Gateway da Kobana
Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conciliación en tiempo real por webhook
El Gateway da Kobana es la plataforma de emisión de boletos y Pix de Kobana. Al conectarlo, el Dunning trae los cobros y los clientes emitidos en el Gateway y pasa a cobrarlos — con la línea digitable y el QR Pix ya listos para que el deudor pague directo en el portal.
Requisitos previos
- Una cuenta en el Gateway da Kobana con boletos y/o Pix emitidos.
- Un token de acceso (access token) de la API del Gateway, generado en el panel de Kobana.
- La URL pública del Dunning configurada (necesaria para que el Gateway entregue los webhooks).
Cómo conectar
El Gateway usa clave estática — pegas un token, sin flujo de redirección.
- En el panel de Kobana, genera o copia el token de acceso de la API del Gateway.
- En el Dunning, abre Configuraciones → Integraciones y elige el Gateway da Kobana.
- Pega el token de acceso y selecciona el ambiente (
producciónosandbox). - Haz clic en Conectar. El Dunning valida el token al instante con una llamada de prueba; un token inválido es rechazado antes de guardar.
- Al guardar, el Dunning crea automáticamente los webhooks en el Gateway (clientes y cobros) y hace la primera sincronización.
Mapeo de campos (origen → Dunning)
En cada sincronización, el Dunning traduce los títulos del Gateway al modelo de cobros y a la cartera:
| Campo en el Gateway | Campo en el Dunning |
|---|---|
| Boleto / cobro Pix | Cobro |
amount (valor) | Valor original |
expire_at (vencimiento) | Vencimiento |
created_at | Fecha de emisión |
Línea digitable (line / barcode) | Línea digitable / código de barras |
QR Pix (pix_qrcode / qrcode.emv) | Copia-y-pega Pix |
URL de pago (shorten_url / url) | URL de pago |
document_number / txid | Número del documento |
Status opened / registered / blocked | pending (o overdue si está vencido) |
Status overdue / chargeback | overdue |
Status paid | paid (baja + salida de la regla) |
Status canceled / expired | cancelled |
Cliente (customer_id / payer) | Persona en la cartera |
| CPF/CNPJ del cliente | Documento de la persona |
| Nombre del cliente | Nombre de la persona |
Los boletos aún en generación (o con falla de generación) no tienen status cobrable y son omitidos hasta quedar listos.
Un chargeback/reverso de un boleto o Pix ya pagado reabre el cobro (overdue) y lo hace reiniciar la regla desde el inicio, reenviando los avisos — el mismo comportamiento de reverso descrito en Ciclo de vida.
Conciliación por webhook
El gran diferencial del Gateway es la conciliación en tiempo real. Cuando un boleto o un Pix es pagado, el Gateway dispara un webhook (bank_billet.paid, pix.paid) y el Dunning da de baja al instante: el cobro se marca como pagado y sale de la regla de inmediato — el deudor que acaba de pagar no recibe el próximo mensaje de cobranza. Cancelación, vencimiento y registro del boleto también llegan por webhook.
Como complemento a la conciliación en tiempo real, el Dunning aún hace un pull activo de los boletos y Pix en la sincronización — automática (cada 60 min por defecto) o manual — para cubrir cualquier evento que no haya llegado por webhook. Así, aunque un webhook se pierda, el cobro queda consistente en la próxima sincronización.
Qué no hace / limitaciones
- No emite boletos ni Pix. La emisión sigue en el Gateway; el Dunning solo cobra lo que ya fue emitido.
- No escribe de vuelta en el Gateway. Es solo lectura (pull) — dar de baja o cancelar en el Dunning no altera el título en el Gateway.
- Sin webhook, hay retraso. Si el webhook falla, el cambio aparece solo en el próximo ciclo de sincronización (hasta 60 min por defecto).
Cómo desconectar o reconfigurar
Rehaz el setup en cualquier momento para cambiar el token o el ambiente — la reconfiguración recrea los webhooks cuando es necesario. Para rotar la clave, genera un nuevo token en el panel de Kobana y pégalo en el Dunning; el token antiguo deja de usarse.
Solución de problemas
- La sincronización está desactualizada. Revisa el intervalo configurado (por defecto 60 min) y haz clic en Sincronizar ahora para forzar un pull inmediato.
- Un pago no dio de baja. Verifica en el log de integración si el webhook
bank_billet.paid/pix.paidllegó; si no, el pull de la próxima sincronización lo regulariza. Confirma también que la URL pública del Dunning esté accesible para el Gateway. - Un cliente no apareció. El sync de clientes corre junto con el de cobros; un cliente sin título todavía no se vuelve cobro, pero la persona se crea cuando se sincroniza su primer boleto/Pix.
- Un cobro aparece duplicado. No debería: el Dunning deduplica por
externalId(kobana:bank_billet:{id}/kobana:pix:{id}). Cobros con orígenes distintos (ej.: importados a mano) pueden coexistir — verifica el origen de cada uno. - La conexión se cayó / token inválido. Genera un nuevo token en el panel de Kobana y reconecta.
Seguridad
El token de acceso está cifrado en reposo y nunca es devuelto por la API. Los webhooks creados en el Gateway reciben un secret propio, usado para validar la firma de cada entrega — el Dunning solo procesa eventos que comprobadamente vinieron del Gateway.