Como emitir NFS-e e receber eventos da NFE.io no n8n
Instale o node da NFE.io no n8n para emitir NFS-e com IBS/CBS, baixar PDF e XML, receber webhooks e consultar CNPJ e CEP em workflows de automação.
Como emitir NFS-e e receber eventos da NFE.io no n8n
Neste artigo você instala o pacote
n8n-nodes-nfeno n8n, configura a credencial e monta workflows que emitem NFS-e, baixam o PDF e reagem aos eventos da NFE.io.
O n8n é uma plataforma de automação de workflows, disponível na nuvem ou instalada no seu servidor. O pacote n8n-nodes-nfe é mantido pela NFE.io, tem código aberto no GitHub e licença MIT. Ele acrescenta dois nodes:
| Node | O que faz |
|---|---|
| NFE.io | Emite, consulta, lista e cancela NFS-e, baixa PDF e XML, envia a nota por e-mail, lista as empresas da conta e consulta CNPJ, inscrição estadual, CEP e código IBGE. Também funciona como ferramenta do AI Agent do n8n. |
| NFE.io Trigger | Inicia o workflow quando a NFE.io envia um evento de webhook, por exemplo "nota fiscal de serviço emitida". |
A interface dos nodes é em inglês, como todo o n8n. Este guia usa os nomes que aparecem na tela e descreve a versão 0.2.1 do pacote.
O n8n-nodes-nfe ainda não é um node verificado pelo n8n. O n8n Cloud só aceita nodes verificados, então hoje o pacote instala apenas em n8n self-hosted (instalado no seu servidor ou container), pelo editor ou por npm. Esta situação muda quando o pacote for verificado. Sem instância própria, veja Quando usar o node do n8n.
O node NFE.io emite e gerencia apenas nota fiscal de serviço (NFS-e). Ele não emite NF-e, NFC-e nem CT-e. Para esses documentos, use a API REST ou um SDK oficial.
Ao final deste tutorial, você será capaz de:
- Instalar o pacote no n8n e configurar a credencial com as duas chaves da NFE.io
- Emitir uma NFS-e com o grupo da Reforma Tributária (IBS/CBS) e esperar a autorização
- Baixar o PDF e o XML como arquivo
- Iniciar workflows a partir dos eventos da NFE.io
- Usar a NFE.io como ferramenta de um agente de IA, com aprovação humana antes de emitir
Requisitos
- Conta na NFE.io (criar conta) com pelo menos uma empresa. Para emitir, a empresa precisa do certificado digital.
- n8n self-hosted com community nodes habilitados. O pacote foi testado no n8n 2.43.
- Para o gatilho: n8n acessível pela internet em HTTPS.
Operações do node NFE.io
| Resource | Operation | Para que serve |
|---|---|---|
| Service Invoice | Issue | Emite uma NFS-e e, por padrão, espera a autorização da prefeitura. |
| Get | Consulta uma nota pelo ID da NFE.io. | |
| Get by External ID | Consulta uma nota pelo identificador que você enviou na emissão. | |
| Get Many | Lista as notas de uma empresa, com filtro por data de competência e de criação. | |
| Cancel | Pede o cancelamento e, por padrão, espera a confirmação. | |
| Download PDF, Download XML | Baixa o arquivo da nota. | |
| Download Cancellation XML | Baixa o XML do evento de cancelamento. Só no Ambiente Nacional. | |
| Send Email | Envia a nota para o e-mail do tomador. | |
| Company | Get, Get Many | Consulta as empresas da sua conta. |
| Lookup | Get Company by CNPJ | Dados cadastrais de um CNPJ, numérico ou alfanumérico. Cobrada. |
| Get State Registration | Inscrições estaduais de um CNPJ em uma UF. Cobrada. | |
| Get Address by Postal Code | Endereço de um CEP. Cobrada. | |
| Get City Code by Postal Code | Código IBGE da cidade de um CEP. Gratuita. |
Os campos de cada operação estão na tela do node e no README do pacote.
1. Instalar o pacote
No editor do n8n:
- Abra Settings > Community Nodes e clique em Install.
- Digite
n8n-nodes-nfe, aceite o aviso de risco e clique em Install.
Os nodes NFE.io e NFE.io Trigger passam a aparecer no painel de nodes.
Em instalação própria com modo fila (queue mode), ou com a instalação pelo editor desligada, instale pelo terminal, como o usuário que roda o n8n, e reinicie o n8n:
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
npm install n8n-nodes-nfe
Com Docker, abra antes um terminal no container com docker exec -it <container> sh. No modo fila, instale na instância principal e em todos os workers. Detalhes na documentação do n8n: instalação pelo editor e instalação manual.
2. Configurar a credencial
Crie uma credencial do tipo NFE.io API. Ela tem dois campos:
| Campo | Obrigatório | Chave da NFE.io | Usada em |
|---|---|---|---|
| API Key | Sim | Chave de Nota Fiscal | Notas fiscais de serviço, empresas e webhooks |
| Data API Key | Só para as consultas cobradas | Chave de Dados | Consultas de CNPJ, inscrição estadual e CEP |
As duas chaves ficam no app de Conta, na aba Chaves de acesso da sua assinatura. Veja Chaves de autenticação. O node envia a chave certa para cada serviço da NFE.io, então uma credencial atende todas as operações.
3. Emitir uma NFS-e
Adicione o node NFE.io com Resource: Service Invoice e Operation: Issue. Os campos obrigatórios são:
- Company: escolha a empresa na lista (From List) ou informe o ID (By ID, aceita expressões).
- City Service Code: código de serviço do município da empresa.
- Description: discriminação dos serviços.
- Services Amount: valor dos serviços em reais.
O tomador (Borrower) pode ser preenchido campo a campo ou enviado como o objeto borrower da API em JSON. O tipo (pessoa física ou jurídica) é detectado pelo CPF ou CNPJ.
Impostos
Os grupos ISS e Federal Withholdings são opcionais. Sem eles, a NFE.io calcula ISS, alíquota e retenções pela configuração da empresa. Um valor informado substitui o cálculo automático, e só vai para a nota o campo que você acrescentar. PIS e COFINS retidos ficam em Federal Withholdings.
Reforma Tributária (IBS/CBS)
No grupo Tax Reform (IBS/CBS), acrescente Operation Indicator e Classification Code. São os dois únicos campos obrigatórios do grupo, cada um com seis dígitos, e a NFE.io calcula IBS e CBS.
- O Operation Indicator (
cIndOp) define onde o IBS/CBS é devido e qual endereço a nota precisa trazer. No indicador100301(consultoria e desenvolvimento de software, por exemplo), vale o endereço do tomador, que deve ter o código IBGE da cidade. Veja a tabela de indicadores. - O Classification Code (
cClassTrib), por exemplo000001. A correlação LC 116 × NBS sugere indicador e classificação por item de serviço.
Use Overrides (JSON) só para sobrepor o cálculo ou enviar outros campos do grupo, e Recipient (JSON) quando o destinatário for diferente do tomador. Os campos estão no layout da NFS-e com a Reforma Tributária. Confirme os códigos com a sua contabilidade.
Esperar a autorização
A NFE.io aceita a nota na hora e a prefeitura autoriza depois, em segundos ou minutos. Com Wait for Authorization ligado (padrão), o node consulta a nota a cada 2 segundos até a autorização ou a rejeição, por até Timeout (Seconds) (60 por padrão, no máximo 300):
- Autorizada: o item traz a nota final, com
flowStatusigual aIssued, pronta para o PDF. - Rejeitada pela prefeitura: o node falha com o motivo informado.
- Tempo esgotado: o item traz a nota como está, com
waitTimedOut: true. Consulte depois com Get ou use o gatilho.
Em lotes grandes, desligue a espera e acompanhe pelo NFE.io Trigger: o n8n mantém a execução aberta enquanto espera.
External ID e reexecução segura
Toda nota sai com um External ID, o identificador da venda no seu sistema (por exemplo, o número do pedido).
- Emitir de novo com um External ID que já existe devolve a nota existente, com
alreadyExisted: true, em vez de emitir outra. Reexecutar o workflow para o mesmo pedido é seguro. - Se a NFE.io não responder com clareza (tempo esgotado, falha de rede, erro 5xx), o node nunca reenvia a emissão: procura a nota pelo External ID por 30 segundos e, se não achar, para e mostra o External ID para você conferir antes de tentar de novo.
- Se o campo ficar vazio, o node gera um External ID que só protege as novas tentativas da mesma execução (Retry On Fail). Reexecutar uma execução que falhou gera outro ID e pode emitir outra nota. Sempre que a mesma venda puder chegar duas vezes ao node, informe um ID do seu sistema.
4. Baixar o PDF e o XML
As operações Download PDF, Download XML e Download Cancellation XML (evento de cancelamento, só no Ambiente Nacional) entregam um arquivo binário, no campo data por padrão, pronto para um node de e-mail, armazenamento ou mensagem.
5. Receber eventos com o NFE.io Trigger
O NFE.io Trigger cadastra um webhook na sua conta quando o workflow é ativado (ou quando você clica em Listen for test event) e o remove ao desativar (ou depois do evento de teste).
- Events: todos os tipos de evento da API, mais All Events. Veja o catálogo de eventos.
- Company (opcional): só inicia o workflow para eventos dessa empresa. Os webhooks da NFE.io são da conta inteira; sem o filtro, o workflow recebe eventos de todas as empresas da conta. Eventos sem empresa identificável sempre passam.
- Assinatura: toda entrega é conferida pelo cabeçalho
X-Hub-Signature(HMAC-SHA1 do corpo com um segredo criado pelo node). Entrega com assinatura inválida recebe HTTP 401 e não inicia o workflow.
Cada evento vira um item com event, resource, action, companyId, deliveryId e payload (para NFS-e, a própria nota).
6. Consultas de CNPJ e CEP
O resource Lookup consulta CNPJ (numérico e alfanumérico), inscrição estadual e endereço por CEP. Essas três consultas são cobradas por chamada, exigem a Data API Key, são validadas antes do envio e não são repetidas automaticamente. Get City Code by Postal Code devolve o código IBGE da cidade de graça, sem chave.
7. Usar com um agente de IA
O node NFE.io pode ser ligado ao AI Agent do n8n como ferramenta. Cada node de ferramenta executa uma operação, e a função $fromAI() deixa o modelo preencher campos como o ID da nota ou o CNPJ.
- Issue emite um documento fiscal de verdade. Ligue a ferramenta por uma revisão humana (human-in-the-loop) para que alguém aprove cada emissão.
- As consultas de CNPJ e CEP são cobradas: diga no prompt do agente quando ele pode usá-las.
- Fixe a empresa no node da ferramenta, em vez de deixar o modelo escolher.
O modelo de IA é seu: a conta e o custo do modelo ficam com você.
Workflows de exemplo
O repositório traz workflows prontos para importar:
- Pedido pago → emitir NFS-e com IBS/CBS → esperar a autorização → baixar o PDF → enviar por e-mail.
- Nota emitida (gatilho) → baixar o PDF → enviar no Telegram.
- Agente de IA que consulta notas e CNPJ e só emite depois da aprovação no chat.
Limitações
- Cada escuta de teste e cada ativação cria um webhook na conta. Ele é removido ao parar a escuta, ao chegar o primeiro evento de teste ou ao desativar o workflow.
- Antes de cadastrar, o gatilho remove as sobras com a mesma URL dele, por exemplo de uma escuta de teste reiniciada sem parar a anterior. Uma sobra de uma URL antiga do n8n continua na conta. Os webhooks criados pelo node têm
source=n8n-nodes-nfena URL; para removê-los, use a API de webhooks. - A NFE.io leva um momento para reconhecer um webhook novo. Depois de ativar um workflow pela primeira vez, espere dois minutos antes de contar com os eventos, e use Get Many com filtro de data para recuperar os eventos desse intervalo.
- Entregas repetidas não são descartadas: use o
deliveryIdpara ignorar repetições. - O formato dos eventos fora da NFS-e segue a documentação da NFE.io. Os eventos de NFS-e foram conferidos com entregas reais.
- As operações de NF-e e NFC-e ainda não estão no node de ações; o gatilho já recebe os eventos delas.
Atualizar da versão 0.1
A versão 0.2.0 refez o node. Workflows montados com a 0.1 precisam trocar cada node NFE.io antigo por um novo e preencher os campos de novo. Até a troca, o node antigo para a execução com a mensagem "This node was created with version 0.1 of n8n-nodes-nfe" e não envia nada à NFE.io. As credenciais existentes continuam valendo. A lista completa de mudanças está no CHANGELOG.
Quando usar o node do n8n
Use o node quando você já opera um n8n self-hosted e quer emitir e acompanhar NFS-e dentro dos seus workflows, sem escrever código. Nos outros casos, há um caminho mais direto:
- Sem instância própria do n8n: a Pluga conecta a NFE.io a outros apps sem nada para instalar ou hospedar.
- NF-e, NFC-e, CT-e ou controle total da integração: use a API REST ou um SDK oficial.
- Assistente de IA fora do n8n (Claude, Cursor e outros clientes MCP): use o servidor MCP da NFE.io.
Precisa de ajuda?
- Status dos serviços: status.nfe.io
- Problemas e sugestões do pacote: issues no GitHub
- Dúvidas sobre a conta e a emissão: [email protected]
- Falhas de segurança: [email protected]