Envío de saldo entre usuarios (Send)

Transferencias P2P entre usuarios Colurs: envía saldo a otro usuario por username o por ID, con o sin comisión según el canal.

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

Visión General

Tipos de envío

Tipo	Descripción
Send clásico	Envío por username del destinatario. Validaciones completas (KYC, balance, límites).
Fast Send	Envío por ID de usuario. Opción de estimar costos antes. Canales con o sin comisión.
Envío múltiple	Estimar costos para enviar a varios destinatarios a la vez.

Send clásico

Crear un envío indicando el username del destinatario. El sistema valida KYC, balance suficiente y límites (para COP).

Flujo

Validar destinatario

El destinatario se identifica por to_user (username). Debe existir y estar activo.

Crear envío

POST /send/ con monto, moneda y descripción opcional.

Proceso interno

Se descuenta (monto + fees) del remitente, se acredita el monto al destinatario, se actualiza límite de balance si aplica y se envía notificación.

Crear envío (POST)

Endpoint

POST /send/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`to_user`	string	✅	Username del usuario destinatario
`amount`	decimal	✅	Monto a enviar (debe ser > 0)
`currency_code`	string	❌	Código de moneda (default: `COP`)
`latitude`	string	❌	Latitud GPS (default: `0000`)
`longitude`	string	❌	Longitud GPS (default: `0000`)
`description`	string	❌	Descripción del envío

request.json

{
  "to_user": "+573001234567",
  "amount": 50000,
  "currency_code": "COP",
  "description": "Pago por servicio"
}

curl -X POST "https://api.colurs.co/send/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "to_user": "+573001234567",
    "amount": 50000,
    "currency_code": "COP"
  }'

Respuesta exitosa (200)

200 OK

{
  "to_user": "+573001234567",
  "from_user": "+573009876543",
  "created": true,
  "pk": 12345,
  "date": "2026-02-03T10:00:00Z",
  "amount": 50000.00
}

Validaciones

Usuario remitente activo para envíos (no bloqueado)
Perfil origen y destino existentes
Usuario con validación KYC completa
Monto mayor a 0
Balance suficiente (monto + fees)
Para COP: destinatario no debe exceder límite de balance
No auto-envío (origen ≠ destino)

Errores posibles

Código	Causa
`403`	Usuario bloqueado para envíos o sin validación KYC
`404`	Perfil origen o destino no existe
`400`	`BALANCE_INSUFFICIENT` — Saldo insuficiente
`400`	`LIMIT_BALANCE` — Destinatario excede límite de balance
`400`	`USER_DOES_NOT_SAME` — Intento de auto-envío
`400`	`AMOUNT_NOT_ZERO` — Monto debe ser mayor a 0
`400`	`OPERATION_INVALID` — Operación no permitida
`400`	`UNABLE_TO_CREATE_SEND` — Error al crear envío

Listar envíos (GET)

Obtiene los envíos donde el usuario es remitente o destinatario.

Endpoint

GET /send/

Headers

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

Respuesta (200)

Lista de envíos (formato según serializer ListSend).

Fast Send (envío rápido)

Envío por ID de usuario con opción de estimar costos antes de ejecutar. Soporta canales con y sin comisión.

Canales de envío

Canal	Descripción
COLURS	Envío entre usuarios Colurs. Sin comisión (fee = 0).
DALE	Envío con comisiones aplicadas. Para COP puede incluir GMF (Gravamen a los Movimientos Financieros).

Estimar Fast Send

Calcula monto total a descontar (monto + fees) y, si aplica, GMF. No ejecuta el envío.

Endpoint

POST /send/fast/estimate/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`amount`	decimal	✅	Monto a enviar
`currency`	string	✅	Código de moneda (ej: `COP`, `USD`)
`to_user`	int	❌	ID del usuario destinatario (opcional; si se envía, puede incluirse `full_name` en la respuesta)
`send_channel`	string	✅	Canal: `COLURS` o `DALE`
`is_for_quote`	boolean	✅	`true` solo cotización, `false` para ejecutar después

COLURS (sin fees)

{
  "amount": 50000,
  "currency": "COP",
  "send_channel": "COLURS",
  "is_for_quote": true
}

Con fees (DALE)

{
  "amount": 50000,
  "currency": "COP",
  "to_user": 42,
  "send_channel": "DALE",
  "is_for_quote": true
}

curl -X POST "https://api.colurs.co/send/fast/estimate/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "COP",
    "send_channel": "COLURS",
    "is_for_quote": true
  }'

Respuesta (200)

200 OK

{
  "result": {
    "amount": 50000.00,
    "fee_amount": 1000.00,
    "fee_iva_amount": 190.00,
    "payed_amount": 51190.00,
    "gmf_amount": 200.00,
    "full_name": "Juan Pérez"
  }
}

Para canal COLURS: fee_amount y fee_iva_amount son 0, payed_amount = amount. Para COP en otros canales puede incluirse gmf_amount.

Ejecutar Fast Send

Crea el envío y, si el canal es COLURS, ejecuta la transferencia de saldo de inmediato y envía notificación al destinatario.

Endpoint

POST /send/fast/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`to_user`	int	✅	ID del usuario destinatario
`amount`	decimal	✅	Monto a enviar
`currency`	string	✅	Código de moneda
`send_channel`	string	✅	`COLURS` o `DALE`
`ip`	string	✅	IP del cliente
`latitude`	string	❌	Latitud GPS
`longitude`	string	❌	Longitud GPS
`description`	string	❌	Descripción del envío

request.json

{
  "to_user": 42,
  "amount": 50000,
  "currency": "COP",
  "send_channel": "COLURS",
  "ip": "192.168.1.1",
  "latitude": "4.60971",
  "longitude": "-74.08175",
  "description": "Reembolso"
}

curl -X POST "https://api.colurs.co/send/fast/" \
  -H "Authorization: Bearer [TOKEN]" \
  -H "x-api-key: [API_KEY]" \
  -H "Content-Type: application/json" \
  -d '{
    "to_user": 42,
    "amount": 50000,
    "currency": "COP",
    "send_channel": "COLURS",
    "ip": "192.168.1.1"
  }'

Respuesta exitosa (201)

201 CREATED

{
  "message": "OK",
  "data": {
    "id": 12345,
    "currency": "COP",
    "fee_amount": 1000.00,
    "fee_iva_amount": 190.00,
    "amount": 50000.00,
    "payed_amount": 51190.00
  }
}

Si el canal es COLURS, el saldo se transfiere al instante y el destinatario recibe una notificación push.

Errores posibles

Código	Causa
`400`	`BalanceInsufficient` — Saldo insuficiente
`404`	`ToUserNotExist` / `ProfileDoesNotExist` — Destinatario no existe
`400`	`ToUserDoesNotAllowBlank` — to_user requerido en ejecución
`404`	Fee o configuración no encontrada

Envío múltiple (estimación)

Calcula el costo total para enviar a varios destinatarios en una sola operación. Útil para nóminas o pagos masivos.

Endpoint

POST /send/multiple/estimate/

Headers

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

Request

Campo	Tipo	Requerido	Descripción
`profiles`	array	✅	Lista de objetos: `profile_id`, `amount`, `send_channel`
`currency`	string	✅	Moneda común para todos los envíos
`is_for_quote`	boolean	✅	Si es solo cotización

Ejemplo

request.json

{
  "profiles": [
    { "profile_id": 10, "amount": 100000, "send_channel": "COLURS" },
    { "profile_id": 11, "amount": 50000, "send_channel": "DALE" }
  ],
  "currency": "COP",
  "is_for_quote": true
}

Respuesta (200)

Objeto con el desglose total estimado (amount, fee_amount, fee_iva_amount, payed_amount según la lógica de múltiple send).

📊

Consulta los endpoints de Balance para verificar saldo antes de crear envíos. Para Send clásico en COP se valida además el límite de balance del destinatario.

Swap (Conversión de saldo)Cuentas bancarias