Conta Azul
Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conexión vía OAuth
La Conta Azul es una plataforma de gestión financiera y ERP para pequeñas empresas. Conectada al Dunning, trae las cuentas por cobrar y los clientes de tu Conta Azul hacia la operación de cobranza — los títulos abiertos se vuelven cobros y los clientes se vuelven personas en tu cartera.
Requisitos previos
- Una cuenta en la Conta Azul con clientes y cuentas por cobrar.
- Una aplicación OAuth registrada en el portal de desarrolladores de la Conta Azul, con la URL de callback del Dunning y los scopes de acceso a clientes y cuentas por cobrar (mira la pendiente abajo).
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.
:::
La Conta Azul usa OAuth2: autorizas el acceso en la propia Conta Azul, sin pegar tokens a mano.
- En el Dunning, abre Configuraciones → Integraciones y haz clic en Conectar en la Conta Azul.
- El Dunning genera un link seguro y te redirige a la pantalla de login de la Conta Azul.
- Inicia sesión y revisa la pantalla de consentimiento con los scopes solicitados.
- Autoriza el acceso del Dunning.
- La Conta Azul te devuelve al Dunning ya conectado — los tokens quedan grabados cifrados y la integración queda activa, con la primera sincronización a continuación.
Después de conectada, el token se renueva automáticamente; solo rehaces el "Conectar" si el acceso es revocado.
Mapeo de campos (origen → Dunning)
| Campo en la Conta Azul | Campo en el Dunning |
|---|---|
| Cuenta por cobrar | Cobro |
total | Valor original |
nao_pago (saldo deudor) | Valor actual |
pago | Valor pagado |
data_vencimento | Vencimiento |
data_competencia / data_criacao | Fecha de emisión |
descricao | Descripción |
Status EM_ABERTO / RECEBIDO_PARCIAL | pending (o overdue si está vencida) |
Status ATRASADO | overdue |
Status RECEBIDO | paid (baja + salida de la regla) |
Status RENEGOCIADO / PERDIDO | cancelled (salen de la regla) |
| Cliente | Persona en la cartera |
documento, nome, tipo_pessoa | Documento, nombre, tipo (PF/PJ) |
La cuenta por cobrar de la Conta Azul no trae el documento del cliente ni la fecha de pago en ese recurso, y no expone línea digitable/Pix. El vínculo del título con la persona se hace por el identificador del cliente; cuando el status es "recibido", la fecha del pago se asume como el momento de la baja.
Sincronización
La sincronización es idempotente y corre de forma automática (cada 60 min por defecto) y manual (botón de sincronizar). Clientes y cuentas por cobrar se sincronizan en el mismo ciclo.
Qué no hace / limitaciones
- No emite títulos ni escribe de vuelta en la Conta Azul — es pull-only.
- Sin webhooks. Los cambios aparecen a lo sumo en el próximo ciclo de sincronización.
- Sin línea digitable/Pix venidos del origen en ese recurso — el pago se acompaña por el status.
- Los títulos renegociados salen de la regla (la renegociación genera un nuevo título en el origen) y los perdidos salen como baja contable.
Pendiente: aplicación OAuth en la Conta Azul
El "Conectar" depende de una aplicación OAuth registrada en el portal de desarrolladores de la Conta Azul, con la URL de callback del Dunning y los scopes de acceso a clientes y cuentas por cobrar. Las credenciales de esa aplicación (client ID y client secret) pueden configurarse globalmente en el ambiente del Dunning o por integración. Sin esa aplicación registrada, el flujo de conexión no abre.
Cómo desconectar o reautorizar
Si el acceso es revocado (o quieres cambiar de cuenta), rehaz el "Conectar" para reautorizar. Mientras la conexión está activa, el token se renueva automáticamente.
Solución de problemas
- La sincronización está desactualizada. Revisa el intervalo (por defecto 60 min) y haz clic en Sincronizar ahora.
- La conexión se cayó. El acceso puede haber sido revocado en la Conta Azul — rehaz el "Conectar".
- Un cliente no apareció. El sync de clientes corre junto con el de cuentas por cobrar; un cliente sin título se crea cuando se sincroniza su primer título.
- Un cobro aparece duplicado. El Dunning deduplica por
externalId(contaazul:receivable:{id}); la duplicidad real solo ocurre con el mismo cobro venido de otro origen. - El "Conectar" no abre. Falta la aplicación OAuth registrada en la Conta Azul (o sus credenciales) — mira la pendiente arriba.
Seguridad
El link de autorización lleva un state firmado (anti-CSRF) de uso único, los tokens están cifrados en reposo y las llamadas de token van al log con el cuerpo redactado — código y secretos nunca se registran.