Exchange México (MXN)

Realiza conversiones de divisa entre MXN y USD dentro de la plataforma.

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

💡

Diferencia con otros módulos: - Exchange (FX): Movimientos transfronterizos entre divisas fiat (USD/COP/PEN/CLP) con dispersión a cuentas bancarias. - Swap: Conversión de saldo interna entre wallets (COP ↔ USD) sin envío externo. - Exchange MXN: Conversión de activos vía RFQ (MXN ↔ USDT, BTC, etc.) con cotización y ejecución inmediata.

Conceptos Clave

Estados de Conversión

Estado	Descripción
`INITIATED`	Conversión creada, en proceso
`COMPLETED`	Conversión ejecutada exitosamente
`FAILED`	Conversión fallida
`TERMINATED`	Conversión cancelada/terminada

Tipos de Operación (Trade Type)

Tipo	Descripción
`BUY`	Comprar el activo destino usando la moneda origen
`SELL`	Vender el activo origen para recibir la moneda destino

Escenarios de Cotización

Escenario	Dirección	Monto	Descripción
1	Canónica	from_amount	Vender monto exacto de moneda origen
2	Canónica	to_amount	Calcular cuánto origen se necesita para recibir monto destino
3	Inversa	from_amount	Comprar activo destino usando monto exacto de origen
4	Inversa	to_amount	Calcular cuánto origen se necesita para comprar monto destino

Flujo General

Consultar pares disponibles

Obtén los pares de conversión RFQ con GET /exchange/pairs.

(Opcional) Vista previa

Obtén cotización sin ejecutar con POST /exchange/conversions/preview para mostrar tasa y monto al usuario.

Crear conversión

Solicita cotización y ejecuta la conversión con POST /exchange/conversions.

Consultar estado

Verifica el resultado con GET /exchange/conversions/{profile_uuid}/{conversion_identifier}.

Pares Disponibles

Lista los pares de conversión RFQ disponibles. Este endpoint consulta directamente el servicio de conversiones.

Pares de Conversión Disponibles

Autorización

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/pairs

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
from_currency	string	✕	Filtrar por moneda/activo origen (ej. mxn, usdt)
to_currency	string	✕	Filtrar por moneda/activo destino (ej. btc, mxn)

request.json?from_currency=mxn

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/exchange/pairs?from_currency=mxn" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "pairs": [
    { "from_currency": "mxn", "to_currency":  "usdt"},
    { "from_currency": "mxn", "to_currency":  "btc"},
    { "from_currency": "usdt", "to_currency":  "mxn"},
    { "from_currency": "btc", "to_currency":  "mxn"}
  ]
}
}

Conversiones

Vista previa de conversión

Obtiene una cotización RFQ en formato de vista previa sin ejecutar ni persistir la conversión. Útil para mostrar al usuario el monto destino y la tasa antes de confirmar.

Vista previa de conversión

Autorización

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

Endpoint

POSThttps://dev.backend.colurs.co/exchange/conversions/preview

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil del usuario
from_currency	string	✓	Moneda/activo origen (ej. mxn)
to_currency	string	✓	Moneda/activo destino (ej. usdt)
from_amount	decimal	⚠	Monto en moneda origen (enviar from_amount o to_amount)
to_amount	decimal	⚠	Monto en moneda destino (enviar from_amount o to_amount)
trade_type	string	✓	Tipo de operación: 'BUY' o 'SELL'
asset	string	✕	Activo involucrado (ej. usdt, btc)

request.json{
"profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
"from_currency": "mxn",
"to_currency": "usdt",
"from_amount": "10000.00",
"trade_type": "BUY",
"asset": "usdt"
}

Ejemplo cURL

curl -X POST "https://dev.backend.colurs.co/exchange/conversions/preview" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"profile_uuid":"550e8400-e29b-41d4-a716-446655440000","from_currency":"mxn","to_currency":"usdt","from_amount":"10000.00","trade_type":"BUY"}'

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "conversion_identifier": null,
  "from_currency": "mxn",
  "to_currency": "usdt",
  "asset": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "quote_identifier": "quote_xyz",
  "exchange_rate": "17.2343",
  "conversion_status": "INITIATED",
  "quote_created_at": "2026-02-15T14:30:00Z",
  "conversion_created_at": null,
  "conversion_updated_at": null,
  "conversion_scenario": {
    "scenario_number": 1,
    "trade_type": "BUY",
    "interpretation": 
  "Vender monto exacto de moneda origen"}
}
}

Errores Posibles

Código	Error	Descripción
400	BadRequest	Par de conversión no válido o montos inválidos
400	BadRequest	Ambos from_amount y to_amount enviados simultáneamente
500	InternalError	Error al comunicarse con el servicio de cotizaciones

Este endpoint **no crea** la conversión ni descuenta saldo. Solo devuelve la cotización actual. Para ejecutar la conversión usa `POST /exchange/conversions`.

Crear Conversión

Solicita una cotización RFQ y la ejecuta inmediatamente. La conversión se persiste en la base de datos local asociada al profile_uuid.

Crear Conversión

Autorización

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

Endpoint

POSThttps://dev.backend.colurs.co/exchange/conversions

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil del usuario
from_currency	string	✓	Moneda/activo origen (ej. mxn)
to_currency	string	✓	Moneda/activo destino (ej. usdt)
from_amount	decimal	⚠	Monto en moneda origen (enviar from_amount o to_amount)
to_amount	decimal	⚠	Monto en moneda destino (enviar from_amount o to_amount)
trade_type	string	✓	Tipo de operación: 'BUY' o 'SELL'
asset	string	✕	Activo involucrado (ej. usdt, btc)

request.json{
"profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
"from_currency": "mxn",
"to_currency": "usdt",
"from_amount": "10000.00",
"trade_type": "BUY",
"asset": "usdt"
}

Ejemplo cURL

curl -X POST "https://dev.backend.colurs.co/exchange/conversions" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"profile_uuid":"550e8400-e29b-41d4-a716-446655440000","from_currency":"mxn","to_currency":"usdt","from_amount":"10000.00","trade_type":"BUY"}'

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "rate": "17.2343",
  "trade_type": "BUY",
  "scenario_number": 1,
  "conversion_state": "COMPLETED",
  "created_at": 
"2026-02-15T14:30:00Z"}
}

Errores Posibles

Código	Error	Descripción
400	BadRequest	Par de conversión no válido o montos inválidos
400	BadRequest	Ambos from_amount y to_amount enviados simultáneamente
402	InsufficientFunds	Saldo insuficiente para la conversión
500	InternalError	Error al comunicarse con el servicio de conversiones

⚠️

Debes enviar **solo uno** de `from_amount` o `to_amount`. El escenario de cotización se calcula automáticamente según la combinación de dirección y tipo de monto.

Listar Conversiones

Lista todas las conversiones desde la base de datos local, con paginación por cursor.

Listar Conversiones

Autorización

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✕	Filtrar por UUID de perfil
asset	string	✕	Filtrar por activo (ej. usdt, btc)
conversion_state	string	✕	Filtrar por estado: COMPLETED, FAILED, INITIATED, TERMINATED
page_limit	integer	✕	Resultados por página (default: 20, max: 100)
pagination_cursor	string	✕	Cursor opaco de la respuesta anterior para paginación

request.json?conversion_state=COMPLETED&page_limit=10

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/exchange/conversions?conversion_state=COMPLETED&page_limit=10" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "conversions": [
    {
      "conversion_identifier": "conv_abc123xyz",
      "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "from_currency": "mxn",
      "to_currency": "usdt",
      "from_amount": "10000.00",
      "to_amount": "580.25",
      "rate": "17.2343",
      "trade_type": "BUY",
      "conversion_state": "COMPLETED",
      "created_at": 
    "2026-02-15T14:30:00Z"}
  ],
  "pagination_cursor": "eyJpZCI6MTIzfQ==",
  "has_more": true
}
}

💡

Usa el campo `pagination_cursor` de la respuesta como parámetro en la siguiente petición para obtener más resultados.

Listar Conversiones por Usuario

Lista las conversiones de un usuario específico desde la base de datos local. No realiza consultas al servicio externo.

Conversiones por Usuario

Autorización

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions/user/{profile_uuid}

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil del usuario (path param)
asset	string	✕	Filtrar por activo
conversion_state	string	✕	Filtrar por estado: COMPLETED, FAILED, INITIATED, TERMINATED

request.json/exchange/conversions/user/550e8400-e29b-41d4-a716-446655440000?conversion_state=COMPLETED

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/exchange/conversions/user/550e8400-e29b-41d4-a716-446655440000?conversion_state=COMPLETED" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "conversions": [
    {
      "conversion_identifier": "conv_abc123xyz",
      "from_currency": "mxn",
      "to_currency": "usdt",
      "from_amount": "10000.00",
      "to_amount": "580.25",
      "rate": "17.2343",
      "trade_type": "BUY",
      "conversion_state": "COMPLETED",
      "created_at": 
    "2026-02-15T14:30:00Z"}
  ]
}
}

Consultar Conversión

Consulta una conversión específica por su identificador. Busca primero en la base de datos local; si no la encuentra, consulta el servicio de conversiones como fallback.

Consultar Conversión

Autorización

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

Endpoint

GEThttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil del usuario (path param)
conversion_identifier	string	✓	Identificador de la conversión (path param)

Ejemplo cURL

curl -X GET "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "rate": "17.2343",
  "trade_type": "BUY",
  "scenario_number": 1,
  "conversion_state": "COMPLETED",
  "asset": "usdt",
  "created_at": 
"2026-02-15T14:30:00Z"}
}

Errores Posibles

Código	Error	Descripción
404	NotFound	Conversión no encontrada en DB local ni en el servicio externo

💡

Si la conversión no está en la base de datos local, el sistema consulta la el servicio de conversiones automáticamente.

Administrar Conversiones

Actualizar Conversión

Actualiza los campos asset y trade_type de una conversión en la base de datos local. El campo scenario_number se recalcula automáticamente. No llama al servicio externo.

Actualizar Conversión (DB)

Autorización

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

Endpoint

PATCHhttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil (path param)
conversion_identifier	string	✓	Identificador de la conversión (path param)
asset	string	✕	Nuevo activo (ej. usdt, btc)
trade_type	string	✕	Nuevo tipo de operación: 'BUY' o 'SELL'

request.json{
"asset": "btc",
"trade_type": "SELL"
}

Ejemplo cURL

curl -X PATCH "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{"asset":"btc","trade_type":"SELL"}'

Respuesta

response.json

{
"code_transaction": "OK",
"data": {
  "conversion_identifier": "conv_abc123xyz",
  "profile_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "from_currency": "mxn",
  "to_currency": "usdt",
  "from_amount": "10000.00",
  "to_amount": "580.25",
  "trade_type": "SELL",
  "asset": "btc",
  "scenario_number": 3,
  "conversion_state": 
"COMPLETED"}
}

Errores Posibles

Código	Error	Descripción
404	NotFound	Conversión no encontrada

⚠️

Este endpoint solo modifica el registro local. No afecta la conversión ejecutada en el servicio externo.

Eliminar Conversión

Elimina el registro de una conversión de la base de datos local. No llama al servicio externo.

Eliminar Conversión (DB)

Autorización

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

Endpoint

DELETEhttps://dev.backend.colurs.co/exchange/conversions/{profile_uuid}/{conversion_identifier}

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
profile_uuid	uuid	✓	UUID del perfil (path param)
conversion_identifier	string	✓	Identificador de la conversión (path param)

Ejemplo cURL

curl -X DELETE "https://dev.backend.colurs.co/exchange/conversions/550e8400-e29b-41d4-a716-446655440000/conv_abc123xyz" \
-H "Authorization: Bearer [ACCESS_TOKEN]" \
-H "x-api-key: [API_KEY]"

Respuesta

response.json

{
"code_transaction": "OK",
"message": "Conversion deleted successfully",
"data": {}
}

Errores Posibles

Código	Error	Descripción
404	NotFound	Conversión no encontrada

🚫

Esta acción es irreversible. Solo elimina el registro local; la conversión ejecutada en el servicio externo no se revierte.

Campos de Respuesta Comunes

Campo	Tipo	Descripción
`code_transaction`	string	Código de estado de la operación
`conversion_identifier`	string	Identificador único de la conversión
`profile_uuid`	uuid	UUID del perfil del usuario
`from_currency`	string	Moneda/activo origen
`to_currency`	string	Moneda/activo destino
`from_amount`	decimal	Monto en moneda origen
`to_amount`	decimal	Monto en moneda destino
`rate`	decimal	Tasa de cambio aplicada
`trade_type`	string	BUY o SELL
`scenario_number`	integer	Escenario de cotización (1-4)
`conversion_state`	string	Estado de la conversión

Notas Importantes

⚠️

Ejecución inmediata: A diferencia del Exchange FX que separa cotización y ejecución, en Exchange MXN la conversión se cotiza y ejecuta en un solo paso vía RFQ.

💡

Persistencia local: Las conversiones se almacenan localmente. Los endpoints PATCH y DELETE solo modifican la base de datos local y no afectan el estado real de la conversión en el servicio externo.

Exchange Internacional (FX)Swap (Conversión de saldo)