---
title: "Como emitir NFS-e e receber eventos da NFE.io no n8n"
description: "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."
source_url: https://nfe.io/docs/integracoes/plugins/n8n/
product: integracoes
last_updated: 2026-11-06
tags: ["how-to", "nfse", "emissao", "consulta", "webhook", "integracao", "plugin", "n8n"]
integration: ["plataforma"]
---

# Como emitir NFS-e e receber eventos da NFE.io no n8n

> Neste artigo você instala o pacote `n8n-nodes-nfe` no n8n, configura a credencial e monta workflows que emitem NFS-e, baixam o PDF e reagem aos eventos da NFE.io.

O [n8n](https://n8n.io/) é uma plataforma de automação de workflows, disponível na nuvem ou instalada no seu servidor. O pacote [`n8n-nodes-nfe`](https://www.npmjs.com/package/n8n-nodes-nfe) é mantido pela NFE.io, tem código aberto no [GitHub](https://github.com/nfe/n8n-nodes-nfe) 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.

:::info Onde o node instala hoje (situação em 06/11/2026)
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](#quando-usar-o-node-do-n8n).
:::

:::note Só NFS-e
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](../../../desenvolvedores/rest-api/intro.md) ou um [SDK oficial](../../../desenvolvedores/bibliotecas/intro.md).
:::

## 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](../../../documentacao/nossa-plataforma/criar-conta.md)) com pelo menos uma [empresa](../../../documentacao/nossa-plataforma/criar-empresa.md). Para emitir, a empresa precisa do [certificado digital](../../../documentacao/nossa-plataforma/upload-do-certificado-digital.md).
- 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](https://github.com/nfe/n8n-nodes-nfe#readme).

## 1. Instalar o pacote

No editor do n8n:

1. Abra **Settings > Community Nodes** e clique em **Install**.
2. 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:

```bash
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](https://docs.n8n.io/integrations/community-nodes/installation-and-management/gui-installation/) e [instalação manual](https://docs.n8n.io/integrations/community-nodes/installation-and-management/manual-installation/).

## 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](../../../documentacao/nossa-plataforma/chaves-de-autenticacao.md). 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 indicador `100301` (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](../../../documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/doc-ref-operationindicator-table-pt-br.md).
- O **Classification Code** (`cClassTrib`), por exemplo `000001`. A [correlação LC 116 × NBS](../../../documentacao/reforma-tributaria/conceitos-funcionais/tabelas-de-referencia/lc116-nbs-correlation-table-pt-br.md) 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](../../../documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc.md). 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 `flowStatus` igual a `Issued`, 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](../../../documentacao/webhooks/catalogo-de-eventos.md).
- **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](https://docs.n8n.io/build/integrate-ai/ai-examples/human-in-the-loop-for-tools/)) 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](https://github.com/nfe/n8n-nodes-nfe/tree/main/examples):

- 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-nfe` na URL; para removê-los, use a [API de webhooks](../../../documentacao/webhooks/como-cadastrar-consultar-listar-editar-e-excluir.md).
- 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 `deliveryId` para 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](https://github.com/nfe/n8n-nodes-nfe/blob/main/CHANGELOG.md).

## 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](../../plataformas/pluga/intro.mdx) 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](../../../desenvolvedores/rest-api/intro.md) ou um [SDK oficial](../../../desenvolvedores/bibliotecas/intro.md).
- **Assistente de IA fora do n8n** (Claude, Cursor e outros clientes MCP): use o [servidor MCP da NFE.io](../../../mcp/index.md).

## Precisa de ajuda?

- Status dos serviços: [status.nfe.io](https://status.nfe.io/)
- Problemas e sugestões do pacote: [issues no GitHub](https://github.com/nfe/n8n-nodes-nfe/issues)
- Dúvidas sobre a conta e a emissão: [suporte@nfe.io](mailto:suporte@nfe.io)
- Falhas de segurança: [hackers@nfe.io](mailto:hackers@nfe.io)