Financeiro Inteligente
Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda
El Financeiro Inteligente es el producto de gestión financiera de Kobana, con cuentas por cobrar y registro de personas. Conectado al Dunning, alimenta la regla con los recibibles abiertos — los clientes y los títulos entran automáticamente en tu operación de cobranza.
Requisitos previos
- Una cuenta en el Financeiro Inteligente con personas y cuentas por cobrar.
- Un token de acceso (access token) de la API del Financeiro Inteligente.
Cómo conectar
:::note Sin pantalla dedicada en el panel (todavía)
Hoy solo el Gateway de Kobana tiene una pantalla de conexión lista en el panel. Para este ERP, la conexión se hace por la API (rutas /api/v1/integrations/...) — los pasos de abajo describen el flujo de autorización; la pantalla self-service equivalente en el panel está en el roadmap.
:::
El Financeiro Inteligente usa clave estática — pegas un token, sin redirección.
- En el panel del Financeiro Inteligente, copia el token de acceso.
- En el Dunning, abre Configuraciones → Integraciones y elige el Financeiro Inteligente.
- Pega el token de acceso y selecciona el ambiente (
producciónosandbox). - Haz clic en Conectar. El Dunning valida el token con una llamada de prueba; un token inválido es rechazado antes de guardar.
- La primera sincronización corre justo después de conectar; las siguientes ocurren automáticamente.
Mapeo de campos (origen → Dunning)
| Campo en el Financeiro Inteligente | Campo en el Dunning |
|---|---|
| Cuenta por cobrar (receivable) | Cobro |
amount | Valor original |
nominal_amount | Valor actual |
ticket_amount (liquidado en el banco) | Valor pagado |
due_date | Vencimiento |
document_date / created_at | Fecha de emisión |
payment_date | Fecha del pago |
document_number / document | Número del documento |
description (+ nº de la cuota) | Descripción |
payment_method_kind (bank_billet→boleto, pix→pix, credit_card, ted→transfer…) | Medio de pago |
Status pending | pending (o overdue si está vencida) |
Status received | paid (baja + salida de la regla) |
Status cancelled | cancelled |
| Persona (cliente) | Persona en la cartera |
document_number, name, legal_name | Documento, nombre, razón social |
emails, phones | E-mails y teléfonos de la persona |
Pull-only
La API del Financeiro Inteligente no expone webhooks, así que la integración es solo lectura por pull: el Dunning busca los recibibles en la sincronización automática (cada 60 min por defecto) y en la sincronización manual, con el botón de sincronizar. Cada ejecución es idempotente — reprocesar no duplica títulos. Un recibible pagado da de baja el cobro y lo retira de la regla; uno cancelado sale definitivamente. Los cobros ya finales localmente (pagados o cancelados) no tienen sus valores sobrescritos por el origen.
Qué no hace / limitaciones
- No emite recibibles. La creación sigue en el Financeiro Inteligente.
- No escribe de vuelta. Es pull-only: dar de baja o cancelar en el Dunning no altera el recibible de origen.
- Sin tiempo real. Sin webhooks, los pagos y cancelaciones aparecen a lo sumo en el próximo ciclo de sincronización.
Cómo desconectar o reconfigurar
Rehaz el setup para cambiar el token. Para rotar credenciales, genera un nuevo token en el panel de origen y pégalo en el Dunning; el antiguo deja de usarse.
Solución de problemas
- La sincronización está desactualizada. Revisa el intervalo (por defecto 60 min) y haz clic en Sincronizar ahora.
- Un recibible pagado no dio de baja. Como no hay webhook, la baja depende del próximo pull — fuérzalo con Sincronizar ahora o espera el ciclo.
- Un cliente no apareció. El sync de personas corre junto con el de recibibles; una persona sin título se crea cuando se sincroniza su primer recibible.
- Un cobro aparece duplicado. El Dunning deduplica por
externalId(finance:receivable:{id}); la duplicidad real solo ocurre si el mismo título viene de otro origen. - La conexión se cayó / token inválido. Genera un nuevo token en el panel y reconecta.
Seguridad
El token de acceso está cifrado en reposo y nunca es devuelto por la API. Toda llamada a la API del Financeiro Inteligente se registra en el log de integración, para que audites lo que entró y diagnostiques fallas de sincronización.