API de Tilín
Para conectar otro programa —un sistema de facturación, una tienda, el software que le rentas a tus clientes— y que los pagos se confirmen solos.
Todos los ejemplos de este documento son respuestas reales capturadas del servidor, no inventadas. Cámbiale el dominio y funcionan tal cual.
1. Autenticación
Hay dos clases de token y los dos se usan igual; lo que cambia es hasta dónde llegan.
El token de la cuenta
Se saca en Panel ▸ Mi cuenta ▸ Generar token nuevo y se enseña una sola vez: en la base solo queda su huella, así que si se pierde hay que generar otro (el anterior deja de valer en ese momento). Hay uno por cuenta.
Va en cada llamada:
Authorization: Bearer vb_a1b2c3…
Sin token, o con uno inventado, todo responde 401.
Ese token es la cuenta entera. Guárdalo en el servidor, nunca en el navegador ni en una app que instale el cliente: con él se pueden crear cobros, ver el historial y leer los movimientos. Si sospechas que se filtró, genera uno nuevo desde el panel y el viejo muere.
Tokens por programa, atados a una cuenta Nequi
Si conectas más de un programa, o si el negocio tiene varias cuentas Nequi (un local por cada una), ese token no sirve bien: es uno solo, lo abre todo, y cambiarlo tumba a la vez a todo lo que lo estuviera usando.
En Panel ▸ Mi cuenta ▸ Tokens por programa se saca uno para cada integración, y a cada uno se le puede poner una dirección. Un token con dirección:
- cobra siempre a esa cuenta Nequi, aunque el programa mande otra en el cuerpo;
- solo ve los cobros y los movimientos de esa dirección;
- no puede tocar los ajustes de la cuenta, ni los teléfonos, ni emitir más tokens;
- se quita sin que los demás se enteren.
Si pregunta por un cobro de otra dirección, la respuesta es 404 —la misma que para un id que no existe: así no se puede averiguar qué hay al otro lado—. Y si entra por una parte de la API que no sabe filtrar por dirección, 403:
{ "error": "Ese token está limitado a una dirección y no puede usar esta parte de la API." }
Esa lista es cerrada por omisión: lo que se le añada a la API más adelante nace prohibido para estos tokens hasta que se le enseñe a respetar el alcance. Vale para cobrar (/api/charges), leer movimientos (/api/transactions), validar (/api/validate), el QR suelto (/api/qr) y la lista de direcciones (/api/mailboxes).
2. Convenciones
| Formato | JSON en ambos sentidos. En los POST, manda Content-Type: application/json |
| Montos | Números en pesos colombianos. 120000 son ciento veinte mil |
| Fechas | ISO 8601 con zona: 2026-10-07T18:41:08-05:00 |
| Zona horaria | Por omisión la del servidor. Mándala con la cabecera X-Timezone: America/Bogota y las fechas te llegan en esa |
| Errores | Siempre {"error": "explicación en español"}, pensada para poder enseñársela a una persona |
Códigos que vas a ver:
200/201— bien.401— falta el token o no vale.402— tu saldo con el servicio se pasó del límite y los cobros con link están cortados. Recarga y vuelve a intentarlo; elerrordice cuánto debes. Ver Tu saldo con el servicio.404— no existe, o es de otra cuenta (es lo mismo a propósito: así no se puede averiguar qué ids existen).422— los datos no valen; elerrordice por qué.429— demasiados intentos seguidos; espera y reintenta.500— fallo del servidor. Trae una referencia (ref. a3f91c) que el administrador puede buscar en el registro del panel.
3. El flujo normal: cobrar con link
tu software Tilín tu cliente
│ │ │
│ 1. POST /api/charges ──────▶│ │
│◀──── id, url, amount │ │
│ │ │
│ 2. le mandas el url ────────┼────────────────────────────▶│
│ │ 3. abre y paga ◀──────│
│ │◀── llega el correo del banco│
│ 4. GET /api/charges/{id} ──▶│ │
│◀──── status: "pagado" │ │
Paso 1 — crear el cobro
curl -X POST https://tilin.glorycompany.com.co/api/charges \
-H "Authorization: Bearer vb_tu_token" \
-H "Content-Type: application/json" \
-d '{"amount": 120000, "reference": "SUSCRIPCION-OCT", "concept": "Plan mensual", "minutes": 1440}'
{
"id": 1,
"token": "47anrc847vjx6um98crmjm",
"url": "https://tilin.glorycompany.com.co/c/47anrc847vjx6um98crmjm",
"amount": 120000,
"reference": "SUSCRIPCION-OCT",
"concept": "Plan mensual",
"status": "pendiente",
"payload": "00020101021226320014CO.COM.RBM.LLA0410@minegocio…6304EA5A",
"key": "@minegocio",
"anyBank": false,
"requested": 120000,
"bump": 0,
"createdAt": "2026-10-07T18:41:08-05:00",
"expiresAt": "2026-10-08T18:41:08-05:00",
"paidAt": null,
"payer": null,
"payReference": null,
"payBank": null
}
Guarda el id junto a tu factura. Al cliente mándale el url.
Paso 4 — preguntar si ya pagaron
curl https://tilin.glorycompany.com.co/api/charges/1 -H "Authorization: Bearer vb_tu_token"
{
"id": 1,
"status": "pagado",
"amount": 120000,
"reference": "SUSCRIPCION-OCT",
"paidAt": "2026-10-07T18:41:08-05:00",
"payer": "CLIENTE UNO",
"payReference": "M77001122",
"payBank": "Nequi"
}
Cuando status es pagado, el pago entró de verdad: lo confirmó el correo del banco, no el cliente. Ahí tu software ya puede renovar la suscripción.
4. Cuatro cosas que hay que entender antes de programar
El monto puede no ser el que pediste
Si tu cuenta ya tenía otro cobro pendiente por esa misma cifra, al nuevo se le suman uno o dos pesos. La respuesta lo dice: requested es lo que pediste, bump lo que se sumó, amount lo que hay que pagar.
No es un capricho. El correo que manda el banco no trae la referencia que va dentro del QR —está comprobado con pagos reales de Nequi—, así que lo único que llega es el monto, el nombre de quien pagó y una referencia que inventa el banco. Con dos cobros de $120.000 esperando, un pago de $120.000 no se puede atribuir a ninguno de los dos. Con un peso de diferencia, sí.
Usa siempre el amount de la respuesta para mostrárselo al cliente. Si le enseñas el que pediste, pagará la cifra equivocada y el cobro se quedará esperando.
Los cobros caducan
Por omisión a los 20 minutos (se cambia en Panel ▸ Mi cuenta ▸ Cobros con QR, o por cobro con minutes). Un cobro vencido pasa a status: "vencido" y deja de aceptar pagos.
Para una suscripción mensual que mandas por correo, pon algo largo: "minutes": 1440 es un día. Para un cobro de mostrador, déjalo corto.
Una cuenta puede tener varias cuentas Nequi
Cada dirección de correo que el negocio tenga conectada puede llevar su propia llave Bre-B: su propia cuenta Nequi. Un cobro se crea contra una dirección (mailboxId) y eso decide dos cosas: con qué llave sale el QR —a qué cuenta le entra la plata— y qué pago puede cerrarlo. Un pago que entra en el local del norte no cierra un cobro del local del sur, ni aunque el monto cuadre.
Si no mandas mailboxId, el cobro queda sin dirección: sale con la llave de la cuenta y lo puede cerrar un pago que entre por cualquiera de ellas. Con una sola cuenta Nequi eso es lo normal y no hay nada que hacer.
Cada cobro te dice a qué dirección pertenece, que es cómo sabes qué cuenta cobró:
{ "mailboxId": 2, "mailbox": "Local norte" }
Un pago cierra un solo cobro
Un mismo pago no puede cerrar dos cobros, y el pago de una cuenta no cierra el cobro de otra. Además el pago tiene que haber ocurrido mientras el link estaba vivo: uno de ayer no cierra un cobro creado hoy.
5. Referencia
Cobros
| Método | Ruta | Qué hace |
|---|---|---|
POST | /api/charges | Crea un cobro. Devuelve 201 |
GET | /api/charges/{id} | Un cobro y su estado |
GET | /api/charges | El historial |
POST | /api/charges/{id}/cancel | Anula uno pendiente |
POST /api/charges — campos del cuerpo:
| Campo | Obligatorio | Qué es |
|---|---|---|
amount | sí | El monto. Mayor que cero |
reference | no | Tu referencia, hasta 25 caracteres (SUSCRIPCION-OCT). Sale en el panel y en el comprobante |
concept | no | Para qué es, hasta 190 caracteres. Se le enseña al cliente |
minutes | no | Cuánto vive el link. Por omisión, lo configurado en la cuenta |
mailboxId | no | A qué cuenta Nequi se le cobra. Los ids salen de GET /api/mailboxes. Con un token limitado se ignora: cobra siempre a la suya |
GET /api/charges — parámetros opcionales: status (pendiente, pagado, vencido, anulado), limit (hasta 200) y mailbox (el id de una dirección, para ver solo los de un local). Devuelve {"charges": [...]} con lo último primero.
Campos de un cobro:
| Campo | Qué es |
|---|---|
id | El que guardas tú para preguntar después |
token, url | El link que se le manda al cliente |
amount | Lo que hay que pagar (puede traer el ajuste) |
reference, concept | Lo que mandaste al crearlo, tal cual. null si no mandaste nada |
requested, bump | Lo pedido y lo sumado. Solo al crearlo |
status | pendiente · pagado · vencido · anulado |
mailboxId, mailbox | A qué dirección se le cobró: el id y su nombre. null si el cobro es de la cuenta y no de un local |
payload | El contenido del QR, por si lo dibujas tú. Ya lleva el valor dentro |
key | La llave Bre-B que lleva dentro ese código, para ofrecer una transferencia |
anyBank | true si el código lo lee la app de cualquier banco; false si solo Nequi. Ver abajo |
fee | Lo que te costó de comisión del servicio. null mientras no esté pagado, y null siempre si no tienes tarifa |
createdAt, expiresAt, paidAt | Fechas con zona |
payer | Quién pagó, tal como lo manda el banco |
payReference, payBank | Comprobante del banco y de qué banco vino |
Un solo código, y de dónde sale
Hay un payload por cobro y siempre lleva el valor dentro: quien paga escanea y confirma, sin teclear nada. Lo que cambia es quién lo puede leer, y eso lo dice anyBank:
{
"payload": "00020101…",
"key": "@midavivienda",
"anyBank": true
}
Ojo con key: es la llave que lleva dentro ese código, no la que el negocio tenga puesta en su cuenta. Cuando el cobro sale del QR del banco, las dos pueden ser distintas, y la que vale es esta — si alguien transfiere a otra, el dinero entra a otra cuenta y el cobro se queda esperando.
anyBank | De dónde sale | Quién lo lee |
|---|---|---|
true | Del QR de comercio del banco del negocio, con el importe insertado | La app de cualquier banco |
false | Armado con la llave del negocio | Solo Nequi. Los demás responden «código no habilitado» |
Sale true cuando el negocio pegó su QR del banco en el panel, y es lo que hay que querer. Con false, a quien no use Nequi se le ofrece la transferencia Bre-B a key.
Lo que hay que enseñar: el payload, y debajo key con un botón de copiar. La llave es el camino que funciona desde cualquier banco pase lo que pase, así que va visible y no escondida. Es lo que hace la página de /c/{token}, por si prefieres mandar ese link y no montar pantalla.
Esto llegó a documentarse al revés —dos códigos, y que al del banco no se le podía insertar el importe porque rompía la firma de la red—. No lo rompe: la firma del campo 91 no cubre la etiqueta del monto, y está comprobado pagando desde dos bancos distintos. Lo que fallaba era una app de Android desactualizada.
Anular devuelve el cobro ya anulado, o 422 si no estaba pendiente:
{ "error": "Solo se puede anular un cobro que siga pendiente." }
Tu saldo con el servicio
Hay un solo saldo y dos cosas que lo consumen:
- Cada cobro con link que te paguen descuenta una comisión: unos pesos fijos más un porcentaje. Solo se devenga cuando el cobro llega a pagarse — un link que nadie paga no cuesta nada. Los QR al momento (
/api/qr) no descuentan nada. - La cuota del servicio, si la tienes, se carga una vez al mes el mismo día en que te dieron de alta (
monthlyDay).
Pagar es recargar el saldo: no hay una segunda forma de pagar ni un cobro aparte de la suscripción. Y si el saldo se pasa del límite, además de cortarse los cobros con link deja de sonar el aviso en el teléfono.
| Método | Ruta | Qué hace |
|---|---|---|
GET | /api/fees | Tu saldo, tu tarifa y tu extracto |
POST | /api/fees/topup | Prepara una recarga y te devuelve el QR para pagarla |
GET /api/fees — si a tu cuenta no se le cobra nada, responde {"active": false} y ya:
{
"active": true,
"balance": -2900,
"debt": 2900,
"limit": 30000,
"blocked": false,
"fixed": 500,
"percent": 2,
"monthly": 30000,
"monthlyDay": 12,
"suggested": 3000,
"ledger": [
{ "kind": "comision", "amount": -2900, "at": "2026-10-14T09:12:04-05:00", "chargeAmount": 120000 }
]
}
| Campo | Qué es |
|---|---|
balance | Tu saldo. Positivo es saldo a favor; negativo es lo que debes |
debt | Lo que debes, en positivo, para no tener que darle la vuelta al signo |
limit | Hasta cuánto se te fía. null = no se te corta nunca; 0 = prepago puro |
blocked, blockedReason | Si tienes los cobros con link cortados, y el motivo en palabras |
fixed, percent | Tu tarifa por cobro con link, para que puedas rehacer la cuenta de cualquier transacción |
monthly, monthlyDay | La cuota del servicio y el día del mes en que se te carga. 0 y null si no tienes cuota |
suggested | Lo que te proponemos recargar: lo que debes, redondeado hacia arriba |
ledger | Los últimos movimientos: comision, recarga o ajuste |
POST /api/fees/topup con {"amount": 20000} (o sin cuerpo, y usa suggested) devuelve el cobro con el que pagas:
{
"amount": 20000,
"url": "https://tilin.glorycompany.com.co/c/9x2mq…",
"payload": "00020101…",
"anyBank": true,
"expiresAt": "2026-10-15T09:12:04-05:00"
}
Dibuja el payload o manda el url. No hay que confirmar nada: cuando el pago entra, el saldo sube solo, igual que se cierran tus propios cobros con link. Mientras esperas puedes ir preguntando por GET /api/fees y mirar balance.
Pedir dos recargas seguidas por el mismo importe devuelve la misma, no dos. Y si estás cortado, esto sigue funcionando: cortarte el camino para pagar sería absurdo.
Direcciones de cobro
| Método | Ruta | Qué hace |
|---|---|---|
GET | /api/mailboxes | Las direcciones por las que se cobra, con el id de cada una |
Es de donde sacas el mailboxId que le pasas a un cobro:
{
"mailboxes": [
{ "id": 1, "address": "ventas@ejemplo.test", "label": "Ventas", "kind": "imap", "active": true, "hasOwnKey": false },
{ "id": 2, "address": "norte@ejemplo.test", "label": "Local norte", "kind": "imap", "active": true, "hasOwnKey": true }
]
}
Solo salen las que pueden recibir un pago. Si el negocio comparte el servicio con otros, el buzón del que se reparte el correo no es una de ellas y no aparece: ahí no se guarda el pago de nadie, así que un cobro atado a él no lo cerraría nunca.
hasOwnKey dice si esa dirección tiene su propia cuenta Nequi detrás. Si es false, los cobros que le mandes salen con la llave de la cuenta —la misma para todas—, así que ahí da igual cuál elijas. Con un token limitado, esta lista trae solo su dirección.
La página del link (pública, sin token)
| Método | Ruta | Qué hace |
|---|---|---|
GET | /c/{token} | La página que abre quien va a pagar |
GET | /c/{token}/estado | {"status": "pagado"} — lo que consulta esa página |
No lleva token a propósito: la abre un cliente que no tiene cuenta. Lo que la protege es que el identificador es largo y aleatorio. La página solo enseña el monto, el negocio y el código; del comercio no sale nada más.
Si prefieres no usar links
| Método | Ruta | Qué hace |
|---|---|---|
GET | /api/qr | Solo el contenido de un QR, sin guardar nada |
POST | /api/validate | ¿Entró un pago por este monto? |
GET | /api/transactions | Los movimientos |
GET | /api/status | Buzones, última sincronización, conteos |
GET /api/qr?amount=50000&ref=MESA-4 — para enseñar un código en el mostrador:
{
"payload": "00020101021226320014CO.COM.RBM.LLA0410@minegocio…63043CBB",
"key": "@minegocio",
"amount": 50000,
"reference": "MESA-4",
"anyBank": false
}
El dibujo lo hace tu programa con cualquier librería de QR. anyBank dice si lo lee la app de cualquier banco o solo Nequi, igual que en un cobro: ahí está explicado de dónde sale cada uno. No deja rastro: si quieres poder saber después si lo pagaron, usa un cobro.
POST /api/validate — cuando el cliente paga por su cuenta y tú solo compruebas:
curl -X POST https://tilin.glorycompany.com.co/api/validate \
-H "Authorization: Bearer vb_tu_token" -H "Content-Type: application/json" \
-d '{"amount": 50000, "withinMinutes": 60, "orderRef": "FACTURA-9"}'
{ "valid": false, "reason": "No hay un pago sin usar que coincida" }
Con orderRef, el pago encontrado queda marcado como usado por esa factura y no se puede validar dos veces. Es la defensa contra cobrar dos pedidos con el mismo pago.
GET /api/transactions — acepta kind (ingreso, gasto, propio), limit y mailbox (solo los de una dirección):
[{
"id": 1,
"kind": "ingreso",
"date": "2026-10-07T18:41:08-05:00",
"amount": 120000,
"payer": "CLIENTE UNO",
"channel": "Bre-B QR",
"bank": "Nequi",
"reference": "M77001122",
"mailbox": "ventas@ejemplo.test",
"claimed_by": "COBRO-47anrc847vjx6um98crmjm",
"claimed_at": "2026-10-07T18:41:08-05:00"
}]
claimed_by dice si ese pago ya se usó: COBRO-… si cerró un link, o tu orderRef si lo validaste tú.
6. Cada cuánto preguntar
Tilín no llama a tu servidor: hoy no hay avisos salientes. Tu software pregunta.
- Mientras tengas cobros pendientes, cada 30–60 segundos. Una sola llamada a
GET /api/charges?status=pendientete los trae todos, aunque tengas varios abiertos. - Sin cobros pendientes, no preguntes.
- Un cobro vencido ya no va a cambiar: sácalo de tu lista de espera.
Con pocos clientes eso basta y no se nota. Si algún día necesitas confirmación inmediata, lo que hace falta es que Tilín avise a tu servidor; está pendiente de hacer.
7. Ejemplo completo (PHP)
<?php
const TILIN = 'https://tilin.glorycompany.com.co';
const TOKEN = 'vb_tu_token';
function tilin(string $metodo, string $ruta, ?array $cuerpo = null): array
{
$ch = curl_init(TILIN . $ruta);
$cabeceras = ['Authorization: Bearer ' . TOKEN, 'Accept: application/json',
'X-Timezone: America/Bogota'];
if ($cuerpo !== null) {
$cabeceras[] = 'Content-Type: application/json';
}
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $metodo,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => $cabeceras,
CURLOPT_TIMEOUT => 20,
]);
if ($cuerpo !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($cuerpo));
}
$respuesta = json_decode((string) curl_exec($ch), true);
$estado = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($estado >= 400) {
throw new RuntimeException($respuesta['error'] ?? "HTTP {$estado}");
}
return $respuesta ?? [];
}
// Al facturar
$cobro = tilin('POST', '/api/charges', [
'amount' => 120000,
'reference' => 'SUSCRIPCION-' . date('Y-m'),
'concept' => 'Plan mensual',
'minutes' => 1440,
]);
guardarEnMiFactura($cobro['id'], $cobro['url'], $cobro['amount']);
// OJO: $cobro['amount'], no el que pediste
mandarPorWhatsapp($cliente, $cobro['url'], $cobro['amount']);
// Cada minuto, desde un cron
foreach (misFacturasEsperando() as $factura) {
$cobro = tilin('GET', '/api/charges/' . $factura->tilinId);
if ($cobro['status'] === 'pagado') {
renovarSuscripcion($factura, $cobro['payer'], $cobro['payReference']);
} elseif ($cobro['status'] === 'vencido') {
marcarVencida($factura); // y crear otro cobro si quieres reintentar
}
}
8. Antes de salir a producción
PUBLIC_BASE_URLtiene que estar puesto en el.envdel servidor: es de donde sale elurldel cobro. Sin él se usa el dominio por el que entró la petición.- La cuenta necesita su llave Bre-B (Panel ▸ Mi cuenta ▸ Cobros con QR). Sin ella,
POST /api/chargesresponde422. - Dale a cada programa su propio token (Panel ▸ Mi cuenta ▸ Tokens por programa) en vez del de la cuenta. Si el negocio tiene varias cuentas Nequi, átalo a la dirección que le toca: así un error de ese programa no le cobra al local de al lado, y quitarlo no tumba a los demás.
- Prueba el ciclo entero con un cobro de $100 pagado de verdad antes de conectarlo a tus clientes. Es la única forma de ver que el correo del banco llega y se concilia. Con varias cuentas Nequi, uno por cada una: es lo que confirma que cada QR le cobra a la suya.