Bling
Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conexión vía OAuth
El Bling es un ERP muy usado por pequeñas y medianas empresas en Brasil. Conectado al Dunning, trae las cuentas por cobrar y los contactos de tu Bling hacia la operación de cobranza — los títulos abiertos se vuelven cobros, y los contactos se vuelven personas en tu cartera.
Requisitos previos
- Una cuenta Bling con contactos y cuentas por cobrar.
- Una aplicación OAuth registrada en el portal de desarrolladores del Bling, apuntando a la URL de callback del Dunning (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.
:::
El Bling usa OAuth2: autorizas el acceso dentro de la propia cuenta Bling, sin pegar tokens a mano.
- En el Dunning, abre Configuraciones → Integraciones y haz clic en Conectar en el Bling.
- El Dunning genera un link seguro y te redirige al Bling.
- En el Bling, inicia sesión y revisa la pantalla de consentimiento con los accesos solicitados.
- Autoriza el acceso del Dunning.
- El Bling te devuelve al Dunning ya conectado — los tokens se graban cifrados y la integración queda activa, con la primera sincronización justo después.
A partir de ahí, el token se renueva automáticamente entre bastidores; no necesitas reconectar en cada expiración.
Mapeo de campos (origen → Dunning)
| Campo en el Bling | Campo en el Dunning |
|---|---|
Cuenta por cobrar (contas/receber) | Cobro |
valor | Valor original |
vencimento | Vencimiento |
dataEmissao | Fecha de emisión |
dataPagamento | Fecha del pago |
numeroDocumento | Número del documento |
historico | Descripción |
linkBoleto | Línea digitable / URL de pago |
linkQRCodePix | Copia-y-pega Pix |
situacao 1 (abierto) / 7 (confirmado) / 3 (parcial) | pending (o overdue si está vencida) |
situacao 2 (recibido) | paid (baja + salida de la regla) |
situacao 5 (cancelado) | cancelled |
situacao 4 / 6 (devuelto) | ignorada (no es objeto de regla) |
Contacto (contatos) | Persona en la cartera |
numeroDocumento del contacto | Documento de la persona |
nome | Nombre de la persona |
Sincronización
La sincronización es idempotente y corre de dos formas: automática (cada 60 min por defecto) y manual (botón de sincronizar). Contactos y cuentas por cobrar se sincronizan en el mismo ciclo.
Qué no hace / limitaciones
- No emite títulos ni escribe de vuelta en el Bling — es pull-only.
- Sin webhooks. La API del Bling no expone webhooks de cuentas por cobrar para aplicaciones, así que los pagos y cancelaciones aparecen a lo sumo en el próximo ciclo de sincronización.
- Las cuentas con situación devuelta/parcial-devuelta quedan afuera, por no ser objeto de cobranza.
Pendiente: aplicación OAuth en el Bling
Para que el "Conectar" funcione, es necesario que haya una aplicación OAuth registrada en el portal de desarrolladores del Bling, apuntando a la URL de callback del Dunning. Las credenciales de esa aplicación (client ID y client secret) pueden configurarse de forma global en el ambiente del Dunning o informarse por integración, en caso de que cada organización use su propia aplicación. Sin esa aplicación registrada, el flujo de conexión no abre — es el paso de habilitación que queda a cargo de quien administra el Bling.
Cómo desconectar o reautorizar
Si el acceso es revocado en el Bling (o quieres cambiar de cuenta), basta con rehacer el "Conectar" — un nuevo consentimiento genera tokens nuevos. Mientras la conexión esté activa, la renovación del token es automática; solo reautorizas cuando el refresh token deja de valer.
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 el Bling o el refresh token expiró — rehaz el "Conectar" para reautorizar.
- Un contacto no apareció. El sync de contactos corre junto con el de cuentas por cobrar; un contacto sin título se crea cuando se sincroniza su primer título.
- Un cobro aparece duplicado. El Dunning deduplica por
externalId(bling: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 el Bling (o las credenciales del app no están configuradas) — mira la pendiente arriba.
Seguridad
Todo el flujo está protegido: 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 se registran con el cuerpo redactado — código y secretos nunca aparecen en el log.