Olist (Tiny)
Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conexión vía OAuth
El Olist, a través del ERP Tiny, es una plataforma de gestión para retail y e-commerce. Conectado al Dunning, trae los contactos y las cuentas por cobrar de tu Tiny 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 Olist/Tiny con contactos y cuentas por cobrar.
- Una aplicación OAuth registrada en el portal de desarrolladores del Olist/Tiny, 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 Olist/Tiny usa OAuth2: autorizas el acceso en la propia plataforma, sin pegar tokens a mano.
- En el Dunning, abre Configuraciones → Integraciones y haz clic en Conectar en el Olist.
- El Dunning genera un link seguro y te redirige al login del Olist/Tiny.
- Inicia sesión y revisa la pantalla de consentimiento con los accesos solicitados.
- Autoriza el acceso del Dunning.
- El Olist 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 el Olist/Tiny | Campo en el Dunning |
|---|---|
| Cuenta por cobrar | Cobro |
valor | Valor |
dataVencimento | Vencimiento |
data | Fecha de emisión |
dataPagamento | Fecha del pago |
numeroDocumento | Número del documento |
historico | Descripción |
situacao abierto / prevista / parcial / atrasada / emisión | pending (o overdue si está vencida) |
situacao pagado / recibido | paid (baja + salida de la regla) |
situacao cancelado | cancelled |
situacao desconocida | ignorada |
| Contacto | Persona en la cartera |
cpfCnpj | Documento de la persona |
nome | Nombre de la persona |
Sincronización
La sincronización es idempotente y corre de forma 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 Olist/Tiny — es pull-only.
- Sin webhooks. La API v3 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.
- Sin línea digitable/Pix/URL de pago venidos del origen — el pago se acompaña por el status.
Pendiente: aplicación OAuth en el Olist
El "Conectar" depende de una aplicación OAuth registrada en el portal de desarrolladores del Olist/Tiny, con la URL de callback del Dunning. 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 — es el paso de habilitación a cargo de quien administra el Olist.
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 el Olist/Tiny — rehaz el "Conectar".
- 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(olist: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 Olist (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.