Omie

O conector Omie lê, pela API do Omie, o cadastro e o financeiro de uma empresa no ERP: clientes e fornecedores, produtos, pedidos de venda, notas fiscais, contas a pagar e a receber, categorias, contas correntes, departamentos, vendedores e projetos.

​

Capacidades

• Traz ao Data Catalog os 11 recursos do Omie listados abaixo, com os campos que o conector declara para cada um. Um campo que o Omie passe a mandar e que não está declarado não chega ao lake.
• Instala 15 tabelas clean prontas, com o código do Omie como external_id, e-mail em minúsculas, CPF e CNPJ em colunas separadas, flags S/N como booleanos, valores em DECIMAL(18,2) e horários em UTC. Itens e parcelas de pedido, tags de cliente e o rateio por categoria dos títulos ficam em tabelas próprias.
• Alimenta o Memory com os nós Customer (clientes e fornecedores), Agent (vendedores), Product, Order, OrderItem, Invoice, Receivable, Payable, FinancialCategory e BankAccount. Eles se ligam por cliente, vendedor, produto, pedido de origem, categoria e conta corrente. Pedido, emissão de nota e vencimento de título entram como eventos de linha do tempo.
• Clientes se unificam por e-mail e telefone com HubSpot, Salesforce, Pipedrive, Attio, Brevo e Asaas. Vendedores se unificam por e-mail com HubSpot, Salesforce e Pipedrive. Os nós só entram no grafo depois que a ontologia unificada é aplicada.

​

Recursos disponíveis

Ao criar a conexão, as tabelas clean do Omie já nascem ligadas no Data Catalog, e com elas os recursos que elas leem. Como todo recurso tem uma tabela clean, os 11 recursos começam ligados. Desligue no Data Catalog o que você não quiser carregar.

​

Como ler os dados

• Clientes e fornecedores vêm do mesmo cadastro do Omie. Em omie_contas_pagar, cliente_external_id aponta o fornecedor em omie_clientes.
• O documento do cadastro vai para cpf ou cnpj conforme o cadastro seja de pessoa física ou jurídica. No destinatário da nota fiscal, vai para destinatario_cpf ou destinatario_cnpj pela contagem de dígitos.
• O telefone sai com o DDD junto, como (11) 99999-0000. Em omie_clientes, phone vem de telefone1.
• unique_email e unique_phone repetem o e-mail e o telefone quando o valor pertence a um cliente só, e ficam NULL quando cadastros de documentos diferentes, ou sem documento, dividem o mesmo valor. São essas colunas que o Memory usa para unificar clientes, para que um e-mail genérico como financeiro@ não junte empresas diferentes.
• O Omie grava data e hora no horário de Brasília. A clean converte para UTC. Data sem hora, como vencimento e emissão, fica como DATE.
• As características customizadas do cliente e do produto ficam como JSON em caracteristicas_json.
• Não chegam ao lake: os dados bancários e o endereço de entrega do cliente, e o e-mail, o telefone e o nome do gerente das contas correntes.
• omie_titulo_categorias traz o rateio por categoria de títulos a pagar e a receber. tipo_titulo diz se a linha é de contas_pagar ou de contas_receber.

​

Permissões (ACL)

Esta fonte não define permissões por registro, então todo mundo que puder usar o conector vê todos os registros. Quem pode usar o conector é definido em Quem pode usar este conector: “Todos os usuários” ou “Apenas times específicos”. O Comportamento dos dados deste conector é sempre “Aberto”.

​

Como a fonte define acesso

No Omie, a App Key e o App Secret são do aplicativo da empresa e enxergam a empresa inteira. A API lista os usuários com nome e e-mail, sem perfil, papel ou permissão.

​

Como a Strattum traduz o acesso

A Strattum não grava permissão por item. Os códigos de usuário que o Omie anexa a cada registro (quem incluiu e quem alterou) não são tratados como identidade. Todas as linhas ficam visíveis para quem pode usar o conector. O conector não oferece Exigir login na fonte como prova de identidade.

​

Quando a identidade não é encontrada

Não se aplica: nenhuma linha depende da identidade de quem consulta.

​

Quando a permissão é atualizada

Não há permissão da fonte para atualizar. O acesso depende só de Quem pode usar este conector.

​

Pré-requisitos

• Uma conta Omie com os módulos dos recursos que você vai carregar habilitados. Um recurso de módulo desabilitado falha sozinho, e os outros seguem.
• Um usuário administrador do Omie, que é quem consegue ver a chave de integração do aplicativo.
• Uma empresa por conexão. O par App Key e App Secret é de um aplicativo, e cada aplicativo é uma empresa.
• Uma só conexão Omie por instalação. A plataforma recusa criar a segunda.
• Para testar antes de conectar a empresa real, o Omie oferece o Aplicativo Teste, com dados de demonstração. Ele vale 7 dias, e a prorrogação é pedida ao suporte do Omie pelo e-mail ajuda@omie.com.br.

​

Autenticação e escopos

A autenticação usa a App Key e o App Secret do aplicativo da empresa no Omie. Toda chamada é um POST com o par no corpo JSON, nunca na URL nem em header. O Omie não tem escopos: um par válido lê tudo o que os módulos habilitados da empresa expõem.

​

Configuração no Console

Para trocar o par depois, na edição do conector, preencha os dois campos. Deixe os dois em branco para manter o par atual. O Console não aceita trocar só um deles.

​

Dados pessoais

O conector declara o tipo de dado pessoal de cada coluna, mas não protege nada sozinho. Uma coluna só vira token, ou só tem o texto mascarado, depois que você a marca no painel Proteção de dados pessoais do Data Catalog e salva. Ao marcar, a coluna é tratada pelo tipo que o conector declara: telefone1 vira token de telefone, e cnpj vira token de CNPJ. O painel do Data Catalog sugere colunas pelo nome, e a regra de nome não reconhece várias colunas do Omie. Marque estas à mão: O painel sugere, pelo nome, email (em clientes e vendedores), cpf, cnpj, destinatario_cpf, destinatario_cnpj e os campos de observação. Em clientes, codigo_cliente_integracao pode guardar o próprio CPF ou CNPJ do cliente. Detalhes do tratamento em Dados pessoais (PII).

​

Como a sincronização funciona

A frequência vem do passo Sincronização. O padrão é uma execução por dia, às 06:00 UTC, porque cada execução relê o ERP inteiro. Criar a conexão não dispara uma execução: a primeira acontece no horário agendado. Full refresh. Todo recurso é reescrito por inteiro a cada execução. O Omie não oferece um cursor de alteração confiável nem uma lista de registros apagados, então só a releitura completa reflete o que mudou e o que foi removido. Um registro apagado no Omie some da tabela na execução seguinte. O que é lido. O conector envia em cada listagem os filtros que desligam o recorte padrão do Omie. Assim entram todos os registros, e não só os incluídos pela API: categorias e contas correntes inativas, títulos a receber já liquidados e produtos fora do PDV e do marketplace. Nenhum filtro por data ou por status é enviado, então as notas fiscais vêm de entrada e de saída, canceladas ou não. Ordem. O conector lê os recursos ligados um por um, com uma chamada por vez: clientes, produtos, pedidos, notas_fiscais, contas_pagar, contas_receber, categorias, contas_correntes, departamentos, vendedores e projetos. Recurso desligado no Data Catalog não é lido. Paginação. Os recursos são lidos de 100 em 100 registros, e contas_pagar e categorias de 50 em 50. Depois de uma página cheia, o conector sempre pede a próxima. A leitura termina numa página vazia, numa última página com menos registros que o pedido ou quando o Omie responde que não há registros para a página. Conferência. O conector guarda o total de registros que o Omie declara na primeira página e descarta repetidos pela chave de cada recurso. Se terminar com menos registros que esse total, o recurso falha, porque um registro apagado durante a leitura desloca as páginas e faria outro sumir. Um recurso também falha se passar de 2.000 páginas. Nos dois casos, a tabela anterior fica como estava, desde que o recurso tenha até 100.000 registros. Falhas. Um erro do Omie num recurso, como um módulo desabilitado, não interrompe os outros. A tabela do recurso que falhou não é tocada, e o log do conector registra o erro e como corrigir. Se pelo menos um recurso carregou, a execução termina normalmente, com um aviso que nomeia cada recurso que falhou, e as tabelas clean são atualizadas. Se nenhum recurso carregou, a execução termina com falha. Um par recusado interrompe a execução na hora, sem ler os recursos seguintes. Uma falha da própria plataforma, como o lake fora do ar, também para a execução.

​

API da fonte

O host da API é https://app.omie.com.br. Todas as chamadas são métodos Listar* e só leem dados. O método vai no campo call do corpo. Rate limits. O Omie aceita 960 requisições por minuto por IP, e 240 por minuto e 4 simultâneas por IP, App Key e método. O aplicativo Trial tem 60 por minuto e 100 por dia, e o FIT 60 por minuto e 500 por dia. Para aplicativo de produção, o Omie não publica cota diária. O limite de uma listagem é 100 registros por página. Na 10ª requisição com erro para o mesmo IP, App Key e método, o Omie bloqueia o aplicativo por 30 minutos e responde 425. A mesma requisição repetida em menos de 60 segundos é recusada como consumo redundante: o Omie responde 500 com o código SOAP-ENV:Client-6, sem header Retry-After. O conector envia uma chamada por vez, com tempo limite de 60 segundos, e nunca segue redirecionamento. Ele não repete uma chamada que o Omie recusou como inválida, para não somar erros no contador de bloqueio. Diante do consumo redundante, espera o tempo que a mensagem do Omie pede mais 1 segundo (60 segundos quando a mensagem não diz) e tenta uma vez. Se o Omie pedir mais de 120 segundos, ou recusar de novo, o recurso falha. Um 425 ou um 429 faz o recurso falhar, sem nova tentativa. Um erro 500 sem código de falha, uma instabilidade PROTO_BYEBYE e uma queda de conexão são repetidos em até 3 tentativas, com espera de 2 e 4 segundos. O teste de conexão faz uma chamada só, com tempo limite de 15 segundos. Referência oficial: Limites de consumo da API do Omie e Lista de serviços da API

​

Limitações conhecidas

• Sem permissão por item: todo usuário que pode usar o conector vê tudo o que o par App Key e App Secret alcança, ou seja, a empresa inteira. Para restringir, limite Quem pode usar este conector.
• Nenhum dado pessoal é protegido sem marcação. O conector declara o tipo de cada coluna, mas o token só é aplicado depois que você marca a coluna no Data Catalog. Endereço, bairro, complemento, contato e telefones de clientes não são sugeridos pelo painel e precisam ser marcados à mão.
• A cada execução, todo o ERP é relido. O Omie não publica a cota diária de aplicativo de produção, e uma empresa grande pode chegar a ela.
• Um recurso com mais de 100.000 registros perde a garantia de tabela intacta: se ele falhar no meio da leitura, a tabela fica parcial até a próxima execução bem-sucedida. O aviso overwrite_not_atomic aparece no resumo da execução.
• Um recurso para de ser lido depois de 2.000 páginas, ou seja, 200.000 registros (100.000 em contas_pagar e categorias).
• Um registro criado no Omie pode levar cerca de um minuto para aparecer na listagem da API.
• omie_titulo_categorias lê contas_pagar e contas_receber. Com um dos dois desligado, a tabela não é construída. A categoria principal de cada título continua em omie_contas_pagar e omie_contas_receber.
• notas_fiscais foi validado contra a documentação do Omie e com uma conta sem notas emitidas. Se o formato real da nota divergir e um registro vier sem a chave, o recurso falha em vez de carregar parcial.
• Ficam de fora movimentos financeiros, lançamentos de conta corrente, ordens de serviço, contratos, CRM, compras, estoque, anexos e o XML das notas fiscais.
• Os rateios por departamento de pedidos e títulos, os itens e títulos da nota fiscal, os impostos do item de pedido e as alíquotas do produto ficam só na raw.
• Uma conexão Omie por instalação, e uma empresa por conexão.
• O Aplicativo Teste do Omie vale 7 dias. Depois disso, o Omie bloqueia o aplicativo e a sincronização para de funcionar até a prorrogação.

​

Troubleshooting

​

Próximos passos

Desenvolvimento local

O conector não lê variáveis do .env. A App Key e o App Secret são informados no Console e ficam no cofre de segredos da plataforma, sob os nomes OMIE_APP_KEY e OMIE_APP_SECRET. Para testar localmente, crie a conexão pelo Console da stack local. O Aplicativo Teste do Omie serve para isso, dentro dos 7 dias de validade.