API pública
La API de Binkio te deja operar tu cuenta desde tu propio sistema: consultar saldos y movimientos, crear cobros y recibir avisos cuando se pagan — sin que nadie tenga que entrar al panel.
https://api.binkio.com/v1
La referencia completa, con cada endpoint, sus parámetros y sus errores, está publicada y se genera del propio código:
- Referencia navegable
- Documento OpenAPI — para generar un cliente en tu lenguaje
Esta página cubre lo transversal: lo que aplica a todas las llamadas y que no cabe en la ficha de ningún endpoint concreto.
:::info Sólo para cuentas de empresa Las credenciales de API están disponibles para personas morales con la verificación de empresa (KYB) aprobada. Si tu cuenta es de persona física, la sección de credenciales no aparece en el panel. :::
Autenticación
Cada llamada lleva el secreto de tu credencial en la cabecera Authorization:
Authorization: Bearer bk_live_sec_7f3a…
El secreto se muestra una sola vez, al crear la credencial o al rotarla. No lo podemos recuperar: si lo pierdes, rota la credencial y despliega el nuevo.
curl https://api.binkio.com/v1/ping \
-H "Authorization: Bearer bk_live_sec_7f3a…"
GET /v1/ping es la forma de comprobar de punta a punta que tu credencial
funciona, contra qué entorno estás pegando y qué alcances tiene — sin mover un
peso. Es el primer sitio donde mirar cuando algo no responde como esperas.
Alcances
Una credencial sólo puede hacer aquello para lo que la emitiste. Los alcances se eligen al crearla y no cambian solos:
| Alcance | Qué habilita |
|---|---|
balances:read | Leer los saldos de la cuenta por activo |
transactions:read | Leer el histórico de movimientos y su detalle |
links:read | Consultar enlaces de pago y su estado |
links:write | Crear, modificar y cancelar enlaces de pago |
qr:read | Consultar los QR de mostrador y sus cobros |
qr:write | Crear y administrar QR de mostrador |
logs:read | Leer el registro de tus llamadas a la API |
webhooks:manage | Registrar y administrar los destinos de tus avisos |
Emite una credencial por integración, con lo mínimo que necesite. Una
terminal de mostrador se lleva qr:write y nada más: si esa terminal se
compromete, el daño queda acotado a lo que esa credencial podía hacer. Una sola
credencial con todos los alcances repartida por tres sistemas es una credencial
que no puedes revocar sin tumbar los tres.
También puedes restringir una credencial a un conjunto de direcciones IP.
Idempotencia
Toda llamada que crea o modifica algo acepta la cabecera Idempotency-Key:
curl -X POST https://api.binkio.com/v1/payment_links \
-H "Authorization: Bearer bk_live_sec_7f3a…" \
-H "Idempotency-Key: pedido-4821" \
-H "Content-Type: application/json" \
-d '{"amount":"1500.25","currency":"MXNB","description":"Pedido 4821"}'
Si repites la llamada con la misma clave, te devolvemos la respuesta original
en lugar de crear un segundo cobro, y la marcamos con Idempotent-Replay: true.
Úsala siempre que crees algo. Una petición que se corta por un tiempo de espera agotado pudo haberse ejecutado igualmente: sin clave de idempotencia, tu reintento crea un cobro duplicado.
La clave vive 24 horas y va atada al cuerpo de la petición: reutilizarla con un cuerpo distinto es un error, no un reemplazo silencioso.
Límites
Cada credencial tiene su propio límite. Las respuestas correctas traen tres cabeceras para que puedas autorregularte en vez de descubrir el tope a golpes:
| Cabecera | Qué dice |
|---|---|
RateLimit-Limit | Tu tope por minuto |
RateLimit-Remaining | Lo que te queda en la ventana actual |
RateLimit-Reset | Segundos hasta que se reinicie |
Pasado el tope recibes un 429. Espera lo que diga RateLimit-Reset antes de
reintentar.
Errores
Todos los errores tienen la misma forma:
{
"error": {
"type": "invalid_request",
"code": "insufficient_balance",
"message": "No hay saldo suficiente para esta operación.",
"param": "amount",
"request_id": "req_9f2a4c8b7e1d3a5f"
}
}
Ramifica sobre code, nunca sobre message. El code es parte del
contrato; el message está escrito para que una persona lo entienda y puede
cambiar de redacción.
El request_id viaja en toda respuesta, correcta o no, y también en la
cabecera X-Request-Id. Es el identificador con el que se abre un ticket:
guárdalo en tus registros.
Paginación
Los listados devuelven un objeto list y se recorren por cursor:
{
"object": "list",
"data": [ /* … */ ],
"has_more": true,
"next_cursor": "eyJ2IjoxLCJ…"
}
Repite la llamada pasando next_cursor en el parámetro cursor mientras
has_more sea true. El cursor es opaco: no lo interpretes ni lo fabriques,
pásalo tal cual.
Registro de llamadas
GET /v1/request_logs te devuelve tus propias llamadas: qué pediste, qué
respondimos, cuándo, desde qué IP y con qué credencial.
Es el primer sitio donde mirar antes de abrir un ticket. Si tu llamada no aparece ahí, no nos llegó — y el problema está entre tu servidor y nosotros, no en la API.
Y para enterarte sin preguntar
Consultar la API en bucle para ver si ya te pagaron funciona, pero es caro y lento. Registra un destino de webhooks y te avisamos nosotros en cuanto pasa.