> ## Documentation Index > Fetch the complete documentation index at: https://docs.strattum.ai/llms.txt > Use this file to discover all available pages before exploring further. # Omie > Clientes e fornecedores, produtos, pedidos de venda, notas fiscais e o financeiro do ERP Omie, no Data Catalog e no Memory. 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. | | | | - | - | | **Status** | Disponível | | **Conteúdo** | Registros | | **Autenticação** | App Key e App Secret | | **Permissões** | Sem permissão por item | | **Sincronização** | Full refresh | | **Última revisão** | 28/10/2026 | ## 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. | Recurso | O que contém | Carga | Cursor | Destino | Permissão por item | | - | - | - | - | - | - | | `clientes` | Cadastro de clientes e fornecedores (o Omie usa um cadastro só), com razão social, nome fantasia, CPF ou CNPJ, e-mail, telefones, endereço, tags, observação e características | Full refresh | Nenhum | Catálogo e Memory | Não | | `produtos` | Produtos e serviços, com código, descrição, unidade, NCM, EAN, preço, estoque e alíquotas | Full refresh | Nenhum | Catálogo e Memory | Não | | `pedidos` | Pedidos de venda, com cliente, vendedor, projeto, categoria, conta corrente, etapa, totais, itens e parcelas | Full refresh | Nenhum | Catálogo e Memory | Não | | `notas_fiscais` | Notas fiscais de entrada e de saída, canceladas ou não, com número, série, chave, destinatário, pedido de origem e totais | Full refresh | Nenhum | Catálogo e Memory | Não | | `contas_pagar` | Títulos a pagar, com fornecedor, categoria, conta corrente, status, valor, datas e rateio por categoria | Full refresh | Nenhum | Catálogo e Memory | Não | | `contas_receber` | Títulos a receber, abertos ou liquidados, com cliente, categoria, conta corrente, status, valor, datas, boleto e rateio por categoria | Full refresh | Nenhum | Catálogo e Memory | Não | | `categorias` | Plano de categorias, ativas ou não, com categoria superior, natureza e dados do DRE | Full refresh | Nenhum | Catálogo e Memory | Não | | `contas_correntes` | Contas correntes e caixas da própria empresa, com banco, agência, número, saldo inicial e limite | Full refresh | Nenhum | Catálogo e Memory | Não | | `departamentos` | Departamentos e a posição de cada um na estrutura | Full refresh | Nenhum | Catálogo | Não | | `vendedores` | Vendedores, com nome, e-mail e comissão | Full refresh | Nenhum | Catálogo e Memory | Não | | `projetos` | Projetos, com nome e se estão inativos | Full refresh | Nenhum | Catálogo | Não | ### 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. | Escopo ou permissão | Para quê | | - | - | | App Key e App Secret de um administrador | Todos os recursos. Não há escopo por recurso nem por módulo. | | Módulo habilitado na conta | Cada recurso depende de o módulo correspondente estar habilitado na empresa. | **1. Entre no Omie como administrador** Só usuários administradores conseguem ver a chave de integração do aplicativo. **2. Abra o resumo do aplicativo** Na tela **Meus Aplicativos**, clique na engrenagem do card do aplicativo e escolha **Resumo do App**. Outra forma: no portal do desenvolvedor (`developer.omie.com.br`), clique em **Aplicativos** e abra o aplicativo da lista. **3. Copie o par** No fim da página, na seção **Chave de Integração (API)**, copie a App Key e clique em **exibir** para ver o App Secret. Os dois valores vão nos campos **App Key** e **App Secret** do Console. ## Configuração no Console **1. Abra o assistente** Em **Conectores**, clique em **+ Nova Conexão** e selecione **Omie**, em **Gestão Financeira**. **2. Preencha a conexão** **Nome do Conector** (Opcional): como a conexão aparece na lista. O padrão é `Omie`. **App Key** (Obrigatório): a App Key do aplicativo da empresa. **App Secret** (Obrigatório): o App Secret do mesmo aplicativo. **3. Teste a conexão** Clique em **Testar Conexão**. Você só avança depois de um teste com sucesso. O teste faz uma única chamada, a mesma listagem de clientes que a sincronização usa, pedindo um registro. Passa quando o Omie aceita o par, inclusive numa empresa sem nenhum cliente. Falha quando o par é recusado, quando o aplicativo está bloqueado por excesso de erros e quando o Omie responde com limite de requisições. O teste nunca repete a chamada sozinho: no Omie, erros seguidos bloqueiam o aplicativo por 30 minutos. **4. Escolha a frequência** Em **Sincronização** (Obrigatório), escolha a frequência. O padrão do Omie é uma vez por dia, às 06:00 UTC. **5. Defina o acesso** Em **Permissionamento**, defina **Quem pode usar este conector**. O **Comportamento dos dados** é sempre "Aberto". **6. Revise e salve** Em **Revisão**, confira os dados e salve. A App Key e o App Secret aparecem mascarados. **7. Marque os dados pessoais no Data Catalog** No Data Catalog, abra cada recurso que tem dado pessoal e marque as colunas no painel **Proteção de dados pessoais**, antes da primeira sincronização. Sem marcação, os valores chegam ao lake em claro. Veja a seção abaixo. **8. Ajuste os recursos no Data Catalog** Os recursos e as tabelas clean já nascem ligados. Desligue os que você não quiser carregar. 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: | Recurso | Colunas que o painel não sugere | | - | - | | `clientes` | `endereco`, `endereco_numero`, `bairro`, `complemento`, `contato`, `telefone1`, `telefone2`, `fax`, `codigo_cliente_integracao`, `caracteristicas_json` | | `notas_fiscais` | `nfDestInt_cCodCliInt` | | `pedidos` | `informacoes_adicionais_contato`, `informacoes_adicionais_dados_adicionais_nf` | 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)](https://docs.strattum.ai/data-pipelines/personal-data.md). ## 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 | Método e caminho | Usado para | Recurso | | - | - | - | | `POST /api/v1/geral/clientes/` (`ListarClientes`) | Listar clientes e fornecedores, e testar a conexão | `clientes` | | `POST /api/v1/geral/produtos/` (`ListarProdutos`) | Listar produtos e serviços | `produtos` | | `POST /api/v1/produtos/pedido/` (`ListarPedidos`) | Listar pedidos de venda | `pedidos` | | `POST /api/v1/produtos/nfconsultar/` (`ListarNF`) | Listar notas fiscais | `notas_fiscais` | | `POST /api/v1/financas/contapagar/` (`ListarContasPagar`) | Listar títulos a pagar | `contas_pagar` | | `POST /api/v1/financas/contareceber/` (`ListarContasReceber`) | Listar títulos a receber | `contas_receber` | | `POST /api/v1/geral/categorias/` (`ListarCategorias`) | Listar o plano de categorias | `categorias` | | `POST /api/v1/geral/contacorrente/` (`ListarContasCorrentes`) | Listar contas correntes e caixas | `contas_correntes` | | `POST /api/v1/geral/departamentos/` (`ListarDepartamentos`) | Listar departamentos | `departamentos` | | `POST /api/v1/geral/vendedores/` (`ListarVendedores`) | Listar vendedores | `vendedores` | | `POST /api/v1/geral/projetos/` (`ListarProjetos`) | Listar projetos | `projetos` | 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](https://ajuda.omie.com.br/pt-BR/articles/8112984-limites-de-consumo-da-api-do-omie) e [Lista de serviços da API](https://developer.omie.com.br/service-list/) ## 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 | Mensagem ou sintoma | Causa | O que fazer | | - | - | - | | Informe a App Key e o App Secret antes de testar | Um dos campos está vazio. | Preencha os dois campos com o par do aplicativo. | | App Key ou App Secret inválidos, ou aplicativo suspenso ou expirado. | O par está errado, o aplicativo foi suspenso ou o Aplicativo Teste passou dos 7 dias. | Confira o par em **Meus Aplicativos** e confirme que o aplicativo está ativo. Não repita o teste com o mesmo par: erros seguidos bloqueiam o aplicativo por 30 minutos. | | O Omie bloqueou o aplicativo por excesso de erros. | O aplicativo recebeu 10 requisições com erro seguidas e está bloqueado por 30 minutos. | Aguarde 30 minutos, confira o par e teste de novo. | | Limite de requisições do Omie atingido. | O limite por minuto foi atingido. | Aguarde alguns instantes e teste de novo. | | Não foi possível contatar a API do Omie. | Falha de rede entre a plataforma e o Omie. | Verifique a conexão de rede e teste de novo. | | Erro ao testar a conexão com o Omie (HTTP N). | O Omie respondeu algo que o teste não classifica, como um redirecionamento. | Teste de novo. Se o erro persistir, fale com o suporte do Omie. | | O App Key e o App Secret são trocados juntos: preencha os dois ou nenhum. | Na edição, só um dos campos foi preenchido. | Preencha os dois para trocar o par, ou deixe os dois em branco. | | Já existe um conector do tipo omie. | A instalação já tem uma conexão Omie. | Edite a conexão existente ou remova-a antes de criar outra. | | O log do conector mostra `Omie rejected the request (SOAP-ENV:Client-...)` num recurso. | O módulo desse recurso não está habilitado na conta, ou o Omie recusou a listagem. | Habilite o módulo no Omie ou desligue o recurso no Data Catalog. Os outros continuam sendo carregados. | | O log do conector mostra `Omie reported redundant consumption`. | O Omie recusou a mesma requisição duas vezes em menos de 60 segundos. | Aguarde um minuto e rode a sincronização de novo. | | O log do conector mostra `records changed during the walk, run the sync again`. | Registros foram apagados no Omie durante a leitura, e o total não bateu. | Rode a sincronização de novo. A tabela anterior foi mantida. | | A execução falha com `Omie rejected the credentials (invalid key or suspended app)`. | O par foi trocado ou o aplicativo foi suspenso ou expirou. | Gere ou confira o par no Omie e informe os dois campos na edição do conector. | | `omie_titulo_categorias` não aparece na clean. | `contas_pagar` ou `contas_receber` está desligado no Data Catalog. | Ligue os dois e rode a sincronização. | | CPF, telefone ou endereço aparecem em claro na raw. | As colunas não foram marcadas no painel **Proteção de dados pessoais**. | Marque as colunas no Data Catalog, salve e rode a sincronização de novo. | ## Próximos passos > **[Data Catalog](https://docs.strattum.ai/data-catalog/overview.md)** > > Marque as colunas com dado pessoal e desligue os recursos e as tabelas clean do Omie que você não vai usar. > **[Memory](https://docs.strattum.ai/memory/overview.md)** > > Veja como clientes, vendedores, pedidos, notas e títulos entram no grafo e se unificam com os CRMs. > **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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.