Integração NFE.io com Omie ERP

Sobre este guia: Este documento descreve a integração do NFE.io com o Omie ERP usando webhooks e a plataforma Pluga. Este guia contém instruções detalhadas para garantir uma configuração sem erros.

Índice

• Fluxo de Integração
• Pré-requisitos
• Passo a Passo da Integração
• Referência de Campos
• Como Funciona na Prática
• Links Úteis

Fluxo de Integração

O fluxo básico de integração segue este caminho:

1. NFE.io emite uma nota fiscal e envia um webhook
2. Pluga recebe os dados e os transforma
3. Omie ERP recebe os dados e cria uma conta a receber
4. O departamento financeiro gerencia a conta a receber

Pré-requisitos

Para realizar esta integração, você precisará de:

Ferramenta	Requisito
NFE.io	Conta ativa com permissões administrativas
Omie ERP	Conta ativa com acesso às credenciais de API (App Key e App Secret)
Pluga	Conta na Pluga (plano que suporte Webhooks)
Conhecimento	Entendimento básico de como as notas fiscais são processadas

Passo a Passo da Integração

1. Configuração na Pluga

1. Acesse https://pluga.co e faça login na sua conta
2. No painel principal, clique no botão Nova Automatização
3. Na página de criação, você verá duas colunas: GATILHO (à esquerda) e AÇÃO (à direita)
4. Na coluna GATILHO, pesquise por Pluga Webhooks na barra de pesquisa
5. Selecione a ferramenta Pluga Webhooks clicando sobre o ícone
6. Nos gatilhos disponíveis, escolha Quando o Pluga Webhooks receber uma notificação da sua ferramenta
7. Uma mensagem será exibida indicando que a Pluga gerou uma URL de webhook para você. Esta URL estará no formato: https://webhooks.pluga.co/v1/webhook/xxxxx-xxxx-xxxx-xxxx
8. IMPORTANTE: Copie esta URL completa e salve em um local seguro e temporário (bloco de notas, editor de texto, etc.). Você precisará dela no próximo passo
9. Clique em Continuar para prosseguir

Detalhes técnicos: O Pluga Webhooks funciona como um receptor HTTP que aguarda requisições POST enviadas pelo NFE.io. Cada automatização recebe uma URL única que não deve ser compartilhada publicamente.

2. Configuração do Webhook no NFE.io

1. Em uma nova aba do navegador, acesse o painel administrativo do NFE.io em https://app.nfe.io/
2. Faça login com suas credenciais de administrador
3. No menu lateral, navegue até Configurações ou Preferências
4. Procure e clique em Webhooks ou Integrações > Webhooks
5. Clique no botão Adicionar Webhook
6. No formulário que aparecer, preencha os campos:

Campo	Valor
URL	Cole EXATAMENTE a URL fornecida pela Pluga no passo anterior
Content Type	Selecione application/json ou json no menu suspenso
Secret	(Opcional) Crie uma chave secreta para segurança adicional
Filters	Deixe vazio para receber todos os eventos ou selecione eventos específicos

7. VERIFIQUE cuidadosamente a URL para garantir que não tenha espaços em branco no início ou final
8. Clique em Salvar ou Criar Webhook
9. Confirme que o webhook aparece como Ativo na lista de webhooks

⚠️ Verificação crítica: O NFE.io tentará fazer uma chamada de teste para a URL fornecida. Se o status do webhook não mudar para "Ativo" ou exibir algum erro, verifique:

• Se a URL foi copiada corretamente
• Se seu ambiente NFE.io está em produção e não em sandbox/homologação
• Se há algum firewall bloqueando as chamadas

3. Configuração do Omie na Pluga

1. Retorne à aba da Pluga onde você estava configurando a automatização
2. Na coluna AÇÃO à direita, pesquise por Omie ERP na barra de pesquisa
3. Selecione a ferramenta Omie ERP clicando sobre o ícone
4. Nas ações disponíveis, escolha Criar um contas a receber
5. Caso já tenha conectado o Omie anteriormente, selecione a conexão existente. Caso contrário, siga os próximos passos
6. Clique em Conectar conta
7. Você precisará informar:
   • App Key: A chave da aplicação fornecida pelo Omie
   • App Secret: A senha secreta fornecida pelo Omie
8. Para obter as credenciais do Omie:
   • Acesse o painel do Omie
   • Vá em Preferências > Integração com outras plataformas
   • Na seção API para desenvolvedores, encontre ou gere suas credenciais
   • Copie a App Key e App Secret
9. Cole as credenciais do Omie nos campos correspondentes da Pluga
10. Clique em Autorizar ou Conectar
11. Aguarde a confirmação de que a conta foi conectada com sucesso
12. Clique em Continuar

🔑 Permissões necessárias: Certifique-se de que a App Key e App Secret que você está usando têm permissões para criar contas a receber e consultar/criar clientes no Omie. Permissões insuficientes causarão falhas na integração.

4. Mapeamento de Campos

Esta é a etapa mais importante e onde mais ocorrem erros! Siga com atenção.

1. Após conectar o Omie, a Pluga exibirá a tela de mapeamento de campos
2. Para cada campo obrigatório (marcado com asterisco *), você precisará selecionar os dados correspondentes do webhook do NFE.io

Cliente (campos obrigatórios)

Campo no Omie	Valor do NFE.io
Código de cliente/fornecedor	customer.federalTaxNumber
Nome/Razão social	customer.name
E-mail	customer.email

Dados da Nota Fiscal (campos obrigatórios)

Campo no Omie	Valor do NFE.io
Código de lançamento	id ou number
Número do documento	number
Valor do documento	amount
Data de emissão	issueDate
Data de vencimento	issueDate ou fórmula hoje + 30 dias

Campos fixos (configuração necessária)

Campo no Omie	Valor a configurar
Categoria	1.01.01 - Receitas Operacionais (ou outra apropriada)
Conta Corrente	Conta Padrão (ou outra apropriada)
Operação	Recebimento

Campos opcionais (recomendados)

Campo no Omie	Valor sugerido
Observação	NF-e {{number}} - {{customer.name}}
Número parcela	1/1 (se usar parcelamento)

Revise atentamente todos os mapeamentos para garantir que estão corretos.

📝 Nota técnica sobre formatos de data: O NFE.io geralmente envia datas no formato ISO (AAAA-MM-DD), enquanto o Omie espera datas no formato brasileiro (DD/MM/AAAA). A Pluga geralmente faz esta conversão automaticamente, mas verifique nas primeiras execuções.

5. Teste e Ativação

1. Nomeie sua automatização - Dê um nome significativo como "NFE.io para Omie - Contas a Receber"
2. Ative a automatização - Certifique-se que o toggle está ligado (geralmente verde)
3. Salve a configuração - Clique em Finalizar ou Salvar automatização

Teste a integração

1. Emita uma nota fiscal de teste no NFE.io com valores pequenos
2. Aguarde autorização da nota e processamento (geralmente leva de 30-60 segundos após autorização)
3. Verifique a execução na Pluga (no menu Histórico ou Logs da automatização)
4. Confirme no Omie o registro da transação (em Financeiro > Contas a Receber)

Teste novamente com pelo menos mais duas notas diferentes para garantir o funcionamento consistente.

Solução de problemas comuns

Problema	Solução
Webhook não é acionado	Verifique se a nota foi emitida e autorizada corretamente no NFE.io
Erro de cliente não encontrado	Verifique se o CPF/CNPJ está no formato correto e se o cliente existe no Omie
Erro de campo obrigatório	Revise o mapeamento de campos na Pluga
Erro de permissão	Verifique se as credenciais do Omie têm permissões suficientes

6. Monitoramento e Manutenção

1. Configure notificações de erro:
   • Na Pluga, acesse as configurações da automatização
   • Ative as notificações por e-mail para casos de falha
   • Adicione o e-mail das pessoas responsáveis pelo monitoramento
2. Estabeleça um processo de verificação periódica:
   • Diariamente: Verifique o histórico de execuções na Pluga
   • Semanalmente: Compare notas emitidas no NFE.io vs. títulos criados no Omie
3. Documentação:
   • Crie um documento interno descrevendo a integração
   • Salve capturas de tela de todas as configurações
   • Mantenha um registro das credenciais usadas
   • Registre os procedimentos de verificação e resolução de problemas

Considerações importantes

• Ambiente: O NFE.io deve estar em ambiente de produção e ativo para emissão
• Dados completos: O webhook do NFE.io envia todos os detalhes da nota fiscal
• Criação de clientes: A Pluga criará/atualizará automaticamente o cliente no Omie se não encontrar correspondência pelo CPF/CNPJ
• Campos obrigatórios: Certifique-se de que os campos obrigatórios do Omie estão sendo preenchidos corretamente
• Valores duplicados: Evite emitir a mesma nota fiscal várias vezes para não criar duplicidades no Omie
• Limites da Pluga: Verifique o limite de execuções no seu plano da Pluga

Dicas práticas

• A Pluga oferece suporte técnico via chat, não hesite em contatar para dúvidas específicas
• Mantenha suas credenciais de API do Omie seguras e atualize-as periodicamente
• Considere criar múltiplas automações para diferentes tipos de notas fiscais (produtos vs. serviços)
• Em períodos de alto volume de notas, monitore mais frequentemente o funcionamento da integração
• Crie um procedimento de emergência caso a integração falhe temporariamente

Referência de Campos NFE.io para Omie

Campo NFE.io	Campo Omie	Descrição	Obrigatório
id	codigo_lancamento_integracao	Identificador único da nota	✅
number	numero_documento	Número sequencial da nota fiscal	✅
customer.federalTaxNumber	codigo_cliente_fornecedor	CPF/CNPJ do cliente	✅
customer.name	cliente_fornecedor	Nome/Razão Social do cliente	✅
amount	valor_documento	Valor total da nota fiscal	✅
issueDate	da...