Exchange (FX / Conversión de Monedas)

Sistema de cotización y conversión de divisas para obtener tasas en tiempo real y ejecutar movimientos transfronterizos.

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 vía webhook)

Los webhooks notifican los cambios de estado del movimiento: initiated, processing, completed, rejected, failed, returned, canceled.

Monedas Soportadas

Pares disponibles

El sistema soporta 25 pares de monedas en formato origen/destino (ej: 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

Cotizaciones

Solicitar cotización FX

Obtiene una cotización válida por 3 minutos. Solo la cotización más reciente puede usarse para iniciar un movimiento.

Endpoint

POST /v2/exchange/quotes/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Request

{
  "currency_pair": "usd/cop",
  "source_amount": 100
}

curl -X POST "https://api.colurs.co/v2/exchange/quotes/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{"currency_pair": "usd/cop", "source_amount": 100}'

Respuesta exitosa (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "cobre_quote_id": "qt_abc123",
  "quote_type": "static_quote",
  "currency_pair": "usd/cop",
  "source_currency": "usd",
  "destination_currency": "cop",
  "source_amount": 100.00,
  "destination_amount": 407731.25,
  "fx_rate": 4077.3125,
  "colurs_fx": 4036.2344,
  "fees_breakdown": {
    "spread": 0.0050
  },
  "status": "pending",
  "is_last_quote": true,
  "off_market": false,
  "is_valid": true,
  "is_expired": false,
  "valid_until": "2026-02-03T10:03:00Z",
  "created_at": "2026-02-03T10:00:00Z"
}

Errores posibles

Obtener cotización por UUID

Consulta los detalles de una cotización por su UUID.

Endpoint

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

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

Mismo formato que la creación de cotización.

Errores

Listar cotizaciones

Lista las cotizaciones del usuario.

Endpoint

GET /v2/exchange/quotes/list/

Parámetros query

Respuesta (200)

Array de objetos con el mismo formato que una cotización individual.

Última cotización válida

Obtiene la última cotización válida (no expirada, no usada) para un par.

Endpoint

GET /v2/exchange/quotes/last/?currency_pair=usd/cop

Parámetros query

Respuesta (200)

Objeto de cotización o 404 si no hay cotización válida.

Pares de monedas disponibles

Lista todos los pares de monedas soportados.

Endpoint

GET /v2/exchange/currency-pairs/

Headers

Authorization: Bearer [ACCESS_TOKEN]
x-api-key: [API_KEY]
Accept: application/json

Respuesta (200)

{
  "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

Crea un movimiento transfronterizo usando una cotización FX válida. Al completarse, el sistema realiza la dispersión automática a la cuenta bancaria indicada.

Endpoint

POST /v2/exchange/initiate/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Request

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

curl -X POST "https://api.colurs.co/v2/exchange/initiate/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "550e8400-e29b-41d4-a716-446655440000",
    "source_account_id": "acc_src_123",
    "destination_account_id": "acc_dst_456",
    "bank_account_id": 85
  }'

Respuesta exitosa (201)

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

Errores posibles

Ejecutar dispersión manual

Para casos especiales, permite crear una dispersión manual asociada a un movimiento transfronterizo.

Endpoint

POST /v2/exchange/execute/

Headers

Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json
x-api-key: [API_KEY]

Estados del Movimiento

Webhooks

El sistema envía notificaciones de cambio de estado para movimientos transfronterizos. Debes configurar una URL en tu integración para recibir estos eventos.

Eventos soportados

• initiated — Movimiento iniciado
• processing — En proceso
• completed — Completado (dispersión automática)
• rejected — Rechazado
• failed — Fallido
• returned — Devuelto
• canceled — Cancelado

Seguridad

• Se verifica la firma del webhook mediante el header correspondiente.
• Solo se procesan eventos de tipo movimiento transfronterizo.