Integraciones

Las integraciones conectan el Dunning a los sistemas donde tus cobros ya nacen — el Gateway da Kobana, los productos hermanos de Faturamento y Financeiro, y ERPs del mercado como Bling, Conta Azul, Omie y Olist/Tiny. En vez de volver a registrar títulos a mano, conectas el origen una vez y el Dunning pasa a traer los cobros y los clientes desde allí para cobrarlos con la regla, el portal y los acuerdos.

Cómo funciona

El modelo es pull idempotente: el Dunning lee la fuente externa y trae lo que existe allí hacia adentro. Cada sincronización:

• Vincula el cliente del origen a una persona de tu cartera — primero por el identificador externo, después por el CPF/CNPJ normalizado. Cuando no hay correspondencia, crea una persona mínima para no perder el título.
• Crea o actualiza el cobro en el Dunning a partir de la cuenta por cobrar (o boleto/factura) del origen.
• No duplica: cada título lleva un externalId prefijado por el origen (ej.: bling:receivable:123). Volver a correr el sync actualiza el mismo registro en vez de crear uno nuevo.

Cuando el origen informa que un título fue pagado, el Dunning reaprovecha su propio flujo de baja — el cobro se marca como pagado y sale de la regla. Cuando informa cancelación, el cobro sale definitivamente de la regla. Los cobros que ya están en estado final localmente (pagados o cancelados) no tienen su valor ni su vencimiento sobrescritos por el origen.

Sincronización automática y manual

Cada integración activa se sincroniza automáticamente cada 60 minutos por defecto. Ese intervalo es configurable por integración (vive en el registro de cada conexión), y la sincronización automática puede apagarse. Además del ciclo automático, puedes sincronizar bajo demanda en cualquier momento, con el botón de sincronizar.

Los productos que soportan webhooks — el Gateway da Kobana y el Faturamento Automático — reciben los eventos en tiempo real, sin esperar el próximo ciclo: un pago en el boleto se refleja en el Dunning en segundos. Los ERPs (Bling, Conta Azul, Omie, Olist) no exponen webhooks y dependen del ciclo de sincronización — el cambio aparece a lo sumo en el próximo sync.

Qué integración para qué

Integración	Qué trae	Autenticación	Tiempo real
Gateway da Kobana	Clientes + boletos y Pix	Token de acceso	Webhook + pull
Faturamento Automático	Clientes + facturas	Token de API	Webhook + pull
Financeiro Inteligente	Personas + cuentas por cobrar	Token de acceso	Solo pull
Bling	Contactos + cuentas por cobrar	OAuth ("Conectar")	Solo pull
Conta Azul	Clientes + cuentas por cobrar	OAuth ("Conectar")	Solo pull
Omie	Clientes + cuentas por cobrar	Clave estática (app key/secret)	Solo pull
Olist (Tiny)	Contactos + cuentas por cobrar	OAuth ("Conectar")	Solo pull

:::note Conexión por el panel: solo el Gateway de Kobana (hoy) De las integraciones anteriores, solo el Gateway de Kobana tiene una pantalla de conexión lista en el panel. Las demás (Facturación, Financiero, Bling, Conta Azul, Omie, Olist) se configuran hoy por la API (/api/v1/integrations/...); la pantalla self-service equivalente en el panel está en el roadmap. La sincronización, los logs y la seguridad descritos abajo valen para todas. :::

Registro de todo

Toda llamada a un sistema externo — y todo webhook recibido — se graba en un log de integración: método, endpoint, status, duración y error. Es la pista que responde "¿el título entró?", "¿por qué falló la última sincronización?" o "¿el webhook llegó?". Los secretos nunca entran en el log: los cuerpos de autenticación se redactan y los tokens jamás se registran.

Seguridad de las credenciales

Las credenciales de cada integración (tokens de acceso, claves de aplicación, tokens OAuth) están cifradas en reposo. La grabación es fail-closed: si el cifrado falla, la operación se aborta en vez de grabar un secreto en texto plano. Ninguna ruta de la API devuelve las credenciales de una integración.

Lo que las integraciones no hacen

El Dunning cobra a partir del dato que recibe — no emite un boleto ni una factura sobre un título de terceros por cuenta propia. La emisión sigue en el sistema de origen; el Dunning entra después, orquestando la regla, el portal y los acuerdos sobre los cobros sincronizados. Las integraciones de ERP son pull-only (solo lectura del origen): el Dunning lee los títulos, pero no escribe de vuelta en el ERP.