Swap (Conversión de saldo)

Conversión de saldo entre monedas dentro de la app (COP ↔ USD, MXN, BRL). No envía dinero a cuentas bancarias; solo mueve saldo entre tus wallets.

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
USD → MXN, MXN → USD
USD → BRL, BRL → 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.

Paso 1: Crear cotización

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

Endpoint

POST /quote/

Headers

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

Request

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

USD a COP

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

COP a USD

{
  "currency_from": "COP",
  "currency_to": "USD",
  "source_amount": 407731.25,
  "action": "SWAP"
}

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 exitosa (200)

200 OK

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

Campo	Descripción
`id`	ID de la cotización. Usar en `POST /swap/` como `quote_id`.
`rate`	Tasa de cambio aplicada
`source_amount`	Monto en moneda origen
`target_amount`	Monto que recibirás en moneda destino
`fee_amount`, `fee_iva_amount`	Comisiones (si aplican)

💾

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

Paso 2: Ejecutar la conversión

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

Endpoint

POST /swap/

Headers

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

Request

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

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 exitosa (200)

200 OK

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

Pares soportados

Par	Descripción
USD → COP	Dólares a pesos colombianos
COP → USD	Pesos colombianos a dólares
USD → MXN	Dólares a pesos mexicanos
MXN → USD	Pesos mexicanos a dólares
USD → BRL	Dólares a reales
BRL → USD	Reales 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 (FX)Envío entre usuarios (Send)