Exchange Internacional (FX)

Realiza conversiones de divisa internacional entre USD y COP.

Todos los endpoints requieren autenticación con Authorization: Bearer [TOKEN] y x-api-key.

Visión General

¿Qué es Exchange?

El módulo Exchange en Colurs permite:

Obtener cotizaciones FX entre pares de monedas
Ejecutar movimientos transfronterizos con dispersión automática a cuentas bancarias
Calcular tasas de cambio con comisiones personalizadas por usuario

Comportamiento

Síncrono: Creación y consulta de cotizaciones (respuesta inmediata)
Asíncrono: Ejecución de movimientos transfronterizos (confirmación cuando el movimiento cambia de estado)

Monedas Soportadas

Pares disponibles

El sistema soporta varios pares de monedas en formato origen/destino (ej: usd/cop, cop/usd).

Moneda Origen	Monedas Destino
USD	COP
COP	USD

Restricciones

Monto mínimo: 50 USD o equivalente en la moneda origen
Horarios: Por defecto solo en horario hábil (lunes–viernes). Con off_market: true se permite operar 24/7

Flujo General

Obtener cotización FX

Solicita una cotización con POST /v2/exchange/quotes/. Válida 3 minutos.

(Opcional) Previsualizar

Consulta el detalle con GET /v2/exchange/quotes/{quote_uuid}/ o .../preview/.

Obtener cuenta bancaria

Usa GET /list_third_party_banks/?country=CO (o el país correspondiente) para el destino.

Iniciar movimiento

Ejecuta con POST /v2/exchange/initiate/ usando la cotización y la cuenta bancaria.

Recibir confirmación

El sistema notifica cuando el movimiento está completed y se realiza la dispersión automática.

Cotizaciones

Solicitar cotización FX

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POST/v2/exchange/quotes/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
currency_pair	string	✓	Par de monedas (ej: usd/cop)
source_amount	decimal	⚠	Monto en moneda origen (uno de source_amount o destination_amount)
destination_amount	decimal	⚠	Monto en moneda destino
type	string	✕	static_quote (default) o rolling_quote
off_market	boolean	✕	Permitir operación 24/7 (default: false)

request.json{
"currency_pair": "usd/cop",
"source_amount": 100
}

Respuesta

response.json

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"currency_pair": "usd/cop",
"source_currency": "usd",
"destination_currency": "cop",
"source_amount": 100.00,
"destination_amount": 407731.25,
"fx_rate": 4077.3125,
"status": "pending",
"is_valid": true,
"valid_until": "2026-02-03T10:03:00Z",
"created_at": 
"2026-02-03T10:00:00Z"}

Errores Posibles

Código	Error	Descripción
400	Bad Request	Monto mínimo no cumplido ($50 USD o equivalente)
400	Bad Request	Ambos source_amount y destination_amount enviados
400	Bad Request	Mercado cerrado (fuera de horario y off_market=false)
502	Bad Gateway	Error al procesar la cotización

⏱️

La cotización expira en 3 minutos. Solo la más reciente del par puede usarse para iniciar un movimiento.

Obtener cotización por UUID

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/v2/exchange/quotes/{quote_uuid}/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"currency_pair": "usd/cop",
"source_amount": 100.00,
"destination_amount": 407731.25,
"status": "pending",
"is_valid": true,
"valid_until": 
"2026-02-03T10:03:00Z"}

Errores Posibles

Código	Error	Descripción
404	Not Found	Cotización no encontrada

Listar cotizaciones

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/v2/exchange/quotes/list/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

[
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "currency_pair": "usd/cop",
  "source_amount": 100.00,
  "destination_amount": 407731.25,
  "status": 
"pending"}
]

Última cotización válida

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/v2/exchange/quotes/last/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"currency_pair": "usd/cop",
"source_amount": 100.00,
"destination_amount": 407731.25,
"is_valid": true
}

Pares de monedas disponibles

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

GET/v2/exchange/currency-pairs/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Respuesta

response.json

{
"currency_pairs": [
  "usd/cop", "usd/mxn", "usd/pen", "usd/clp",
  "cop/usd", "cop/mxn", "cop/pen", "cop/clp",
  "mxn/cop", "mxn/usd", "mxn/pen", "mxn/clp",
  "pen/usd", "pen/mxn", "pen/cop", "pen/clp",
  "clp/usd", "clp/mxn", "clp/pen", 
"clp/cop"]
}

Movimientos Transfronterizos

Iniciar movimiento

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POST/v2/exchange/initiate/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

Request Body

Campo	Tipo	Requerido	Descripción
quote_id	UUID	✓	UUID de la cotización válida
source_account_id	string	✓	ID de cuenta origen
destination_account_id	string	✓	ID de cuenta destino
bank_account_id	int	✓	ID de cuenta bancaria del usuario (ThirdPartyBankAccount)
destination_description	string	✕	Descripción del movimiento
external_id	string	✕	ID externo para tracking

request.json{
"quote_id": "550e8400-e29b-41d4-a716-446655440000",
"source_account_id": "acc_src_123",
"destination_account_id": "acc_dst_456",
"bank_account_id": 85
}

Respuesta

response.json

{
"sale_crypto_id": "123",
"quote_id": 
"456"}

Errores Posibles

Código	Error	Descripción
400	Bad Request	La cotización ha expirado o ya fue utilizada
404	Not Found	Cotización no encontrada
502	Bad Gateway	Error al procesar el movimiento

Ejecutar dispersión manual

Autorización

Se requieren el header x-api-key y Authorization: Bearer <token>.

Endpoint

POST/v2/exchange/execute/

Headers Requeridos

Content-Type: application/jsonAccept: application/jsonx-api-key: [API_KEY]Authorization: Bearer [ACCESS_TOKEN]

🔧

Uso interno o casos especiales. El flujo estándar realiza la dispersión automática al completarse el movimiento.

Estados del Movimiento

Estado	Descripción
`initiated`	Movimiento iniciado
`processing`	En proceso
`completed`	Completado → se crea dispersión automática
`rejected`	Rechazado
`failed`	Fallido
`returned`	Devuelto
`canceled`	Cancelado

Cómo hacer un intercambio Exchange México (MXN)