Omie

Integração nativa · Somente leitura (pull) · Sincroniza automaticamente a cada 60 min (configurável) + sob demanda · Conexão por chave estática

O Omie é um ERP de gestão para pequenas e médias empresas. Conectado ao Dunning, ele traz os clientes e as contas a receber do seu Omie para a operação de cobrança — os títulos em aberto viram cobranças e os clientes viram pessoas na sua carteira.

Pré-requisitos

• Uma conta Omie com clientes e contas a receber.
• Uma app key e um app secret gerados no painel do Omie (chave de aplicativo).

Como conectar

:::note Sem tela dedicada no painel (ainda) Hoje só o Gateway da Kobana tem tela de conexão pronta no painel. Para este ERP, a conexão é feita pela API (rotas /api/v1/integrations/...) — o passo a passo abaixo descreve o fluxo de autorização; a tela self-service equivalente no painel está no roadmap. :::

Diferente do Bling, da Conta Azul e do Olist, o Omie não usa OAuth: a autenticação é por chave estática.

1. No painel do Omie, gere (ou copie) a app key e o app secret do aplicativo.
2. No Dunning, abra Configurações → Integrações e escolha o Omie.
3. Cole a app key e o app secret nos campos indicados.
4. Clique em Conectar. O Dunning valida as credenciais na hora, com uma chamada de teste à API do Omie; chaves inválidas são recusadas antes de salvar.
5. A primeira sincronização roda logo após conectar.

O Omie tem apenas ambiente de produção (não há sandbox público) — os testes são feitos com uma conta trial na própria plataforma.

De → Para: como os campos são mapeados

Campo no Omie	Campo no Dunning
Conta a receber (financas/contareceber)	Cobrança
valor_documento	Valor
data_vencimento	Vencimento
data_emissao / data_registro	Data de emissão
numero_documento	Número do documento
status_titulo contém RECEBIDO / LIQUIDADO / PAGO / QUITADO	paid (baixa + saída da régua)
status_titulo contém CANCELAD / INATIVO	cancelled
status_titulo contém ATRASAD / VENCIDO	overdue
demais status (A VENCER / A RECEBER / vazio)	pending ou overdue, derivado pelo vencimento
Cliente (geral/clientes)	Pessoa na carteira
cnpj_cpf	Documento da pessoa
razao_social / nome_fantasia	Nome / apelido da pessoa
email, telefone1_ddd + telefone1_numero	E-mail e telefone da pessoa

O status_titulo do Omie é texto livre; quando ele não é conclusivo, o status é derivado da data de vencimento (vencida → overdue, futura → pending). "PARCIAL" não conta como quitação total.

Sincronização

A sincronização é idempotente e roda de forma automática (a cada 60 min por padrão) e manual (botão de sincronizar). Clientes e contas a receber são sincronizados no mesmo ciclo.

O que não faz / limitações

• Não emite títulos nem escreve de volta no Omie — é pull-only.
• Sem webhooks. A API do Omie não expõe webhooks, então pagamentos e cancelamentos chegam ao Dunning apenas na próxima sincronização.
• Sem linha digitável/Pix/URL de pagamento vindos da origem — o pagamento é acompanhado pelo status.
• Sem sandbox público — teste com conta trial.

Como desconectar ou rotacionar a chave

Para rotacionar as credenciais, gere uma nova app key/app secret no painel do Omie e cole no Dunning; as chaves antigas deixam de ser usadas. Refazer o setup também troca o ambiente e revalida a conexão.

Solução de problemas

• A sincronização está desatualizada. Confira o intervalo (padrão 60 min) e clique em Sincronizar agora.
• Um título pago não deu baixa. Sem webhook, a baixa depende do próximo pull — force com Sincronizar agora. Confirme também que o status_titulo no Omie já indica recebimento.
• Um cliente não apareceu. O sync de clientes roda junto com o de contas a receber; um cliente sem título é criado quando o primeiro título dele é sincronizado.
• Uma cobrança aparece duplicada. O Dunning deduplica por externalId (omie:receivable:{codigo}); duplicidade real só ocorre com a mesma cobrança vinda de outra origem.
• Chaves inválidas. Gere uma nova app key/app secret no painel do Omie e reconecte.

Segurança

A app key e o app secret são cifrados em repouso e nunca são devolvidos pela API. Toda chamada à API do Omie é registrada no log de integração, para você auditar o que entrou e diagnosticar falhas.