Swap (Conversión de saldo)

Convierte saldo de forma instantánea entre las diferentes wallets del usuario.

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

🔄

Diferencia con Exchange (FX): Exchange es para movimientos transfronterizos (cotizar y enviar a banco). Swap es para convertir saldo interno entre tus monedas en Colurs.

Visión General

¿Qué es Swap?

El módulo Swap permite convertir saldo de una moneda a otra dentro de tu cuenta Colurs:

USD → COP, COP → USD

El saldo se descuenta de la moneda origen y se acredita en la moneda destino en tu wallet.

Dos modos de conversión

Modo	Uso típico	Comportamiento
SWAP	Usuarios naturales	Conversión inmediata. Se descuenta y acredita al instante en wallet principal (MAIN).
QUOTE	Usuarios jurídicos	Requiere aprobación del operador. Se reserva en wallet de cotización (QUOTATION) y al aprobar se acredita.

Flujo General

Crear cotización

Obtén la tasa y el monto destino con POST /quote/ (acción SWAP o QUOTE).

Ejecutar la conversión

Confirma la operación con POST /swap/ usando el quote_id del paso 1.

Para SWAP la conversión se aplica al instante. Para QUOTE el saldo queda reservado hasta que un operador apruebe la cotización.

Tasa de cambio

Obtiene la tasa entre dos monedas fiat (COP ↔ USD) para la acción SWAP.

POST /exchange_rate/

Body: currency_from (ej. COP, USD), currency_to (ej. USD, COP), source_amount (número), action: “SWAP”.

Obtiene la tasa de cambio y el monto resultante para la conversión. No ejecuta la operación.

Paso 1: Crear cotización

Autorización

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

Endpoint

POSThttps://api.colurs.co/quote/

Headers Requeridos

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

Request Body

Campo	Tipo	Requerido	Descripción
currency_from	string	✓	Moneda origen: USD, COP
currency_to	string	✓	Moneda destino: COP, USD
source_amount	number	✓	Monto a convertir en la moneda origen
action	string	✓	SWAP (inmediato) o QUOTE (requiere aprobación)

request.json{
"currency_from": "USD",
"currency_to": "COP",
"source_amount": 100000,
"action": "SWAP"
}

Ejemplo cURL

curl -X POST "https://api.colurs.co/quote/" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "currency_from": "USD",
  "currency_to": "COP",
  "source_amount": 100000,
  "action": "SWAP"
}'

Respuesta

response.json

{
"message": "OK",
"data": {
  "id": 688,
  "user": "colurs@colurs.io",
  "currency_from": "USD",
  "currency_to": "COP",
  "rate": 4077.3125550239233,
  "fee_amount": 0.0,
  "fee_iva_amount": 0.0,
  "source_amount": 100000.0,
  "target_amount": 407731250.0,
  "total_paid": 100000.0
}
}

💾

Guarda el `id` de la cotización para el siguiente paso. La cotización debe usarse con la misma `action` (SWAP o QUOTE).

Ejecuta la conversión usando el ID de la cotización creada en el paso 1.

Paso 2: Ejecutar conversión

Autorización

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

Endpoint

POSThttps://api.colurs.co/swap/

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	integer	✓	ID de la cotización (paso 1)
action	string	✓	Misma acción que en la cotización: SWAP o QUOTE
ip	string	✓	IP del cliente
latitude	string	✓	Latitud GPS
longitude	string	✓	Longitud GPS

request.json{
"quote_id": 688,
"action": "SWAP",
"ip": "192.168.1.1",
"latitude": "4.60971",
"longitude": "-74.08175"
}

Ejemplo cURL

curl -X POST "https://api.colurs.co/swap/" \
-H "Authorization: Bearer [TOKEN]" \
-H "x-api-key: [API_KEY]" \
-H "Content-Type: application/json" \
-d '{
  "quote_id": 688,
  "action": "SWAP",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175"
}'

Respuesta

response.json

{
"message": "OK",
"data": {
  "id": 1688,
  "user": "colurs@colurs.io",
  "currency_from": "USD",
  "currency_to": "COP",
  "rate": 4077.3125550239233,
  "fee_amount": 0.0,
  "fee_iva_amount": 0.0,
  "source_amount": 100000.0,
  "target_amount": 407731250.0
}
}

Con SWAP el saldo se actualiza de inmediato. Con QUOTE el monto queda reservado hasta la aprobación del operador.

Fast swap (conversión rápida)

Crea un ID para una conversión rápida (usado en flujos como UMA cuando aplica).

POST /fast_swap/

Body: currency_from_code (ej. COP), currency_to_code (ej. USD).

Pares soportados

Par	Descripción
USD → COP	Dólares a pesos colombianos
COP → USD	Pesos colombianos a dólares

Las tasas se actualizan periódicamente por el sistema.

Proceso interno (resumen)

SWAP (inmediato)

Se descuenta el saldo de la moneda origen en la wallet principal (MAIN).
Se acredita el saldo en la moneda destino en la wallet principal (MAIN).
Se registran las comisiones en la wallet de Colurs.

QUOTE (con aprobación)

Se descuenta el saldo de la moneda origen en la wallet de cotización (QUOTATION).
Se espera la aprobación del operador.
Al aprobar, se acredita el saldo en la moneda destino en la wallet de cotización (QUOTATION).

Cada conversión genera movimientos de balance con motivo SWAP.

📊

Puedes consultar tu balance por moneda con los endpoints de Balance para verificar saldos antes y después de la conversión.

Exchange México (MXN)Cómo gestionar cuentas bancarias