Omie

Integración nativa · Solo lectura (pull) · Sincroniza automáticamente cada 60 min (configurable) + bajo demanda · Conexión por clave estática

El Omie es un ERP de gestión para pequeñas y medianas empresas. Conectado al Dunning, trae los clientes y las cuentas por cobrar de tu Omie 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 Omie con clientes y cuentas por cobrar.
• Una app key y un app secret generados en el panel del Omie (clave de aplicación).

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. :::

A diferencia del Bling, la Conta Azul y el Olist, el Omie no usa OAuth: la autenticación es por clave estática.

1. En el panel del Omie, genera (o copia) la app key y el app secret de la aplicación.
2. En el Dunning, abre Configuraciones → Integraciones y elige el Omie.
3. Pega la app key y el app secret en los campos indicados.
4. Haz clic en Conectar. El Dunning valida las credenciales al instante, con una llamada de prueba a la API del Omie; claves inválidas son rechazadas antes de guardar.
5. La primera sincronización corre justo después de conectar.

El Omie tiene solo ambiente de producción (no hay sandbox público) — las pruebas se hacen con una cuenta trial en la propia plataforma.

Mapeo de campos (origen → Dunning)

Campo en el Omie	Campo en el Dunning
Cuenta por cobrar (financas/contareceber)	Cobro
valor_documento	Valor
data_vencimento	Vencimiento
data_emissao / data_registro	Fecha de emisión
numero_documento	Número del documento
status_titulo contiene RECEBIDO / LIQUIDADO / PAGO / QUITADO	paid (baja + salida de la regla)
status_titulo contiene CANCELAD / INATIVO	cancelled
status_titulo contiene ATRASAD / VENCIDO	overdue
demás status (A VENCER / A RECEBER / vacío)	pending o overdue, derivado por el vencimiento
Cliente (geral/clientes)	Persona en la cartera
cnpj_cpf	Documento de la persona
razao_social / nome_fantasia	Nombre / apodo de la persona
email, telefone1_ddd + telefone1_numero	E-mail y teléfono de la persona

El status_titulo del Omie es texto libre; cuando no es concluyente, el status se deriva de la fecha de vencimiento (vencida → overdue, futura → pending). "PARCIAL" no cuenta como pago total.

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 el Omie — es pull-only.
• Sin webhooks. La API del Omie no expone webhooks, así que los pagos y cancelaciones llegan al Dunning solo en la próxima sincronización.
• Sin línea digitable/Pix/URL de pago venidos del origen — el pago se acompaña por el status.
• Sin sandbox público — prueba con cuenta trial.

Cómo desconectar o rotar la clave

Para rotar las credenciales, genera una nueva app key/app secret en el panel del Omie y pégalas en el Dunning; las claves antiguas dejan de usarse. Rehacer el setup también cambia el ambiente y revalida la conexión.

Solución de problemas

• La sincronización está desactualizada. Revisa el intervalo (por defecto 60 min) y haz clic en Sincronizar ahora.
• Un título pagado no dio de baja. Sin webhook, la baja depende del próximo pull — fuérzalo con Sincronizar ahora. Confirma también que el status_titulo en el Omie ya indique recepción.
• 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 (omie:receivable:{codigo}); la duplicidad real solo ocurre con el mismo cobro venido de otro origen.
• Claves inválidas. Genera una nueva app key/app secret en el panel del Omie y reconecta.

Seguridad

La app key y el app secret están cifrados en reposo y nunca son devueltos por la API. Toda llamada a la API del Omie se registra en el log de integración, para que audites lo que entró y diagnostiques fallas.