Guia do Usuário — Recebimento Automático de NF-e, CT-e e NFS-e (nfe.io)

Produto: DFe Inbound — Recepção Automática de Documentos Fiscais Público: Clientes (empresas usuárias do serviço) Atualizado em: 2026-04-30

---

Índice

1. O que é o DFe Inbound?
2. Como o Sistema Funciona?
3. Comparativo: NF-e, CT-e e NFS-e
4. Nota Fiscal Eletrônica (NF-e)
5. Conhecimento de Transporte Eletrônico (CT-e)
6. Nota Fiscal de Serviços Eletrônica (NFS-e)
7. O que é o Certificado Digital?
8. Ativando o Serviço — Passo a Passo Detalhado
9. Consultando Documentos Recebidos
10. Listagem em Lote via API — Para Grandes Volumes
11. Exportação em Massa — XML, PDF e CSV (Bulk Export)
12. Manifestação de Documentos — O que é e Por que Importa
13. Notificações Automáticas (Webhooks)
14. Segurança e Privacidade dos Dados
15. Reforma Tributária — O que Muda para Minha Empresa?
16. Dúvidas Comuns
17. Glossário

---

1. O que é o DFe Inbound?

Imagine que você tem uma empresa e recebe dezenas ou centenas de Notas Fiscais Eletrônicas (NF-e), Conhecimentos de Transporte (CT-e) e Notas Fiscais de Serviços (NFS-e) de fornecedores por mês. Antes, você precisaria:

• Acessar múltiplos portais (SEFAZ, prefeituras, SEFIN Nacional) manualmente
• Baixar cada documento um por um
• Guardar os arquivos XML em algum lugar
• Avisar seu sistema de gestão sobre cada documento novo

O DFe Inbound da nfe.io faz tudo isso automaticamente para você, cobrindo os três tipos de documento fiscal eletrônico mais relevantes para quem recebe:

1. Monitora continuamente o Ambiente Nacional da SEFAZ (NF-e / CT-e) e o Ambiente de Distribuição Nacional da SEFIN (NFS-e) em busca de novos documentos destinados ao seu CNPJ
2. Baixa e armazena todos os XMLs de forma segura na nuvem
3. Organiza os dados (emitente, valor, data, etc.) para consulta rápida
4. Avisa seu sistema automaticamente quando um documento novo chega

Para quem é este serviço?

• Empresas que compram mercadorias de fornecedores e precisam controlar as NF-es recebidas
• Empresas que contratam serviços de transporte e precisam controlar os CT-es
• Empresas que contratam serviços (consultoria, manutenção, software, etc.) e precisam controlar as NFS-es tomadas
• Empresas que precisam fazer a manifestação fiscal das NF-es e NFS-es recebidas
• Equipes de TI ou contabilidade que precisam integrar documentos fiscais com sistemas de gestão (ERP, TMS, etc.)

Os três subsistemas em uma frase

Subsistema	O que captura
DFe Inbound NF-e	Notas de compra de produtos que chegam para sua empresa
DFe Inbound CT-e	Conhecimentos de transporte emitidos por transportadoras onde sua empresa aparece como tomadora, expedidora, recebedora ou destinatária
DFe Inbound NFS-e	Notas de serviços tomados pela sua empresa (novo padrão nacional da LC 214/2025)

Cada subsistema pode ser ativado independentemente por CNPJ — você pode ligar só NF-e, só NFS-e, ou os três juntos, conforme a realidade da sua operação.

---

2. Como o Sistema Funciona?

O Fluxo Completo em 7 Passos

PASSO 1: Fornecedor emite o documento fiscal destinado à sua empresa
         (NF-e, CT-e ou NFS-e)
         ↓
PASSO 2: SEFAZ (NF-e/CT-e) ou Prefeitura/SEFIN (NFS-e) autoriza o documento
         ↓
PASSO 3: O documento é sincronizado com o Ambiente Nacional correspondente
         (SEFAZ AN para NF-e/CT-e; ADN/SEFIN para NFS-e)
         ↓
PASSO 4: O Ambiente Nacional registra o documento com um NSU
         (número sequencial único por CNPJ)
         ↓
PASSO 5: nfe.io detecta o novo documento consultando o Ambiente Nacional
         ↓
PASSO 6: nfe.io baixa o XML, extrai os dados e armazena tudo com segurança
         ↓
PASSO 7: Seu sistema é notificado automaticamente (webhook)
         ou você consulta quando precisar (API / painel)

Quanto tempo leva?

• NF-e e CT-e: entre 15 minutos e 4 horas após a autorização da SEFAZ. Em picos (final de mês, campanhas), pode aumentar.
• NFS-e: até cerca de 30 segundos após a disponibilização no ADN (pollings curtos). Quanto tempo a prefeitura/SEFIN leva para autorizar e publicar o documento depende do município emissor.

O que é o NSU?

O NSU (Número Sequencial Único) é um número que os ambientes nacionais atribuem a cada documento fiscal destinado ao seu CNPJ. Funciona como um "contador de correspondências":

• NSU 1000 → NF-e do fornecedor A
• NSU 1001 → NFS-e da empresa de consultoria B
• NSU 1002 → Cancelamento da NF-e do fornecedor A

Cada subsistema (NF-e/CT-e e NFS-e) tem seu próprio NSU, controlado separadamente. O nosso sistema usa o NSU para saber quais documentos já foram buscados e quais ainda precisam ser baixados — assim, nenhum documento é perdido ou duplicado.

---

3. Comparativo: NF-e, CT-e e NFS-e

As três operações são diferentes e têm regras próprias. Este quadro resume o essencial:

Aspecto	NF-e (modelo 55)	CT-e (modelo 57)	NFS-e (padrão nacional)
O que é	Nota fiscal de venda de produtos/mercadorias	Conhecimento de transporte de cargas	Nota fiscal de prestação de serviços
Quem emite	Vendedor (fornecedor de produtos)	Transportadora	Prestador de serviços
Quem recebe	Destinatário (comprador)	Tomador, expedidor, recebedor ou destinatário	Tomador do serviço
Fonte de distribuição	SEFAZ — Ambiente Nacional (AN)	SEFAZ — Ambiente Nacional (AN)	SEFIN Nacional — ADN (Ambiente de Distribuição Nacional)
Base legal/padrão	NT 2014/002, regime nacional	NT 2013/003, regime nacional	LC 214/2025 + padrão nacional NFS-e (transição municipal → nacional)
Chave de acesso	44 dígitos	44 dígitos	50 dígitos
Frequência de sincronização	A cada ~3 min	A cada ~3 min	A cada ~30 s
Documento complementar (PDF)	DANFE	DACTE	DANFSe
Manifestação do destinatário	4 tipos (Ciência, Confirmação, Desconhecimento, Operação Não Realizada)	Não aplicável (apenas consulta)	2 tipos (Ciência 203202, Rejeição 203206)
Prazo de retroatividade SEFAZ/SEFIN	90 dias	90 dias	Desde o início da produção do ADN (aprox. 2026)
Impostos destacados no XML	ICMS, IPI, PIS, COFINS + IBS/CBS/IS (Reforma Tributária)	ICMS, PIS, COFINS + IBS/CBS (Reforma)	ISS (municipal) + IBS/CBS (Reforma)

Quando eu preciso de cada um?

Sua situação	Você precisa de...
Sua empresa compra matéria-prima, mercadoria para revenda ou ativos fixos	NF-e
Sua empresa contrata frete, transporte rodoviário, aquaviário, ferroviário ou aéreo	CT-e
Sua empresa contrata serviços (consultoria, software, manutenção, terceirização, assessoria jurídica, etc.)	NFS-e
Sua empresa faz tudo isso	Os três juntos

Você pode ativar apenas os subsistemas que fazem sentido para sua operação. O plano contratado determina quais estão disponíveis.

---

4. Nota Fiscal Eletrônica (NF-e)

O que é uma NF-e?

A Nota Fiscal Eletrônica (modelo 55) é o documento fiscal digital emitido quando uma empresa vende produtos ou presta serviços para outra empresa. É o equivalente digital da antiga nota fiscal de papel.

Cada NF-e tem:

• Uma Chave de Acesso de 44 dígitos que a identifica unicamente no Brasil
• Um XML com todos os dados fiscais (emitente, destinatário, produtos, valores, impostos)
• Um DANFE (Documento Auxiliar) em PDF para visualização

Tipos de Registros de NF-e que você pode receber

Tipo	O que significa
NF-e Completa	Documento autorizado com XML completo disponível
Resumo de NF-e	Dados básicos disponíveis antes do XML completo chegar
Evento	Uma ação sobre a NF-e (cancelamento, correção, manifestação)
Resumo de Evento	Dados básicos de um evento

Eventos de NF-e

Além da NF-e em si, existem eventos que registram ações sobre ela:

Evento	O que significa para você
Cancelamento	O emitente cancelou a NF-e. Atenção: se você já recebeu a mercadoria, entre em contato com o fornecedor
Carta de Correção	O emitente corrigiu um dado da NF-e (exceto dados fiscais críticos)
Ciência da Operação	Você (ou o sistema automaticamente) confirmou que tem ciência desta NF-e
Confirmação da Operação	Você confirmou que recebeu a mercadoria conforme descrito
Desconhecimento da Operação	Você informou à SEFAZ que não reconhece esta NF-e
Operação Não Realizada	Você informou que a operação não foi concluída

---

5. Conhecimento de Transporte Eletrônico (CT-e)

O que é um CT-e?

O Conhecimento de Transporte Eletrônico (CT-e) é o documento fiscal obrigatório emitido pelas transportadoras para acobertar as prestações de serviço de transporte de cargas.

Quando você compra mercadorias de um fornecedor e a transportadora é diferente do fornecedor, você pode receber:

• Uma NF-e (da venda das mercadorias pelo fornecedor)
• Um CT-e (do serviço de transporte pela transportadora)

Partes Envolvidas em um CT-e

Parte	Descrição
Emitente	A transportadora que emitiu o CT-e
Tomador	Quem contratou o serviço de transporte (pode ser você)
Expedidor	Quem entregou a carga para transporte
Receptor	Quem recebeu a carga no destino
Destinatário	Para quem a carga foi enviada (geralmente você)

Você pode aparecer em qualquer um desses papéis, e o CT-e será distribuído para o seu CNPJ em todos os casos.

---

6. Nota Fiscal de Serviços Eletrônica (NFS-e)

O que é uma NFS-e?

A Nota Fiscal de Serviços Eletrônica (NFS-e) é o documento fiscal emitido sempre que uma empresa presta um serviço para outra empresa ou para um consumidor. Diferente da NF-e (que cobre produtos), a NFS-e cobre serviços — consultoria, software, transporte de pessoas, manutenção, educação, saúde, assessoria, tecnologia, entre muitos outros.

Por que existe um novo padrão nacional?

Historicamente, a NFS-e era emitida pela prefeitura de cada município, e cada prefeitura tinha seu próprio layout, site e regras. Para uma empresa com fornecedores de vários municípios, isso significava acompanhar dezenas de portais diferentes.

A Lei Complementar 214/2025 (Reforma Tributária) criou um padrão nacional e unificado de NFS-e. Agora os documentos são centralizados no Ambiente de Distribuição Nacional (ADN) da SEFIN Nacional, da mesma forma que a SEFAZ centraliza NF-e e CT-e. O DFe Inbound NFS-e consome esse ambiente nacional.

Como a NFS-e funciona no padrão nacional?

O fluxo envolve dois documentos distintos:

1. DPS (Declaração de Prestação de Serviço) — é o XML antes da autorização, submetido pelo prestador à SEFIN Nacional
2. NFS-e — é o XML após a autorização, assinado pela SEFIN, com a chave de acesso definitiva

Do ponto de vista de quem recebe (tomador do serviço), o que importa é a NFS-e autorizada — é ela que o DFe Inbound captura.

Tipos de Registros de NFS-e que você pode receber

Tipo	O que significa
NFS-e autorizada	Nota fiscal de serviço autorizada pela SEFIN, com XML completo
DPS	Declaração pré-autorização (geralmente só relevante para auditoria e casos de inconsistência)
Evento de registro	Registros oficiais vinculados à NFS-e (ex.: eventos fiscais, eventos do prestador)
Evento	Eventos vinculados diretamente a uma NFS-e (incluindo manifestação do tomador)

Partes Envolvidas em uma NFS-e

Parte	Descrição
Prestador (Provider)	A empresa que realizou o serviço e emitiu a NFS-e
Tomador (Borrower)	A empresa que contratou e pagou pelo serviço — geralmente você
Intermediário (opcional)	Uma terceira parte envolvida na contratação (ex.: plataforma, holding)

O DFe Inbound NFS-e captura toda NFS-e em que o seu CNPJ apareça como tomador.

Manifestação de NFS-e pelo Tomador

Diferente da NF-e, o padrão nacional da NFS-e oferece dois tipos de manifestação que o tomador (quem recebe o serviço) pode submeter:

Evento	Código	O que significa
Ciência	203202	"Estou ciente desta NFS-e destinada ao meu CNPJ"
Rejeição	203206	"Rejeito esta NFS-e — não reconheço o serviço, ou há inconsistência fiscal"

Para a Rejeição, a SEFIN exige um motivo codificado:

Código do motivo	Descrição
1	Duplicata
2	Já emitida pelo tomador
3	Sem fato gerador
4	Erro de responsabilidade tributária
5	Erro de valor, serviço ou data
9	Outros (texto livre em justification)

A Ciência pode ser automatizada pela plataforma, igual à Ciência da NF-e. A Rejeição é sempre manual por envolver juízo fiscal.

Identificando a NFS-e

Campo	Formato
Chave de Acesso NFS-e	50 dígitos (diferente da NF-e/CT-e, que têm 44)
Código do Serviço	Código municipal do serviço prestado (ex.: 01.01 = Análise e desenvolvimento de sistemas)
Código do Município	Código IBGE do município onde o serviço foi prestado

Diferenças práticas em relação à NF-e

• Não há conferência de mercadoria física — o serviço é imaterial. Por isso, as manifestações são apenas Ciência e Rejeição (não há "Confirmação de Operação" como na NF-e)
• A NFS-e pode ser emitida após o serviço já ter sido prestado, então a data de emissão não corresponde necessariamente à data da execução
• O valor do serviço fica em servicesAmount; não há campos equivalentes aos do XML da NF-e para quantidade de mercadoria, peso, etc.

---

7. O que é o Certificado Digital?

Por que precisamos do seu certificado?

O serviço de inbound se comunica com a SEFAZ (NF-e/CT-e) e com a SEFIN Nacional (NFS-e) em nome da sua empresa para buscar os documentos. Esses ambientes exigem autenticação por certificado digital — é como uma "assinatura eletrônica" que prova que somos você.

Sem o certificado configurado na plataforma, o sistema não consegue consultar esses ambientes e não há como receber os documentos. O mesmo certificado atende aos três subsistemas (NF-e, CT-e e NFS-e).

O que é um certificado digital?

É um arquivo eletrônico (ou cartão/token físico) que funciona como uma carteira de identidade digital da sua empresa. Ele contém:

• O CNPJ da empresa
• A chave criptográfica que prova a identidade
• A validade (geralmente 1 ou 3 anos)

Tipos de Certificado

Tipo	Como funciona	Quando usar
A1	Arquivo .pfx ou .p12 salvo no computador	Mais simples de usar. Ideal para integração com sistemas automatizados
A3	Cartão físico ou token USB	Mais seguro. O certificado não sai do dispositivo físico

Para o DFe Inbound, o certificado A1 é obrigatório, pois permite que nosso sistema faça as consultas automaticamente sem interação humana.

Como obter um certificado digital?

1. Acesse um dos Agentes de Registro credenciados pela ICP-Brasil (exemplos: Certisign, Serasa Experian, Valid, Soluti, SERPRO)
2. Escolha um certificado e-CNPJ (para pessoa jurídica)
3. O custo varia entre R$ 150 e R$ 400, dependendo da autoridade certificadora e da validade

Como configurar na plataforma nfe.io?

1. Acesse o Painel nfe.io → Empresas → {sua empresa} → Certificado Digital
2. Faça upload do arquivo .pfx ou .p12
3. Informe a senha do certificado
4. Clique em Salvar

Importante: Fique atento ao vencimento do seu certificado. Quando ele expirar, o sistema para de buscar novos documentos automaticamente. Configure um lembrete 30 dias antes do vencimento para renová-lo.

---

8. Ativando o Serviço — Passo a Passo Detalhado

Esta seção descreve em detalhe todo o processo de onboarding, da criação da conta até o primeiro documento capturado. Se você já completou alguma destas etapas, pode pular para a próxima.

Visão Geral do Onboarding

1. Criar conta principal (conta guarda-chuva) ─────► só uma vez por organização
                    ↓
2. Cadastrar empresa (CNPJ) na conta ─────────────► repetir por CNPJ
                    ↓
3. Enviar certificado digital A1 da empresa
                    ↓
4. Ativar o(s) subsistema(s) desejado(s) ──────────► NF-e, CT-e e/ou NFS-e
                    ↓
5. Configurar webhook (opcional mas recomendado)
                    ↓
6. Configurar manifestação automática (opcional)
                    ↓
7. Gerar API Key para integração com seu ERP
                    ↓
8. Monitorar os primeiros documentos capturados

Passo 1 — Criar a Conta Principal (Conta Guarda-Chuva)

A conta principal é o "teto" organizacional da sua empresa dentro da nfe.io. Ela agrupa todas as empresas (CNPJs), usuários, permissões e dados faturáveis em um único lugar. Em grupos econômicos com várias filiais ou marcas, uma única conta principal hospeda todos os CNPJs do grupo.

Como criar:

1. Acesse nfe.io e clique em "Criar conta"
2. Preencha dados do responsável (nome, e-mail corporativo, senha)
3. Confirme o e-mail (link enviado para a caixa de entrada)
4. Faça login em app.nfe.io
5. Na primeira sessão, você será guiado a preencher dados da organização (razão social, CNPJ principal, endereço, telefone de contato)

Se sua empresa já possui conta na nfe.io, pule este passo. Peça ao administrador da conta que adicione você como usuário com o papel apropriado.

Passo 2 — Cadastrar uma Empresa (CNPJ) na Conta

Dentro da conta principal, cada CNPJ monitorado é cadastrado como uma "empresa" independente. Você pode ter quantos CNPJs quiser, e ativar cada um de forma isolada.

Como cadastrar uma empresa:

1. No Painel, menu lateral → "Empresas" → "+ Nova Empresa"
2. Preencha:
   • CNPJ: o CNPJ da filial/matriz que deseja monitorar
   • Razão Social e Nome Fantasia
   • Endereço completo (CEP, logradouro, município, UF)
   • Inscrição Estadual (se aplicável)
   • Inscrição Municipal (obrigatória para NFS-e)
   • Regime Tributário (Simples Nacional, Lucro Presumido, Lucro Real)
3. Clique em "Salvar"

Ao salvar, a empresa fica cadastrada porém ainda inativa para inbound — os próximos passos ligam o recebimento.

Passo 3 — Enviar o Certificado Digital

Com a empresa cadastrada, o próximo passo é o certificado digital A1 (arquivo .pfx/.p12). Sem ele, nenhum subsistema de inbound consegue operar.

1. Painel → Empresas → {sua empresa} → "Certificado Digital"
2. Clique em "Enviar Certificado"
3. Selecione o arquivo .pfx ou .p12
4. Informe a senha do certificado
5. Clique em "Salvar"

O sistema valida:

• Se o CNPJ do certificado bate com o CNPJ da empresa
• Se o certificado ainda está dentro da validade
• Se a senha está correta
• Se a chave privada é acessível (necessária para assinar as requisições)

Em caso de erro, a plataforma mostra a mensagem específica. Os problemas mais comuns são CNPJ divergente e senha incorreta.

Passo 4 — Ativar o(s) Subsistema(s) de Inbound

Agora vem a parte principal: ligar o recebimento de documentos. Cada subsistema é ativado separadamente pela sua própria tela, pois tem configurações específicas.

4a. Ativando NF-e Inbound

1. Painel → Empresas → {sua empresa} → "Inbound" → "NF-e"
2. Clique em "Ativar"
3. Preencha:
   • Data de Início: a partir de qual data buscar documentos históricos (máx. 90 dias atrás — limite da SEFAZ)
   • Ambiente SEFAZ: Produção (operação real) ou Homologação (testes)
   • Manifestação Automática: habilitar/desabilitar, e delay em minutos (recomendado 60 minutos)
4. Clique em "Salvar e Ativar"

O sistema começa a consultar a SEFAZ Ambiente Nacional imediatamente.

4b. Ativando CT-e Inbound

1. Painel → Empresas → {sua empresa} → "Inbound" → "CT-e"
2. Clique em "Ativar"
3. Preencha Data de Início e Ambiente SEFAZ
4. Clique em "Salvar e Ativar"

CT-e não tem manifestação do destinatário, então não existe "Manifestação Automática" aqui.

4c. Ativando NFS-e Inbound

1. Painel → Empresas → {sua empresa} → "Inbound" → "NFS-e"
2. Clique em "Ativar"
3. Preencha:
   • NSU Inicial: por padrão 0 (começa do mais antigo disponível no ADN)
   • Ambiente SEFIN: Produção ou Homologação
   • Manifestação Automática (Ciência): habilitar/desabilitar, delay em segundos (máx. 604.800 = 7 dias; recomendado 3.600 = 1 hora)
4. Clique em "Salvar e Ativar"

A manifestação automática da NFS-e envia apenas o evento de Ciência (203202). A Rejeição é sempre manual.

Passo 5 — Configurar o Webhook (Opcional, Mas Recomendado)

Sem webhook, você depende de consultar periodicamente o painel ou a API. Com webhook, seu ERP é avisado no instante em que o documento chega.

1. Painel → "Webhooks" → "+ Adicionar URL"
2. Informe:
   • URL: o endpoint do seu sistema (ex.: https://meu-erp.com/api/webhooks/nfe)
   • Eventos: selecione quais eventos quer receber (NF-e nova, evento de NF-e, CT-e novo, NFS-e nova, manifestação submetida, etc.)
   • Cabeçalhos customizados (opcional, útil se seu endpoint exige autenticação)
3. Clique em "Testar" — o painel dispara uma notificação de teste para validar que o endpoint responde HTTP 200
4. Clique em "Salvar"

Veja seção 13 para mais detalhes.

Passo 6 — Configurar Manifestação Automática (Opcional)

Se você habilitou manifestação automática no Passo 4, o sistema registra automaticamente:

• NF-e: Ciência da Operação após o delay configurado
• NFS-e: Ciência (203202) após o delay configurado

Isso garante conformidade fiscal sem intervenção manual. Você ainda pode registrar manifestações mais específicas (Confirmação, Desconhecimento, Operação Não Realizada para NF-e; Rejeição para NFS-e) quando aplicável.

Passo 7 — Gerar uma API Key para Integração

Para que o ERP consuma a API nfe.io:

1. Painel → "API Keys" → "+ Nova API Key"
2. Nomeie a chave (ex.: ERP Produção)
3. Selecione os papéis (roles) que a chave terá:
   • Nota Fiscal (api.nfe.io) — cobre NF-e, CT-e e listagem em lote
   • NFS-e Inbound — cobre endpoints de NFS-e
   • Outros conforme contratado
4. Clique em "Gerar"
5. Copie e guarde a chave em local seguro — ela é exibida apenas uma vez

Trate a API Key como uma senha. Nunca exponha em código versionado em repositório público, em logs ou em prints.

Passo 8 — Monitorar os Primeiros Documentos

Nas primeiras horas após ativação, você deve ver:

• Documentos aparecendo na lista "Documentos Recebidos"
• O indicador "Último NSU processado" avançando
• Webhooks sendo disparados (se configurados)

Sinais de problema a observar:

Sintoma	Possível causa	O que fazer
Último NSU não avança	Certificado expirado ou CNPJ não habilitado na SEFAZ/SEFIN	Renovar certificado; abrir chamado na SEFAZ
Status "Inativo" em vermelho	Falhas consecutivas (circuit breaker acionou)	Ver detalhe do erro no painel; reativar após corrigir
Webhooks não chegam	URL incorreta ou servidor recusando	Testar URL no painel; checar logs do seu endpoint
"Rate limited until {data}"	SEFAZ/SEFIN aplicou throttle temporário	Aguardar — a captura retoma automaticamente

Como Saber se Está Funcionando?

No painel de cada subsistema, você verá:

• Status: "Ativo" (verde) ou "Inativo" (vermelho)
• Último NSU processado: número do último documento buscado
• NSU máximo disponível: indica se há documentos pendentes
• Data da última execução: quando ocorreu a última busca
• Falhas consecutivas: contador que dispara o circuit breaker se muito alto

Se "Último NSU processado" estiver igual ao "NSU máximo disponível", estamos em dia — não há documentos novos.

---

9. Consultando Documentos Recebidos

Via Painel nfe.io

No painel da empresa, acesse "Documentos Recebidos" e escolha o subsistema (NF-e, CT-e ou NFS-e). Você verá uma lista com:

• Data de emissão
• Emitente/Prestador (CNPJ e nome)
• Valor total / Valor do serviço
• Tipo (documento ou evento)
• Status

Clique em qualquer documento para:

• Ver todos os dados detalhados
• Baixar o XML
• Baixar o DANFE/DACTE/DANFSe (PDF)
• Consultar eventos vinculados (quando houver)

Filtros Disponíveis

Filtro	NF-e	CT-e	NFS-e
Período de emissão	✔	✔	✔
Tipo (documento/evento)	✔	✔	✔
Emitente/Prestador (CNPJ/nome)	✔	✔	✔
Faixa de valor	✔	✔	✔
Status de processamento	✔	✔	✔
Status do webhook	✔	✔	✔
Intervalo de NSU	✔	✔	✔
Código do serviço	—	—	✔

Baixando o XML

O XML é o arquivo oficial — contém todos os dados com validade jurídica e fiscal.

1. Encontre o documento na lista
2. Clique em "Baixar XML"
3. O arquivo .xml será baixado para o seu computador

Guarde os XMLs! A legislação exige que você mantenha os arquivos XML por pelo menos 5 anos.

Baixando o PDF (DANFE / DACTE / DANFSe)

O PDF é a representação visual do documento, usado para conferência e arquivo físico.

1. Encontre o documento na lista
2. Clique em "Baixar PDF"
3. O arquivo .pdf será baixado

---

10. Listagem em Lote via API — Para Grandes Volumes

Além das consultas individuais no painel e do recebimento automático via webhook, a nfe.io oferece endpoints de listagem em lote que permitem à sua equipe de TI baixar vários documentos de uma vez só. Essa funcionalidade é útil quando você precisa:

• Sincronizar um histórico completo — por exemplo, ao integrar um novo sistema de gestão (ERP) e precisar carregar todos os documentos dos últimos meses de uma só vez
• Fazer auditorias e conciliações contábeis — listar todos os documentos de um período para conferir com o livro fiscal
• Gerar relatórios consolidados — comparar volume de compras mês a mês, ticket médio por fornecedor, etc.
• Reprocessar documentos — caso o seu sistema ERP tenha ficado fora do ar e perdido webhooks, você pode "recuperar" os documentos em lote

Como funciona?

A ideia é simples: em vez de consultar um documento por vez, sua equipe de TI faz uma única chamada à API e recebe uma lista paginada de documentos.

┌─────────────────────────────────────────────────┐
│  Seu sistema ERP                                │
└────────────────────┬────────────────────────────┘
                     │
                     │ 1. Pede "me dê as próximas 100 notas"
                     ▼
┌─────────────────────────────────────────────────┐
│  API nfe.io — Listagem em Lote                  │
└────────────────────┬────────────────────────────┘
                     │
                     │ 2. Retorna 100 notas de uma vez
                     ▼
┌─────────────────────────────────────────────────┐
│  Seu sistema processa as 100 notas              │
└────────────────────┬────────────────────────────┘
                     │
                     │ 3. Pede as próximas 100 (paginação)
                     ▼
              ... até acabar

O que pode ser listado em lote?

Listagem	O que retorna
NF-e (ProductInvoices)	Todas as notas fiscais de produto destinadas ao seu CNPJ, filtradas por ambiente (produção ou homologação)
Eventos de NF-e (ProductInvoiceEvents)	Todos os eventos de uma NF-e específica (ciência, confirmação, cancelamento, carta de correção, etc.)
CT-e (TransportationInvoices)	Todos os conhecimentos de transporte destinados ao seu CNPJ de uma data específica
Eventos de CT-e (TransportationInvoiceEvents)	Todos os eventos de CT-e recebidos em uma data específica
NFS-e (ServiceInvoicesInbound)	Todas as NFS-es tomadas pela sua empresa — paginação por NSU, suporta filtros por ambiente, CNPJ do prestador, período de emissão e de recebimento
Eventos de NFS-e	Eventos vinculados a uma NFS-e específica (incluindo manifestações)

Paginação — como "virar de página"

Como o volume pode ser grande (milhares ou até milhões), a API entrega os documentos em páginas de até 1000 registros por vez (tamanho recomendado: 100 registros).

• NF-e e CT-e usam um cursor do tipo skiptoken (OData)
• NFS-e usa paginação pageIndex/pageCount baseada em NSU ascendente — você passa pageIndex=1, 2, 3... até a API devolver uma página vazia

Em todos os casos, a ordenação é crescente por NSU — isso garante que nenhum documento seja pulado, mesmo se chegarem novos durante a iteração.

Por que usar listagem em lote em vez de webhooks?

Use a listagem em lote quando:

• Você está integrando pela primeira vez e precisa processar os documentos já recebidos
• Seu sistema ficou fora do ar por um período e perdeu webhooks
• Você precisa gerar um relatório histórico ou fazer uma conciliação contábil
• Você quer fazer um processamento periódico (ex: rotina noturna que consulta tudo do dia)

Use os webhooks quando:

• Você quer ser notificado em tempo real sobre cada documento novo
• Seu sistema precisa reagir imediatamente à chegada de uma nota (ex: liberar um pagamento, abrir uma OS)

Dica: o ideal é usar os dois mecanismos juntos — webhooks para o dia a dia e listagem em lote para situações especiais (integração inicial, recuperação, auditorias).

Quem pode usar a listagem em lote?

• Sua equipe de TI (através da nossa API, documentada em detalhes no guia técnico para desenvolvedores)
• O uso exige uma API Key com a role apropriada (Nota Fiscal (api.nfe.io) para NF-e/CT-e; NFS-e Inbound para NFS-e)

Se a sua empresa não tem equipe de TI interna, entre em contato com o suporte nfe.io para recomendarmos parceiros integradores.

Perguntas frequentes sobre listagem em lote

Quanto custa usar a listagem em lote?

Depende do seu plano na nfe.io. Em geral, as requisições de listagem estão incluídas no plano normal, sem custo adicional. Consulte seu contrato ou o time comercial.

Há limite de requisições?

Sim, há um limite de requisições por minuto (rate limit) para proteger o sistema contra sobrecarga. Em geral, esse limite é suficiente para qualquer integração normal. Sua equipe de TI receberá informações sobre o limite em headers de resposta.

Existe ordenação fixa dos resultados?

Sim. As listagens são sempre ordenadas do NSU mais antigo para o mais recente (ascendente). Isso garante que a paginação funcione de forma consistente e que nenhum documento seja pulado.

E se chegarem documentos novos durante a listagem?

Sem problemas. Como a paginação é baseada em cursor (NSU), novos documentos recebidos durante a iteração terão NSU maior que o cursor atual e serão incluídos naturalmente quando você chegar naquele ponto.

Posso filtrar por data de emissão, fornecedor ou valor?

Os filtros suportados variam por subsistema:

• NF-e: ambiente (environmentType)
• Eventos de NF-e: chave de acesso da NF-e pai
• CT-e: data de emissão (issuedOn)
• Eventos de CT-e: data de recebimento (receiptOn)
• NFS-e: ambiente, CNPJ do prestador/tomador, intervalo de NSU, período de criação, período de emissão, status de processamento, status de webhook, código do serviço

Para filtros mais específicos (fornecedor, faixa de valor, etc.), sua equipe de TI pode baixar os documentos e aplicar os filtros localmente depois.

---

11. Exportação em Massa — XML, PDF e CSV (Bulk Export)

11.1 O que é a Exportação em Massa?

Imagine que sua empresa recebeu 2.000 NF-es no mês passado e o pessoal da contabilidade pediu "manda todos os XMLs e uma planilha com o resumo de cada nota pra eu fazer o fechamento". Sem a Exportação em Massa, você teria duas opções dolorosas:

• Baixar uma por uma pelo console — clicar em cada nota, abrir, baixar XML, baixar PDF, repetir 2.000 vezes. Inviável.
• Implementar uma integração com a API — chamar GET /v2/companies/{id}/inbound/nfse paginado, depois para cada nota chamar GET /{id}/xml, GET /{id}/pdf ou GET /{id}/json, juntar tudo num ZIP, gerar planilha. Funciona mas exige programação + servidor + tempo.

A Exportação em Massa resolve isso com um clique no console ou uma única chamada de API. Você define um período (ex.: 01/04/2026 a 30/04/2026), escolhe um formato (XML, PDF ou CSV), e a NFE.io processa tudo nos servidores dela e te envia por e-mail um link para baixar um único arquivo com tudo pronto.

11.2 Os três formatos disponíveis

A NFE.io oferece três formatos de exportação, cada um com um caso de uso específico:

📑 XML — Para guarda fiscal e auditoria

• Conteúdo: todos os arquivos .xml originais e assinados das notas do período, compactados em um único arquivo .zip.
• Tamanho típico: 2.000 notas ≈ 80-200 MB de ZIP (cada XML tem 5-50 KB dependendo da complexidade).
• Quando usar:
  • Guardar pelos 5 anos que a legislação fiscal exige.
  • Enviar para auditoria fiscal (a Receita pede o XML, não o PDF).
  • Importar em sistemas contábeis que processam XML (Domínio, Sage, Conta Azul, etc.).
• O que não dá pra fazer com o XML: abrir e ler como um humano — é um formato técnico, cheio de tags. Para isso, use o PDF ou o CSV.

📄 PDF — Para visualização humana e impressão

• Conteúdo: todos os DANFEs (NF-e) ou DANFSes (NFS-e) em PDF, compactados em ZIP.
• Tamanho típico: 2.000 notas ≈ 200-500 MB de ZIP (PDFs são proporcionalmente maiores).
• Quando usar:
  • Imprimir pra anexar a processos físicos.
  • Enviar pra alguém que não tem leitor de XML (advogado, gerente, auditor independente).
  • Arquivar visualmente — alguns clientes preferem ler o PDF antes de processar o XML.
• Limitação importante: eventos de NF-e (cancelamento, carta de correção, ciência, etc.) e NFC-e (modelo 65) não têm DANFE — esses documentos são silenciosamente pulados na exportação PDF (sem mensagem de erro). Se você está esperando 2.000 PDFs e só recebeu 1.850, é provavelmente isso.

📊 CSV — Para análise, conciliação e BI ⭐ (mais usado pelo time fiscal)

• Conteúdo: uma única planilha (arquivo .csv) com uma linha por nota, contendo dados estruturados nas colunas (chave de acesso, emitente, valor, CFOP, status, evento relacionado, etc.).
• Tamanho típico: 2.000 notas ≈ 1-3 MB. Tamanho desprezível comparado a XML/PDF.
• Por que é o mais usado:
  • Abre direto no Excel / Google Sheets / Power BI / Tableau sem nenhuma conversão.
  • Permite filtros, agrupamentos, somas e gráficos em segundos.
  • Ideal para conciliação (cruzar com contas a pagar, com pedidos, com lançamentos contábeis).
• Quando usar:
  • Fechamento contábil mensal (somar valores, separar por CFOP, identificar notas canceladas).
  • Auditoria interna ("quantas notas vieram do fornecedor X?", "quanto pagamos de ICMS-ST esse mês?").
  • Relatórios para diretoria (importar no Power BI / Tableau / Looker).
  • Detectar anomalias (notas com valor muito maior que a média do fornecedor, divergências em CFOP, eventos de cancelamento que você não estava esperando).

11.3 Disponibilidade por subsistema

Subsistema	XML	PDF	CSV
NF-e Recebidas	✅ disponível	✅ disponível	✅ disponível (a partir de mai/2026)
NFS-e Recebidas	✅ disponível	✅ disponível	✅ disponível (a partir de mai/2026)
CT-e Recebidas	⏳ no roadmap	⏳ no roadmap	⏳ no roadmap

O suporte a CT-e em bulk export está sendo planejado para versões futuras. No momento, para baixar CT-es em massa, use a API de Listagem em Lote com download individual via GET /{accessKey}/xml e /pdf.

Per-document JSON (apenas NFS-e): além do bulk export em XML/PDF/CSV, o subsistema NFS-e Recebidas oferece um endpoint adicional por documento — GET /v2/companies/{companyId}/inbound/nfse/{id}/json — que devolve o XML capturado convertido em JSON literal, útil para integrações que preferem JSON ao XML. Não é um formato de exportação em massa: é um download alternativo do mesmo conteúdo do XML, uma nota por vez. Detalhes em 02-doc-tecnica-clientes-dev-nfse-inbound-api.md.

11.4 Como funciona por dentro (visão simplificada)

A exportação é assíncrona — significa que ela não acontece na hora em que você clica. O fluxo:

1. Você clica em "Exportar" no console (ou faz POST via API)
       ↓
2. NFE.io recebe o pedido e cria um "job" na fila
       ↓ (responde imediatamente: "ok, vou processar")
       ↓
3. Um worker da NFE.io pega o job:
   - Para cada dia do período, busca a lista de notas
   - Para cada nota, baixa o conteúdo (XML, PDF ou monta linha do CSV)
   - Vai escrevendo num arquivo temporário
       ↓
4. Quando termina, sobe o arquivo para um blob storage seguro (Azure)
       ↓
5. Gera um link expirável (válido por 7 dias) e envia por e-mail
       ↓
6. Você clica no link e baixa o arquivo

Tempo típico de processamento:

Volume	XML/PDF	CSV
100 notas (1 mês de empresa pequena)	30-60 segundos	10-20 segundos
1.000 notas (1 mês de empresa média)	3-8 minutos	30-60 segundos
10.000 notas (1 mês de empresa grande)	30-90 minutos	5-10 minutos

Por que CSV é tão mais rápido? Porque o CSV não baixa o XML/PDF de cada nota — ele só lê os metadados (que já estão indexados na base de dados da NFE.io). XML e PDF exigem download de cada arquivo individual, multiplicando o tempo.

11.5 O que tem dentro do CSV (a regra de "achatamento")

Esta é a parte mais importante de entender, porque o CSV tem uma peculiaridade conceitual que pode confundir no primeiro contato.

Por que existem "eventos relacionados"

Uma nota fiscal não fica estática depois de emitida. Ela pode receber eventos ao longo do tempo:

• Cancelamento — o emitente desistiu da operação.
• Substituição (NFS-e) — uma nova nota foi emitida no lugar dessa.
• Carta de Correção (NF-e) — pequenas correções textuais (não fiscais).
• Manifestação — você (destinatário) confirmou/discordou da operação.

Esses eventos são documentos separados na base da NFE.io, vinculados à nota original. Se você fizer a listagem completa (sem bulk export), pode trazer 2.000 notas + 350 eventos misturados. Confuso para análise.

A regra do "evento primário"

O CSV resolve isso assim:

"Cada linha do CSV é uma nota fiscal. Se essa nota tem eventos relacionados, eu escolho o evento mais relevante e coloco os dados dele nas últimas colunas. Os outros eventos não aparecem."

A escolha do evento mais relevante segue uma regra de prioridade (diferente entre NF-e e NFS-e, porque os domínios têm conceitos diferentes):

Para NFS-e Recebidas:

1. Se há um evento de Substituição (código 310611), ele vence — pega o mais recente.
2. Senão, se há um evento de Cancelamento (código 310610), ele vence — pega o mais recente.
3. Senão, pega o evento mais recente por data de geração (GeneratedOn).

Para NF-e Recebidas:

1. Pega o evento mais recente por data de emissão (IssuedOn).
2. Em caso de empate (mesma data), desempata pela chave de acesso (ordem alfanumérica) — garantia de ordem determinística.

Por que NFS-e tem prioridade Substituição/Cancelamento mas NF-e não? Porque o NFS-e expõe o EventCode (310610, 310611, etc.) como um campo separado nos metadados, e dá pra detectar Substituição vs Cancelamento sem abrir o XML. Já no NF-e, esse código vive dentro do XML do evento, e detectá-lo exigiria parsing extra. A regra "mais recente" funciona bem porque eventos NF-e em sequência cronológica (ciência → confirmação → cancelamento) seguem o ciclo de vida natural — o último evento é normalmente o mais relevante.

Quando uma nota não tem evento

As colunas de evento ficam vazias — mas a linha da nota continua sendo emitida. Você nunca perde uma nota por não ter evento.

Schema completo das colunas

📑 Para o detalhamento coluna-por-coluna (24 colunas no CSV de NFS-e, 18 no de NF-e), consulte o Guia de Uso do Console — seção 10. Lá tem a descrição de cada coluna individual.

11.6 Casos de uso típicos (real-world)

Caso 1 — Fechamento contábil mensal

A contadora roda no console no dia 5 de cada mês:

1. Acessa NF-e Recebidas → Exportar → CSV → período: mês anterior.
2. Recebe e-mail em ~2 minutos com o link.
3. Abre no Excel.
4. Filtra por status Issued (exclui canceladas).
5. Cria pivot table somando valor por CFOP.
6. Exporta o resumo para o sistema contábil.
7. Repete para NFS-e Recebidas.

Tempo total: 15-20 minutos para fechar o mês inteiro de uma empresa com 1.500 notas. Sem o CSV, seriam horas.

Caso 2 — Conciliação com contas a pagar

Time financeiro precisa cruzar NF-es recebidas com pagamentos efetuados:

1. Exporta CSV de NF-e do mês.
2. Exporta extrato de contas a pagar do ERP.
3. No Excel, faz VLOOKUP cruzando CNPJ do fornecedor + valor.
4. Identifica:
   • Notas sem pagamento correspondente (atrasadas ou não lançadas).
   • Pagamentos sem nota (problema fiscal — sem documento suporte).

Caso 3 — Power BI / dashboard executivo

Diretoria quer um dashboard mensal com:

• Top 10 fornecedores por valor.
• Variação YoY (year over year).
• % de notas canceladas (indicador de qualidade da operação).

Solução: agendar exportação CSV via API (curl + cron), salvar histórico em tabela do Power BI, montar visualizações. Atualiza sozinho todo mês.

Caso 4 — Auditoria SEFAZ

A SEFAZ pede "todos os XMLs do trimestre Q1 2026". Resposta:

1. Faz 3 exportações XML (uma por mês: jan, fev, mar — ou usa splitDays=true pra arquivos por dia).
2. Recebe 3 arquivos ZIP.
3. Envia para o auditor via canal seguro.

Tempo: minutos. Sem bulk export, seria proibitivo.

11.7 Como acompanhar uma exportação em andamento

Pelo console

Acesse Conta (no menu superior) → Exportações. A página lista todas as suas exportações dos últimos 90 dias, com colunas:

• Data de criação
• Tipo (NF-e XML, NFS-e CSV, etc.)
• Período solicitado
• Status (Pendente / Em Processamento / Concluído / Falhou)
• Quantidade de itens processados
• Tamanho do arquivo final
• Botão de Baixar (se Concluído)

Os estados possíveis:

• Pendente (cinza) — está na fila aguardando ser pega por um worker.
• Em processamento (azul, com ícone giratório) — em execução.
• Concluído (verde) — pronto, link disponível.
• Falhou (vermelho) — erro durante a execução. Clique em "Detalhes" pra ver a causa.

Por API (para integrações automatizadas)

Para times técnicos que querem integrar o status no próprio sistema:

GET /accounts({accountId})/subscriptions({subscriptionId})/exports({jobId})
Authorization: <SUA_API_KEY>

Resposta inclui status, downloadUrl (quando concluído), errorMessage (quando falhou), totalLines, failed (notas que erraram individualmente mas não pararam o job).

Detalhes técnicos completos no 02-doc-tecnica-clientes-nfe-cte-dev-pt.md e na Postman collection (folder 6. Bulk Export (shared-usage-api)).

11.8 Limites e boas práticas

Tamanho do período

• Recomendado: 1 mês por exportação (alinha com fechamento contábil).
• Máximo prático: 6 meses — acima disso o tempo de processamento e o tamanho do arquivo ficam inconvenientes.
• Para períodos longos: use o parâmetro splitDays=true (disponível via API e no console em opções avançadas) — gera um arquivo por dia em vez de um único arquivo gigante. Mais arquivos, mais fáceis de processar.

Notificação por e-mail

Se sua exportação vai levar mais de 1 minuto, marque "Notificar por e-mail" no console. Senão você precisa acompanhar manualmente em Conta → Exportações. O e-mail traz o link direto.

Idioma das colunas (CSV)

O CSV vem com cabeçalhos em português por padrão. Para receber em inglês, use o parâmetro language=en-US na chamada de API. No console ainda não há essa opção exposta — sai sempre em PT-BR.

Reexecução

A página de Conta → Exportações tem um menu ⋮ em cada linha com opção Reexecutar — útil quando o período é o mesmo mas você quer pegar dados atualizados (notas que chegaram entre a primeira execução e agora).

Quanto tempo o link de download fica disponível?

7 dias após conclusão. Depois disso o arquivo é deletado por política de privacidade e você precisa rodar nova exportação. Baixe rápido ou encaminhe o link pra quem precisa antes do prazo.

11.9 O que fazer se algo der errado

"Não foi possível enfileirar a exportação"

Erro temporário do servidor. Aguarde 30 segundos e tente novamente. Se persistir após 3 tentativas, verifique o status da NFE.io em status.nfe.io e, se estiver tudo "verde", abra chamado no suporte.

"Não foi encontrada uma chave de API ativa"

Sua conta tem várias API Keys e nenhuma delas está marcada como Ativa com a descrição "Nota Fiscal (api.nfe.io)". Vá em Conta → API Keys e ative (ou crie) uma chave com essa descrição.

Job está "Em processamento" há mais de 1 hora

Pode estar travado. Vá em Conta → Exportações e verifique se o status mudou. Se continuar "Em processamento" sem progresso, contate o suporte mencionando o ID do job (visível na URL ou nos detalhes).

CSV abriu no Excel com tudo numa coluna só

O Excel está usando o delimitador errado. Solução:

1. Abra o Excel antes do arquivo.
2. Dados → Obter Dados → Do Arquivo → CSV/Texto.
3. Selecione o arquivo CSV.
4. Na janela de importação, escolha delimitador: ponto-e-vírgula ;.
5. Encoding: ISO-8859-1 (ou Windows-1252).

Alternativa: Google Sheets detecta automaticamente o delimitador na maioria das vezes — basta arrastar o arquivo pra dentro.

Algumas notas estão como "failed" no resumo do job

O CSV/XML/PDF foi gerado, mas algumas notas não puderam ser processadas individualmente (problema de download, parsing, etc.). O resumo do job mostra totalLines (notas escritas) e failed (notas que erraram). Se failed > 0, abra os detalhes do job no console para ver os erros específicos por chave de acesso.

11.10 Por dentro: arquitetura (para quem se interessa)

A Exportação em Massa não roda no dfetech-distribution-api — roda num serviço separado chamado shared-usage-api (que originalmente foi feito para o módulo de medição de uso da plataforma e ganhou esse módulo de export depois).

O fluxo técnico:

1. Console / cliente API faz POST .../exports para o shared-usage-api com resource: "company-{nfse|nfe}-inbound-{xml|pdf|analytical-csv}".
2. O shared-usage-api cria um ExportJob no Azure Storage (state: Pending) e publica mensagem na fila Rebus.
3. Um Azure Function (AzExport) pega a mensagem, instancia o IExporter correspondente (ex.: NfeInboundAnalyticalDataExporter), e começa o processamento.
4. O exporter consome a mesma API pública do dfetech-distribution-api — exatamente os mesmos endpoints que sua integração usaria (GET /v2/companies/{id}/inbound/nfse?type=Nfse, GET /{id}, GET /{id}/xml, etc.). Não há atalho privado.
5. À medida que o exporter recebe dados, vai escrevendo em arquivo temp local. Quando termina (todos os dias do período processados), sobe o arquivo para o blob storage final.
6. Gera URL pré-assinada (HMAC, válida por 7 dias) e dispara notificação por e-mail via notification-sender-api.

Por que esse design? Porque centralizar exportações num único serviço permite observabilidade unificada (todas as exportações de NF-e, NFS-e, CT-e, faturas de uso, relatórios, etc. passam pelo mesmo pipeline e gravam log no mesmo lugar) e escala independentemente da API principal — picos de exportação (fechamento de mês) não impactam latência de quem está consultando uma nota individual.

---

12. Manifestação de Documentos — O que é e Por que Importa

O que é a Manifestação?

A manifestação é a forma como você comunica à SEFAZ ou SEFIN o que aconteceu com um documento destinado à sua empresa. É um processo legalmente relevante para empresas que utilizam a Escrituração Fiscal Digital (EFD).

Manifestação de NF-e

Por que é importante?

A SEFAZ precisa saber se você:

• Recebeu a mercadoria conforme descrito na NF-e
• Não reconhece aquela operação
• A operação não foi concluída (mercadoria devolvida, por exemplo)

Sem a manifestação, você pode ter problemas em auditorias fiscais.

Prazos para Manifestar NF-e

Os prazos são contados a partir da data de autorização da NF-e pela SEFAZ:

Tipo de Manifestação	Prazo Máximo
Ciência da Operação	Sem prazo fixo, mas recomendado o quanto antes
Confirmação da Operação	180 dias após a autorização da NF-e
Desconhecimento da Operação	180 dias após a autorização da NF-e
Operação Não Realizada	180 dias após a autorização da NF-e

Atenção: Após 180 dias sem manifestação de confirmação, desconhecimento ou operação não realizada, a SEFAZ pode considerar a operação como confirmada automaticamente. Mantenha seus registros em dia.

Tipos de Manifestação de NF-e

Ciência da Operação

O que significa: "Eu sei que existe esta NF-e destinada para mim."

Esta é a manifestação mais básica e deve ser feita assim que você toma conhecimento da NF-e. Não confirma recebimento físico.

Quando usar: Sempre que uma NF-e chegar para sua empresa — mesmo que você ainda não tenha recebido a mercadoria.

Confirmação da Operação

O que significa: "Recebi a mercadoria exatamente como descrito nesta NF-e."

Quando usar: Após conferir que a mercadoria chegou e está de acordo com o que foi faturado.

Desconhecimento da Operação

O que significa: "Não reconheço esta operação — não comprei nada disso."

Quando usar: Quando chega uma NF-e de uma compra que sua empresa não realizou. Pode ser uma fraude ou erro do emitente.

Atenção: Use com cuidado. Esta manifestação tem implicações legais e pode acionar investigação da SEFAZ sobre o emitente.

O que fazer se suspeitar de fraude:

1. Registre o Desconhecimento da Operação imediatamente
2. Documente a ocorrência internamente
3. Se identificar uso indevido do seu CNPJ, registre um Boletim de Ocorrência e notifique a Receita Federal
4. Entre em contato com sua assessoria jurídica ou contábil

Operação Não Realizada

O que significa: "A operação estava prevista, mas não foi concluída."

Quando usar: Quando a mercadoria foi devolvida, o pedido foi cancelado após a emissão da NF-e, ou qualquer situação onde a operação não se concretizou conforme descrito.

Manifestação de NFS-e

Diferente da NF-e, a NFS-e do padrão nacional aceita apenas duas manifestações pelo tomador:

Ciência (código 203202)

O que significa: "Estou ciente desta NFS-e destinada ao meu CNPJ."

Quando usar: Sempre que uma NFS-e chegar para sua empresa. É o equivalente à Ciência da Operação da NF-e.

Rejeição (código 203206)

O que significa: "Rejeito esta NFS-e — não reconheço ou há inconsistência."

Quando usar: Quando a NFS-e recebida tem algum problema fiscal ou não corresponde a nenhum serviço que sua empresa tomou.

A Rejeição exige um motivo codificado (ver seção 6) e pode incluir uma justificativa em texto livre (até 255 caracteres).

Não existem eventos de "Confirmação de Operação" ou "Operação Não Realizada" para NFS-e — a natureza imaterial do serviço não comporta esses conceitos.

Manifestação Automática

O serviço pode registrar automaticamente a manifestação de Ciência:

• NF-e: registra Ciência da Operação após o delay configurado (ex.: 60 minutos)
• NFS-e: registra Ciência (203202) após o delay configurado (ex.: 3.600 segundos = 1 hora)

Vantagens:

• Você não precisa manifestar manualmente cada documento
• Garante conformidade legal de forma automática
• Economiza tempo

Importante: A manifestação automática registra apenas a Ciência. Você ainda precisa registrar manualmente:

• NF-e: Confirmação da Operação, Desconhecimento ou Operação Não Realizada quando aplicável
• NFS-e: Rejeição (203206) quando aplicável

Como Manifestar Manualmente

No painel:

1. Abra o documento
2. Clique em "Manifestar"
3. Escolha o tipo de manifestação
4. Para Rejeição de NFS-e ou Desconhecimento/Operação Não Realizada de NF-e, informe o motivo/justificativa
5. Clique em "Enviar"

Via API: sua equipe de TI pode acionar a manifestação diretamente do ERP — veja o guia técnico para desenvolvedores.

O resultado da manifestação (aceite ou rejeição pela SEFAZ/SEFIN) chega via webhook, na API (GET /manifestations/{id}) ou no painel.

---

13. Notificações Automáticas (Webhooks)

O que é um Webhook?

Um webhook é uma notificação automática que enviamos para o seu sistema assim que um evento acontece — como quando uma NF-e, CT-e ou NFS-e nova é recebida.

Funciona como um "aviso automático": em vez de você ficar perguntando periodicamente "chegou algum documento novo?", nós avisamos você no momento exato em que algo acontece.

Para que serve?

Com webhooks, seu sistema pode:

• Importar automaticamente NF-es, CT-es e NFS-es para o ERP
• Iniciar o processo de conferência de mercadoria automaticamente
• Gerar alertas quando chegam documentos de alto valor
• Sincronizar dados fiscais em tempo real
• Liberar pagamentos a fornecedores mediante chegada da nota correspondente

Eventos que disparam um Webhook

Evento	Quando dispara
inbound.nfe.received	Nova NF-e capturada
inbound.nfe.event.received	Novo evento de NF-e (cancelamento, CC-e, manifestação)
inbound.cte.received	Novo CT-e capturado
inbound.cte.event.received	Novo evento de CT-e
inbound.nfse.received	Nova NFS-e capturada
inbound.nfse.event.received	Novo evento de NFS-e (inclui manifestações de outros atores)
inbound.manifestation.submitted	Resultado de manifestação submetida pela sua empresa

Como Configurar?

1. Acesse o Painel nfe.io → Webhooks
2. Clique em "Adicionar URL"
3. Informe a URL do endpoint no seu sistema que vai receber as notificações
4. Selecione os eventos que deseja receber
5. (Opcional) Adicione cabeçalhos customizados se seu endpoint exige autenticação
6. Clique em "Testar" para validar
7. Salve e ative

Sua equipe de TI precisará criar um endpoint (uma URL) que recebe e processa as notificações.

O que você recebe na notificação?

Quando um documento chega, enviamos uma notificação com:

• Tipo do evento
• Chave de acesso do documento
• NSU
• Data de emissão
• Dados do emitente/prestador
• Valor total / valor do serviço

Com esses dados, seu sistema pode buscar o XML completo via API se necessário.

Reentrega de Webhooks

Se o seu endpoint responder com erro (status HTTP 4xx/5xx) ou estiver fora do ar, o sistema tenta novamente automaticamente com backoff exponencial por até 24 horas. Se após o limite ainda não tivermos sucesso, marcamos a entrega como falha — mas o documento fica disponível para consulta via painel ou API (nenhum dado é perdido).

Reprocessando uma Notificação

Se você quiser receber novamente uma notificação específica (por exemplo, após corrigir um bug no seu endpoint):

• Via painel: abra o documento → "Reprocessar Webhook"
• Via API: endpoint de reprocessamento (consulte o guia técnico)

---

14. Segurança e Privacidade dos Dados

Onde os dados ficam armazenados?

Todos os XMLs e metadados dos seus documentos fiscais são armazenados em servidores na nuvem com:

• Criptografia em trânsito: Toda comunicação usa HTTPS/TLS 1.2+
• Criptografia em repouso: Os arquivos XML são armazenados com criptografia no storage
• Acesso isolado: Os dados da sua empresa são acessíveis apenas com sua API Key ou credenciais de usuário — nenhum outro cliente da plataforma tem acesso aos seus documentos

Por quanto tempo os dados ficam armazenados?

Os XMLs e metadados ficam armazenados por no mínimo 5 anos, em conformidade com o prazo de guarda exigido pela legislação fiscal brasileira (Art. 195 do CTN).

Após esse período, os dados podem ser arquivados ou excluídos conforme a política de retenção da plataforma. Você será notificado antes de qualquer exclusão.

LGPD — Lei Geral de Proteção de Dados

O processamento dos dados fiscais pela nfe.io está em conformidade com a Lei nº 13.709/2018 (LGPD):

• Os dados são tratados com base legal na obrigação legal (art. 7º, II) — a guarda de documentos fiscais é exigida pela legislação tributária
• Não compartilhamos seus dados fiscais com terceiros sem sua autorização explícita
• Você pode solicitar relatório de dados pessoais tratados pela plataforma através do suporte

Quem pode acessar os meus documentos?

Apenas:

1. Usuários da sua conta com as permissões corretas
2. Sistemas integrados que usam sua API Key
3. Equipe de suporte nfe.io em caso de acionamento para investigar problemas — sempre com registro de acesso

E o certificado digital?

Seu certificado digital A1 é armazenado com criptografia adicional. A senha que você informou não é armazenada em texto puro — é usada apenas no momento de carregar o certificado para comunicação com a SEFAZ/SEFIN.

Recomendamos renovar o certificado periodicamente e revogar imediatamente caso suspeite de uso indevido.

---

15. Reforma Tributária — O que Muda para Minha Empresa?

A Lei Complementar 214/2025 introduziu a Reforma Tributária brasileira, criando novos tributos que substituirão gradualmente os impostos atuais sobre consumo — e também unificou o padrão da NFS-e em nível nacional.

Os novos tributos em linguagem simples

Novo Tributo	O que é	Substitui
IBS (Imposto sobre Bens e Serviços)	Imposto sobre consumo cobrado pelos estados e municípios	ICMS e ISS
CBS (Contribuição sobre Bens e Serviços)	Contribuição federal sobre consumo	PIS e COFINS
IS (Imposto Seletivo)	Imposto sobre produtos prejudiciais à saúde/ambiente	IPI (parcialmente)

O que muda na prática nas notas fiscais?

As NF-es, CT-es e NFS-es emitidas a partir da implementação da Reforma Tributária passarão a ter novos campos no XML para informar os valores de IBS, CBS e IS, além dos impostos tradicionais (ICMS, ISS, PIS, COFINS, etc.).

Nossa plataforma já está preparada para receber e processar documentos com esses novos campos. Você não precisa fazer nenhuma configuração adicional — a atualização é transparente.

E a NFS-e?

A Reforma Tributária criou o padrão nacional único da NFS-e — é por isso que o subsistema NFS-e do DFe Inbound existe. Antes da LC 214/2025, cada prefeitura tinha seu próprio layout e portal. Agora:

• O layout é único em todo o Brasil
• A distribuição é centralizada no ADN da SEFIN Nacional
• A chave de acesso é padronizada em 50 dígitos

Municípios que ainda não migraram totalmente podem continuar a emitir localmente durante o período de transição — nesses casos, a nota é replicada no ADN.

O que muda para quem recebe documentos?

Para empresas que recebem NF-es, CT-es e NFS-es (como destinatárias/tomadoras), as mudanças são:

• Os documentos que chegarem terão mais informações de impostos no XML
• O processo de recebimento e manifestação não muda — continua igual
• Os dados de IBS, CBS e IS estarão disponíveis na consulta via API e no painel quando aplicável

Período de transição

A reforma prevê um período de transição de vários anos (até 2033). Durante esse período, os impostos antigos e os novos vão coexistir gradualmente. Isso significa que você vai receber documentos com os impostos antigos, com os novos, ou com ambos, dependendo do período e do fornecedor.

Nossa plataforma trata todos os formatos automaticamente.

Preciso fazer algo agora?

Não. Do ponto de vista da recepção de documentos, nenhuma ação é necessária da sua parte. O sistema da nfe.io se adapta automaticamente às novas versões do leiaute das notas fiscais.

Para emissão de NF-es, CT-es ou NFS-es, consulte seu contador ou o emissor de notas que você utiliza.

---

16. Dúvidas Comuns

O serviço cobre todos os documentos destinados ao meu CNPJ?

Sim. O DFe Inbound consulta os Ambientes Nacionais correspondentes:

• NF-e e CT-e → SEFAZ Ambiente Nacional
• NFS-e → SEFIN Nacional (ADN)

Esses ambientes concentram todos os documentos destinados ao seu CNPJ, independentemente do estado ou município emissor.

Posso ativar só um dos subsistemas?

Sim. NF-e, CT-e e NFS-e são ativados independentemente por CNPJ. Se sua empresa só contrata serviços (sem compras de mercadoria), basta ativar NFS-e. Se só recebe produtos e fretes, ative NF-e e CT-e. A combinação é sua escolha.

Qual a diferença entre webhook e listagem em lote?

• Webhook: notificação automática em tempo real. Cada documento novo gera uma notificação HTTP para o seu sistema assim que ele é recebido. Ideal para o fluxo normal do dia a dia.
• Listagem em lote: você faz uma requisição pontual à API e recebe vários documentos de uma vez. Ideal para sincronização inicial de histórico, recuperação após indisponibilidade do seu sistema, auditorias e relatórios consolidados.

O ideal é usar os dois mecanismos em conjunto — webhooks para o tempo real e listagem em lote para situações específicas. Veja a seção 10 para mais detalhes.

Documentos emitidos antes da ativação aparecem?

• NF-e e CT-e: sim, até 90 dias antes da ativação (limite da SEFAZ).
• NFS-e: sim, desde o início da disponibilidade no ADN (a SEFIN mantém histórico mais longo que a SEFAZ nos primeiros anos do padrão).

Se você precisar de documentos mais antigos que esses limites, será necessário obtê-los diretamente com o emitente.

O que acontece se a SEFAZ ou SEFIN ficar fora do ar?

Nosso sistema fica tentando a consulta periodicamente. Quando o ambiente voltar, ele retoma de onde parou e busca todos os documentos que chegaram durante a indisponibilidade. Nenhum documento é perdido.

Posso receber documentos de mais de um CNPJ?

Sim. Você pode ativar o serviço para cada CNPJ da sua empresa separadamente. Cada CNPJ tem sua própria configuração de inbound (por subsistema).

Meu fornecedor diz que emitiu a nota, mas não aparece no sistema. O que fazer?

1. Aguarde o tempo de sincronização: até 4h para NF-e/CT-e, até alguns minutos para NFS-e
2. Verifique se o CNPJ destinatário/tomador da nota é o mesmo que está configurado
3. Confirme com o fornecedor se a nota foi autorizada pela SEFAZ/SEFIN (não apenas emitida localmente)
4. Para NFS-e: confirme que o município emitente aderiu ao padrão nacional — municípios em transição podem ter latência adicional
5. Se o problema persistir, entre em contato com o suporte nfe.io informando a chave de acesso

Qual a diferença entre NF-e e NFC-e?

Documento	Modelo	Uso
NF-e	55	Venda entre empresas (B2B)
NFC-e	65	Venda para consumidor final (B2C) — substitui o cupom fiscal

O serviço de inbound foca em NF-e (modelo 55), pois são as notas destinadas à sua empresa.

Qual a diferença entre NFS-e e NF-e?

• NF-e cobre venda de produtos/mercadorias
• NFS-e cobre prestação de serviços

Uma mesma empresa pode emitir tanto NF-e quanto NFS-e, dependendo de o que está vendendo. Como destinatário, você pode receber dos dois tipos e cada um é tratado pelo subsistema correspondente.

Preciso pagar por cada documento recebido?

Depende do seu plano na nfe.io. Consulte a tabela de preços ou entre em contato com nosso time comercial.

O serviço funciona em ambiente de testes (homologação)?

Sim. Para cada subsistema, você pode configurar o ambiente:

• NF-e/CT-e: ambiente SEFAZ (Produção ou Homologação)
• NFS-e: ambiente SEFIN (Produção ou Homologação)

Documentos de homologação não têm validade fiscal — use apenas para testes de integração.

O que fazer se chegar um documento que parece fraude?

1. Não confirme a operação
2. Registre o Desconhecimento da Operação (NF-e) ou a Rejeição (NFS-e, código 203206 com motivo apropriado) imediatamente na plataforma
3. Verifique com seu departamento financeiro se houve alguma compra/serviço que não reconhece
4. Se confirmar fraude, registre um Boletim de Ocorrência (BO) e notifique a Receita Federal pelo e-CAC
5. Contate sua assessoria jurídica para avaliar as medidas cabíveis

---

17. Glossário

Termo	Definição
ADN	Ambiente de Distribuição Nacional — sistema central da SEFIN Nacional que concentra NFS-e do padrão nacional unificado
AN	Ambiente Nacional — sistema central da SEFAZ que concentra NF-e e CT-e de todos os estados
API	Interface de Programação de Aplicações — conjunto de endpoints HTTP que permitem que sistemas externos interajam com a plataforma nfe.io
API Key	Chave secreta de autenticação usada por sistemas para se identificar ao consumir a API nfe.io
CBS	Contribuição sobre Bens e Serviços — novo tributo federal criado pela Reforma Tributária (substitui PIS e COFINS)
Circuit Breaker	Mecanismo que desativa automaticamente a captura de uma empresa após muitas falhas consecutivas, para evitar punição por rate limit. Requer reativação manual após correção
CNPJ	Cadastro Nacional da Pessoa Jurídica — número de identificação fiscal da empresa
Conta guarda-chuva	Conta principal da nfe.io que agrupa todos os CNPJs, usuários e permissões de um mesmo grupo econômico
CT-e	Conhecimento de Transporte Eletrônico — documento fiscal obrigatório para transporte de cargas
Cursor (paginação cursor-based)	Técnica de paginação em que o ponto de continuação é um valor sequencial (NSU) em vez de um número de página
DACTE	Documento Auxiliar do CT-e — representação visual em PDF do CT-e
DANFE	Documento Auxiliar da NF-e — representação visual em PDF da NF-e
DANFSe	Documento Auxiliar da NFS-e — representação visual em PDF da NFS-e
DFe	Documento Fiscal Eletrônico — termo genérico para documentos fiscais digitais (NF-e, CT-e, NFS-e)
DPS	Declaração de Prestação de Serviço — XML submetido pelo prestador à SEFIN antes da autorização da NFS-e
EFD	Escrituração Fiscal Digital — obrigação de escriturar os documentos fiscais digitalmente
Evento	Ação que modifica ou complementa um documento fiscal (cancelamento, correção, manifestação)
Homologação	Ambiente de testes da SEFAZ/SEFIN — documentos sem validade fiscal real
IBS	Imposto sobre Bens e Serviços — novo tributo estadual/municipal criado pela Reforma Tributária (substitui ICMS e ISS)
Inbound	Recebimento — neste contexto, recepção de documentos fiscais de terceiros
IS	Imposto Seletivo — novo tributo sobre produtos prejudiciais à saúde ou ao meio ambiente
Listagem em lote	Consulta à API que retorna vários documentos de uma só vez (em páginas), em vez de um a um
LC 214/2025	Lei Complementar da Reforma Tributária — introduziu IBS, CBS e IS no sistema tributário brasileiro, e criou o padrão nacional da NFS-e
LGPD	Lei Geral de Proteção de Dados — lei brasileira que regula o tratamento de dados pessoais
Manifestação	Comunicado do destinatário/tomador à SEFAZ/SEFIN sobre o que aconteceu com um documento
NF-e	Nota Fiscal Eletrônica — documento fiscal digital para venda de produtos entre empresas (modelo 55)
NFC-e	Nota Fiscal de Consumidor Eletrônica — nota para venda ao consumidor final (modelo 65)
NFS-e	Nota Fiscal de Serviços Eletrônica — documento fiscal para prestação de serviços (padrão nacional LC 214/2025)
NSU	Número Sequencial Único — contador de documentos fiscais por CNPJ, atribuído pelo ambiente nacional (AN ou ADN). Também funciona como cursor de paginação nas listagens em lote
OData	Protocolo padronizado de consulta REST utilizado por alguns endpoints de listagem em lote
Prestador	Quem presta o serviço e emite a NFS-e — equivalente ao emitente na NF-e
Rejeição (NFS-e)	Manifestação do tomador indicando que a NFS-e não é reconhecida ou tem inconsistência (evento 203206)
SEFAZ	Secretaria da Fazenda — órgão estadual responsável pela administração tributária (NF-e, CT-e)
SEFIN Nacional	Secretaria Especial da Fazenda Nacional — órgão federal responsável pelo padrão nacional da NFS-e
Tomador	Quem contrata e paga pelo serviço — equivalente ao destinatário na NF-e
Webhook	Notificação automática enviada para um sistema externo quando um evento ocorre
XML	Formato do arquivo oficial de documentos fiscais eletrônicos

---

Para suporte, acesse nfe.io/suporte ou envie e-mail para [email protected].

Esta documentação é mantida pela nfe.io. Versão atual: 2026-04-24.