Detalhamento do Processamento e Regras de Periodicidade — NF-e, CT-e e NFS-e Inbound

Produto	Captura Fiscal NFE.io (dfetech-distribution-api)
Documento	3 de 3 — Detalhamento por escrito do processamento, da periodicidade de captura e da conformidade com as regras do governo
Versão	1.1 — 24/09/2026
Público	Clientes, times de arquitetura, TI, auditoria e área fiscal
Documentos relacionados	1 de 3 — Arquitetura · 2 de 3 — Fluxos de processamento · English version

Sumário

1. Resumo executivo
2. Conceitos
3. Regras do governo que regem a captura
4. NF-e Inbound
5. CT-e Inbound
6. NFS-e Inbound
7. Quadro comparativo de periodicidade
8. Tempo esperado até o documento chegar ao cliente
9. Responsabilidades do cliente
10. Referências governamentais

1. Resumo executivo

A Captura Fiscal consulta os ambientes nacionais de distribuição de documentos fiscais em nome de cada empresa cliente, usando o certificado digital A1 da própria empresa. A captura é contínua e automática, e segue quatro regras de conduta:

1. Enquanto houver documentos pendentes no ambiente nacional, a NFE.io consulta de forma encadeada, lote após lote, sempre a partir do último NSU devolvido pelo próprio ambiente, até esvaziar a fila.
2. Quando o ambiente nacional informa que não há documentos novos, a NFE.io aguarda no mínimo 1 hora antes de consultar de novo aquela empresa. Essa é a regra de uso definida pelas Notas Técnicas para evitar a rejeição por consumo indevido.
3. Quando o ambiente nacional sinaliza restrição ou indisponibilidade, a NFE.io suspende as consultas por um período definido e retoma sozinha, sem intervenção do cliente. Na NF-e e no CT-e, rejeições bloqueiam a empresa por 1 hora e paralisações do serviço pausam as consultas por 5 ou 20 minutos. Na NFS-e, a suspensão ocorre quando o ADN sinaliza limite de consumo (HTTP 429), quando não há documentos novos, quando o ADN rejeita a consulta sem que nenhum documento tenha sido capturado e quando o certificado está indisponível.
4. As consultas pontuais (por NSU ou por chave de acesso) são limitadas a 20 por hora por CNPJ na NF-e e no CT-e. Só contam as consultas que retornam o documento. Elas não fazem parte da captura rotineira e aparecem apenas na recuperação de lacunas e no reprocessamento.

A única manifestação que a NFE.io envia automaticamente é a Ciência da Operação da NF-e (210210), quando a empresa a ativa. Manifestações conclusivas da NF-e e as manifestações do tomador da NFS-e são sempre decisão do cliente.

Em regime normal, um documento novo chega ao sistema do cliente em até cerca de 1 hora depois de ficar disponível no ambiente nacional. Durante uma carga inicial ou um pico de emissão, a captura é mais rápida, porque as consultas são encadeadas enquanto houver documentos.

2. Conceitos

Termo	Significado
Ambiente Nacional (AN)	Ambiente mantido pela administração tributária que centraliza a distribuição de NF-e e CT-e aos interessados. Para a NF-e, o Web Service é o NFeDistribuicaoDFe; para o CT-e, o CTeDistribuicaoDFe.
ADN	Ambiente de Dados Nacional do Sistema Nacional NFS-e, que distribui as NFS-e do Padrão Nacional, as DPS e os eventos aos contribuintes.
NSU	Número Sequencial Único. O ambiente nacional numera, por CNPJ interessado, cada documento ou evento disponibilizado. É o cursor da captura.
ultNSU	Último NSU pesquisado pelo ambiente nacional na resposta. A consulta seguinte deve partir dele.
maxNSU	Maior NSU existente no ambiente nacional para o CNPJ consultado. Quando ultNSU é igual a maxNSU, não há mais documentos pendentes.
cStat	Código de status da resposta dos Web Services da NF-e e do CT-e. Os mais relevantes são 138 (documento localizado), 137 (nenhum documento localizado) e 656 (consumo indevido).
docZip	Cada documento de um lote de distribuição, compactado em GZip e codificado em Base64.
Resumo (resNFe)	Conjunto de informações resumidas de uma NF-e, gerado pelo Ambiente Nacional para o destinatário antes da manifestação.
Manifestação do destinatário	Eventos pelos quais o destinatário da NF-e se posiciona sobre a operação: Ciência (210210), Confirmação (210200), Desconhecimento (210220) e Operação não Realizada (210240).
Cursor	O NSU a partir do qual a NFE.io fará a próxima consulta de uma empresa. É gravado a cada lote.
Consulta pontual	Consulta de um único documento, por NSU (consNSU) ou por chave de acesso (consChNFe), fora da distribuição sequencial.

3. Regras do governo que regem a captura

3.1 NF-e — Nota Técnica 2014.002 e schemas de distribuição

Regra	Conteúdo
Web Service	NFeDistribuicaoDFe, no Ambiente Nacional, com autenticação por certificado digital ICP-Brasil do interessado.
Modalidades de consulta	distNSU (distribuição a partir do último NSU recebido), consNSU (consulta de um NSU específico, para NSU faltante) e consChNFe (consulta pela chave de acesso).
Tamanho do lote	No máximo 50 documentos por resposta (loteDistDFeInt).
Continuidade	As consultas seguintes devem usar o ultNSU devolvido pelo Web Service.
Janela de disponibilidade	Com ultNSU igual a zero ou muito antigo, o Ambiente Nacional devolve os documentos recebidos nos últimos 3 meses. As consultas por NSU e por chave de acesso valem para documentos recebidos nos últimos 90 dias.
Espera sem documentos	Quando não houver mais documentos (cStat 137, ou ultNSU igual a maxNSU), o interessado deve aguardar 1 hora antes de nova consulta.
Consumo indevido	Consultas que desrespeitam as regras de uso recebem cStat 656 e o CNPJ fica bloqueado por 1 hora.
Quem recebe o quê	O destinatário recebe o resumo (resNFe) e, após a manifestação de Ciência, Confirmação ou Operação não Realizada, a NF-e completa. Transportador e terceiros autorizados no grupo autXML recebem a NF-e completa. O emitente recebe os eventos distribuíveis, mas não a própria NF-e.

3.2 NF-e — Manifestação do destinatário (Nota Técnica 2020.001 e Ajuste SINIEF 07/05)

• Os eventos são registrados no Web Service NFeRecepcaoEvento4 do Ambiente Nacional.
• A Ciência da Operação (210210) não é manifestação conclusiva. Ela libera o XML completo, mas a NF-e continua sujeita à manifestação conclusiva (Confirmação, Desconhecimento ou Operação não Realizada) dentro do prazo fixado pela legislação.
• A Operação não Realizada (210240) exige justificativa de 15 a 255 caracteres.
• Os eventos do destinatário introduzidos pela Reforma Tributária do Consumo seguem a Nota Técnica 2025.002 e são registrados no ambiente de eventos indicado para eles.

3.3 CT-e — Nota Técnica 2015.002 e schemas de distribuição

Regra	Conteúdo
Web Service	CTeDistribuicaoDFe, no Ambiente Nacional, com autenticação por certificado digital do interessado e informação obrigatória da UF do autor (cUFAutor).
Modalidades de consulta	Apenas distNSU e consNSU. Não existe consulta por chave de acesso no Web Service de distribuição do CT-e.
Tamanho do lote	No máximo 50 documentos por resposta.
Janela de disponibilidade	Com ultNSU igual a zero ou muito antigo, são devolvidos os documentos dos últimos 3 meses.
Consumo indevido	O Web Service mantém controles contra tentativas sucessivas de buscar registros já disponibilizados e rejeita essas tentativas com cStat 656.
Quem recebe	Emitente, remetente, destinatário, expedidor, recebedor, tomador e terceiros autorizados (autXML). O CT-e completo é distribuído sem necessidade de manifestação.

3.4 NFS-e — Sistema Nacional NFS-e (Manual dos Contribuintes: APIs do ADN)

Regra	Conteúdo
API	GET /DFe/{NSU} do ADN, que devolve os documentos fiscais de serviço a partir do NSU informado, e GET /NFSe/{ChaveAcesso}/Eventos para os eventos de uma NFS-e.
Autenticação	TLS mútuo com certificado ICP-Brasil do contribuinte (e-CNPJ).
Quem recebe	O contribuinte consulta os documentos em que figura como emitente (prestador), tomador ou intermediário.
Continuidade	O contribuinte controla o último NSU recebido e retoma a partir dele.

Para a NFS-e, a NFE.io aplica por padrão a mesma disciplina de consumo da NF-e e do CT-e (espera de 1 hora quando não há documentos) e respeita integralmente a sinalização de limite de consumo do ADN (HTTP 429 com o tempo de espera indicado).

---

4. NF-e Inbound

4.1 Ativação e pré-requisitos

1. A empresa precisa estar cadastrada na NFE.io com certificado digital A1 válido (e-CNPJ ICP-Brasil). Certificados com chave em HSM não são suportados pela captura.
2. A captura é ativada por empresa, pela API ou pelo console, informando o ambiente da SEFAZ (produção ou homologação) e, opcionalmente, a Ciência da Operação automática, com o tempo de espera em minutos antes do envio (AutomaticManifesting.MinutesToWaitAwarenessOperation, mínimo de 5).
3. Na primeira ativação, a captura começa pelo NSU zero. Pela regra do Ambiente Nacional, a primeira sequência de consultas devolve os documentos recebidos nos últimos 3 meses. Depois disso, a captura segue apenas com os documentos novos.

4.2 Periodicidade de captura

Parâmetro	Valor	Finalidade
Ciclo do agendador	a cada 3 minutos	Avalia todas as empresas ativas e decide quais podem ser consultadas agora.
Elegibilidade	empresa com continuação pendente, ou última consulta há mais de 61 minutos	Garante que uma empresa sem documentos novos só volte a ser avaliada depois de 1 hora.
Trava de fila vazia	nova consulta bloqueada por 62 minutos depois de o cursor alcançar o maxNSU	Implementa a regra de espera de 1 hora da NT 2014.002, com margem de segurança.
Encadeamento	consulta imediata enquanto ultNSU for menor que maxNSU	Esvazia a fila do Ambiente Nacional o mais rápido possível, como prevê a NT.
Tempo limite por chamada	5 minutos	Evita consultas presas quando o Web Service está lento.

Na prática, uma empresa com a fila em dia é consultada uma vez por hora (intervalo efetivo de 62 a 65 minutos). Uma empresa com documentos pendentes é consultada em sequência, lote a lote, até alcançar o maxNSU.

4.3 Captura, passo a passo

1. Seleção. A cada 3 minutos, o agendador lista as empresas com captura ativa e envia uma mensagem de captura para cada empresa elegível. O identificador da mensagem combina a empresa e o NSU, o que impede duas capturas iguais em paralelo.
2. Verificações antes de consultar. A captura não chama o Web Service se: (a) houver pausa global ativa por paralisação da SEFAZ; (b) a empresa estiver bloqueada por rejeição recente, inclusive consumo indevido (cStat 656); (c) o cursor já estiver no maxNSU e a última consulta tiver menos de 62 minutos.
3. Certificado. O certificado A1 da empresa é obtido do serviço de certificados da NFE.io e carregado em memória. Certificado vencido interrompe a consulta.
4. Consulta. A NFE.io chama NFeDistribuicaoDFe na modalidade distNSU, com ultNSU igual ao cursor da empresa, o CNPJ da empresa e a UF do autor. As respostas com documentos e as rejeições (exceto 656) são arquivadas.
5. Resposta com documentos (cStat 138). O lote é gravado, um item de processamento é criado para cada NSU entre o primeiro NSU do lote e o ultNSU, e uma mensagem é enviada por NSU. O cursor é atualizado com o ultNSU e o maxNSU devolvidos. Se ultNSU ainda for menor que maxNSU, a próxima consulta é disparada imediatamente.
6. Resposta sem documentos (cStat 137). O horário da consulta é registrado e a empresa entra na espera de 1 hora.
7. Paralisação da SEFAZ. Para cStat 108 (serviço paralisado momentaneamente), as consultas de todas as empresas são pausadas por 5 minutos. Para cStat 109 (serviço paralisado sem previsão), por 20 minutos.
8. Consumo indevido (cStat 656). A rejeição é registrada e a empresa fica 1 hora sem novas consultas de distribuição. As consultas pontuais do mesmo CNPJ também ficam suspensas pela mesma hora (seção 4.6). O cursor é ajustado ao ultNSU devolvido pelo Ambiente Nacional, só para a frente: ele nunca recua e o maxNSU conhecido nunca diminui. O 656 não afeta a Ciência automática, que usa outro Web Service. Em operação normal, o 656 é evitado pela espera de 1 hora com a fila em dia, descrita no item 6 e na seção 4.2.
9. Outras rejeições. As demais rejeições são registradas e a empresa fica 1 hora sem novas consultas.
10. Falha de comunicação. A consulta é repetida automaticamente. Se a mesma consulta falhar repetidamente e atingir o limite de tentativas, ela é interrompida e encaminhada à equipe de operação, para não consumir o Web Service indefinidamente.

4.4 Processamento de cada documento

1. O item do NSU é lido, o docZip correspondente é localizado no lote arquivado, decodificado de Base64 e descompactado de GZip.
2. O tipo é identificado pelo atributo schema:

Schema	Tipo	Notificação
procNFe	NF-e completa autorizada	product_invoice_inbound — issued_successfully (recebida) ou outbound_successfully (emitida pela própria empresa)
resNFe	Resumo da NF-e	product_invoice_inbound_summary
procEventoNFe	Evento completo (cancelamento, carta de correção, manifestações etc.)	product_invoice_inbound — input_event_raised_successfully para manifestações do destinatário; event_raised_successfully para os demais
resEvento	Resumo de evento	product_invoice_inbound_summary — event_raised_successfully

3. São extraídos os metadados: chave de acesso, UF, número, série, data e hora de emissão com fuso, emitente, destinatário, transportador, valor total, tipo de operação e ambiente.
4. A direção é determinada: o documento é "emitido" somente quando a empresa é a emitente e não ocupa outro papel (destinatária ou transportadora); nos demais casos é "recebido".
5. O XML é gravado no armazenamento de objetos e os metadados no banco. Eventos são vinculados à NF-e de mesma chave.
6. O webhook é enviado e o uso é registrado.
7. Se o processamento falhar, o item volta para a fila e é repetido automaticamente. Itens parados por mais de 2 horas são reenviados pelo agendador.

4.5 Manifestação do destinatário

• Ciência automática (opcional). Quando ativada na configuração da empresa, cada resumo (resNFe) recebido agenda um evento 210210 — Ciência da Operação para depois do tempo de espera configurado (MinutesToWaitAwarenessOperation). No momento do envio, a NFE.io confere de novo a situação. A Ciência não é enviada se a empresa tiver desligado a Ciência automática, ou se o cliente já tiver uma manifestação conclusiva aceita para a chave. Uma manifestação conclusiva ainda pendente não cancela a Ciência, porque pode ser rejeitada. O evento é assinado com o certificado A1 da empresa e enviado ao NFeRecepcaoEvento4 do Ambiente Nacional. Há proteção contra envio duplicado para a mesma chave. Enquanto a Ciência aguarda o tempo de espera, o resumo não é reprocessado nem notificado de novo.
• Única manifestação automática. A Ciência da Operação é a única manifestação que a NFE.io envia sem pedido do cliente. Confirmação (210200), Desconhecimento (210220) e Operação não Realizada (210240) são sempre decisão do cliente e só são enviadas quando ele as registra.
• Manifestação pelo cliente. Pela API ou pelo console, o cliente registra Confirmação (210200), Ciência (210210), Desconhecimento (210220) ou Operação não Realizada (210240, com justificativa). A API também aceita os eventos do destinatário da Reforma Tributária (NT 2025.002), enviados ao ambiente de eventos correspondente. O envio é assíncrono: a API responde que o pedido está pendente e o resultado fica disponível para consulta.
• Resultado. cStat 135 ou 136 indica evento registrado. cStat 573 (evento duplicado) é tratado como sucesso. Outras rejeições encerram o pedido como rejeitado. Falhas de comunicação são repetidas automaticamente.
• XML completo. A NFE.io não precisa consultar a chave de acesso depois da Ciência. Registrada a manifestação, o Ambiente Nacional disponibiliza a NF-e completa (procNFe) com um novo NSU, que chega pelo fluxo normal de captura e gera o webhook issued_successfully.

4.6 Consultas pontuais (consNSU e consChNFe)

As modalidades consNSU e consChNFe não são usadas na captura rotineira. Elas aparecem apenas em duas situações excepcionais:

1. Recuperação de lacunas (consNSU), descrita na seção 4.7.
2. Reprocessamento solicitado pelo cliente para um NSU ou uma chave de acesso específicos. Nesse caso, a NFE.io procura primeiro o documento na própria base e só consulta o Ambiente Nacional se ele não existir localmente.

As consultas de recuperação são espaçadas por espera exponencial (de 1 minuto até 30 minutos, com variação aleatória) e limitadas a 8 tentativas por NSU.

Limite de consumo. As consultas pontuais são limitadas a 20 por hora por CNPJ, em janela deslizante:

• Só contam as consultas que retornam o documento. Uma consulta sem documento, rejeitada ou que falha devolve a vaga.
• O reenvio de um documento que já existe na base não consulta a SEFAZ e não consome a cota.
• Sem vaga, a consulta da fila interna é adiada até a próxima vaga, com espaçamento aleatório de até 30 minutos para não concentrar as retomadas. O adiamento não conta como tentativa.
• Sem vaga, um pedido feito pela API de reprocessamento recebe HTTP 429, com o cabeçalho Retry-After.
• Um cStat 656 numa consulta pontual suspende as consultas pontuais do CNPJ por 1 hora e também registra o bloqueio da empresa para a distribuição.

4.7 Recuperação de lacunas de NSU

Todos os dias, às 23h (horário de Brasília), uma rotina executada por uma única instância confere, para cada empresa ativa, a sequência de NSUs capturados nos últimos 3 dias. Todo NSU ausente no intervalo vira uma pendência de recuperação. A cada 5 minutos, as pendências são despachadas para consulta individual por consNSU. Quando o documento é recuperado, ele segue o processamento normal e gera o webhook. A recuperação respeita o limite de consultas pontuais da seção 4.6: lacunas grandes são recuperadas em até 20 documentos por hora por CNPJ.

4.8 PDF (DANFE)

O DANFE é gerado sob demanda, a partir do XML armazenado, na primeira solicitação de PDF. O arquivo gerado é guardado e reutilizado nas solicitações seguintes.

4.9 Como a NF-e Inbound obedece às regras do governo

Regra (NT 2014.002)	Implementação na NFE.io
Usar sempre o ultNSU devolvido	O cursor da empresa é gravado com o ultNSU de cada resposta e toda consulta distNSU parte dele.
Aguardar 1 hora quando não houver documentos	Trava de 62 minutos após o cursor alcançar o maxNSU, somada à elegibilidade de 61 minutos no agendador.
No máximo 50 documentos por lote	O lote é definido pelo Ambiente Nacional; a NFE.io processa todos os NSUs do intervalo devolvido.
Janela de 3 meses	A primeira ativação parte do NSU zero e recebe o histórico disponibilizado pelo Ambiente Nacional. A recuperação diária de lacunas atua sobre os últimos 3 dias, bem dentro da janela.
Uso excepcional de consNSU e consChNFe	Usados apenas em recuperação de lacunas e reprocessamento, com espera exponencial, limite de tentativas e limite de 20 consultas com documento por hora por CNPJ.
Evitar consumo indevido em situações de erro	Pausa global de 5 minutos (cStat 108) ou 20 minutos (cStat 109) em paralisações da SEFAZ e bloqueio de 1 hora da empresa após rejeição, inclusive 656, que também suspende as consultas pontuais do CNPJ. Em operação normal, o cStat 656 é evitado pela espera de 1 hora com a fila em dia.
Uma única consulta por vez por empresa	Mensagem com identificador determinístico e deduplicação, mais controle de estado da empresa.
Manifestação no Web Service de eventos	Envio assinado ao NFeRecepcaoEvento4, com proteção contra duplicidade. A Ciência automática respeita o tempo de espera configurado pela empresa e é a única manifestação enviada automaticamente.

---

5. CT-e Inbound

5.1 Ativação e pré-requisitos

1. Empresa cadastrada na NFE.io com certificado digital A1 válido. Certificados com chave em HSM não são suportados.
2. A captura é ativada por empresa, informando o ambiente da SEFAZ (produção ou homologação). A empresa pode configurar:
   • Filtro de tipos de evento: eventos fora da lista são guardados, mas não geram webhook.
   • Filtro de parte interessada: o webhook só é enviado quando a empresa ocupa um dos papéis escolhidos no CT-e (tomador, remetente, expedidor, recebedor ou destinatário). O documento continua disponível na API mesmo quando o webhook é suprimido.
3. A captura começa pelo NSU zero e, pela regra do Ambiente Nacional, a primeira sequência de consultas devolve os documentos dos últimos 3 meses.

5.2 Periodicidade de captura

Parâmetro	Valor	Finalidade
Ciclo do agendador	a cada 60 segundos	Avalia todas as empresas ativas.
Elegibilidade	empresa com continuação pendente, ou última consulta há mais de 60 minutos	Uma empresa sem documentos novos só volta a ser consultada depois de 1 hora.
Trava de fila vazia	nova consulta bloqueada por 1 hora depois de uma resposta sem documentos	Aplica ao CT-e a mesma regra de espera da NF-e.
Encadeamento	consulta imediata enquanto ultNSU for menor que maxNSU	Esvazia a fila do Ambiente Nacional.
Tempo limite por chamada	5 minutos	Evita consultas presas.

5.3 Captura, passo a passo

1. Seleção. A cada 60 segundos, o agendador envia uma mensagem de captura para cada empresa elegível. Empresas com captura em andamento não recebem nova mensagem.
2. Verificações antes de consultar. A captura não chama o Web Service se houver pausa global da SEFAZ, bloqueio da empresa por rejeição recente, ou se a última resposta tiver indicado fim da fila há menos de 1 hora.
3. Certificado e consulta. O certificado A1 é obtido em memória e a NFE.io chama CTeDistribuicaoDFe na modalidade distNSU, com ultNSU igual ao cursor, o CNPJ e a UF do autor. A requisição e a resposta são arquivadas.
4. Resposta com documentos (cStat 138). Todos os NSUs do lote são gravados, com paralelismo controlado. O cursor só avança depois que o lote foi persistido. Se algum NSU falhar na gravação, ele vira pendência de recuperação individual. Se ultNSU ainda for menor que maxNSU, a próxima consulta é disparada imediatamente.
5. Resposta sem documentos (cStat 137). O cursor avança e a empresa entra na espera de 1 hora.
6. Paralisação da SEFAZ. cStat 108 pausa todas as consultas por 5 minutos; cStat 109, por 20 minutos.
7. Outras rejeições, inclusive 656. A empresa fica 1 hora sem novas consultas de distribuição e o erro é registrado.
8. NSU além do máximo (cStat 589). A situação gera alerta crítico para a equipe de operação.

5.4 Processamento de cada documento

1. O docZip do NSU é localizado no lote arquivado, decodificado e descompactado.
2. O tipo é identificado pelo schema:
   • procCTe: CT-e completo. São extraídos chave, UF, data de emissão com fuso, tipo do CT-e, modal, valor total da prestação, emitente, remetente, expedidor, recebedor, destinatário, tomador e chaves das NF-e transportadas.
   • procEventoCTe: evento do CT-e. São extraídos tipo, sequência, data de registro e descrição.
3. A direção é determinada: o CT-e é "emitido" somente quando a empresa é a emitente e não ocupa nenhum outro papel; nos demais casos é "recebido".
4. Eventos cujo tipo não está na lista configurada são guardados como ignorados e não geram webhook.
5. O XML é gravado no armazenamento de objetos e os metadados no banco.
6. Se houver filtro de parte interessada, ele é aplicado. Os eventos seguem a decisão tomada para o CT-e ao qual pertencem.
7. O webhook transportation_invoice_inbound é enviado (issued_successfully, outbound_successfully ou event_raised_successfully) e o uso é registrado.
8. Itens com falha são repetidos automaticamente. Itens parados por mais de 2 horas são reenviados pelo agendador.

5.5 Recuperação de lacunas e reprocessamento

• Rotina diária às 23h (horário de Brasília): confere a sequência de NSUs dos últimos 3 dias e faz uma varredura até o cursor atual da empresa. Cada NSU ausente vira pendência e é consultado por consNSU a cada 5 minutos, com espera exponencial (1 minuto a 30 minutos, com variação aleatória) e até 8 tentativas. A resposta 137 para um NSU específico encerra a pendência, porque indica que o NSU não existe no Ambiente Nacional.
• Alertas de saúde: a rotina alerta a operação quando uma empresa com documentos pendentes fica muitas horas sem captura, ou quando o cursor fica à frente do Ambiente Nacional.
• Reprocessamento pela API: o cliente pode pedir o reprocessamento de um NSU, de um lote já arquivado (sem nova consulta à SEFAZ) ou o reenvio de webhooks por chave ou por data.
• Sem consulta por chave: como o Web Service de distribuição do CT-e não oferece consulta por chave de acesso, toda recuperação é feita por NSU.
• Limite de consultas pontuais: as consultas consNSU seguem o mesmo limite da NF-e (seção 4.6), de 20 com documento por hora por CNPJ. Só contam as que retornam o documento, e quem fica sem vaga é adiado sem consumir tentativa. Um cStat 656 numa consulta consNSU suspende as consultas pontuais do CNPJ por 1 hora.

5.6 PDF (DACTE)

O DACTE é gerado sob demanda, a cada solicitação, a partir do XML armazenado.

5.7 Como a CT-e Inbound obedece às regras do governo

Regra (NT 2015.002)	Implementação na NFE.io
Continuidade pelo ultNSU	Cursor gravado com o ultNSU de cada resposta, só depois da persistência do lote.
Controle de consumo indevido (656)	Espera de 1 hora após resposta sem documentos; bloqueio de 1 hora da empresa após 656 ou outra rejeição.
No máximo 50 documentos por lote	Lote definido pelo Ambiente Nacional; todos os NSUs do intervalo são processados.
Apenas distNSU e consNSU	A captura usa distNSU; consNSU só na recuperação de lacunas e no reprocessamento de itens, com limite de 20 consultas com documento por hora por CNPJ.
Janela de 3 meses	Primeira ativação a partir do NSU zero; recuperação diária sobre os últimos 3 dias.
Paralisação do serviço	Pausa global de 5 minutos (cStat 108) ou 20 minutos (cStat 109), com retomada automática.

---

6. NFS-e Inbound

6.1 Ativação e pré-requisitos

1. Empresa cadastrada na NFE.io com certificado digital A1 válido. O ADN exige TLS mútuo com o certificado do contribuinte, e a Captura Fiscal usa para isso o certificado A1 (arquivo); certificados com chave em HSM ainda não são suportados. A ativação é recusada se o certificado estiver ausente ou vencido.
2. A captura é ativada por empresa, informando o ambiente (produção ou produção restrita), a URL de webhook e, opcionalmente:
   • Captura de NFS-e emitidas pela própria empresa: desligada por padrão. Quando desligada, as NFS-e em que a empresa é apenas a prestadora não são listadas nem notificadas.
   • Data de corte: documentos anteriores a essa data são guardados, mas não aparecem na listagem nem geram webhook. A liberação desse histórico pode ser contratada posteriormente junto à NFE.io.

6.2 Periodicidade de captura

Parâmetro	Valor	Finalidade
Ciclo do agendador	a cada 30 segundos	Seleciona as empresas ativas que não estão em período de espera.
Lotes por execução	até 50 consultas seguidas por empresa	Esvazia rapidamente a fila do ADN; se sobrar, continua no ciclo seguinte.
Espera sem documentos	1 hora após NENHUM_DOCUMENTO_LOCALIZADO	Mesma disciplina de consumo aplicada à NF-e e ao CT-e.
Limite de consumo do ADN	tempo indicado no cabeçalho Retry-After do HTTP 429, ou 1 hora	Respeita integralmente a sinalização do ADN.
Rejeição do ADN (REJEICAO)	10 minutos de espera, só quando a execução não capturou nenhum documento	Evita repetir a mesma consulta rejeitada a cada 30 segundos. Depois de lotes capturados, a captura retoma no ciclo seguinte.
Certificado indisponível	1 hora de espera, com a empresa mantida ativa	Retoma sozinha quando o certificado for regularizado, sem perder documentos.
Concorrência	uma captura por empresa por vez, por trava distribuída	Evita consultas simultâneas do mesmo CNPJ.
Tempo limite por chamada	60 segundos	Evita consultas presas.

6.3 Captura, passo a passo

1. Seleção. A cada 30 segundos, o agendador seleciona as empresas ativas cuja última execução é anterior ao ciclo e que não estão em espera, e envia uma mensagem de captura para cada uma.
2. Trava. A captura obtém a trava da empresa. Se outra captura da mesma empresa estiver em andamento, a mensagem é descartada.
3. Certificado. O certificado A1 é obtido em memória. Se estiver ausente, vencido ou em HSM, a empresa entra em espera de 1 hora e continua ativa.
4. Consulta. A NFE.io chama GET /DFe/{NSU} do ADN, no modo de distribuição em lote, a partir do cursor da empresa. Cada requisição usa uma conexão TLS própria, com o certificado da empresa.
5. Documentos localizados. Uma mensagem de processamento é enviada para cada documento do lote e o cursor é gravado com o maior NSU recebido. A consulta se repete, até 50 vezes na mesma execução, enquanto houver documentos.
6. Nenhum documento localizado. O cursor é gravado e a empresa entra em espera de 1 hora.
7. HTTP 429. A empresa entra em espera pelo tempo indicado pelo ADN (ou 1 hora, se não houver indicação).
8. Rejeição. Os códigos de erro devolvidos pelo ADN são registrados. Se a execução não tiver capturado nenhum documento, a empresa entra em espera de 10 minutos. Se já tiver capturado lotes, a consulta é refeita no ciclo seguinte.
9. Falhas transitórias (erros 5xx, timeout). Até 3 novas tentativas, com espera de 1, 2 e 4 segundos, dentro do tempo limite da chamada. Disjuntores por certificado (10 falhas) e global (50 falhas) interrompem as chamadas por 60 segundos para proteger o ADN em caso de instabilidade. Se a falha persistir, a captura é reagendada com espera exponencial de 1 minuto até 1 hora.
10. Certificado rejeitado pelo ADN. Cada rejeição conta uma falha consecutiva. Após 10 falhas seguidas, a captura da empresa é desativada e a equipe da NFE.io é notificada. A reativação é feita depois de corrigida a causa.

6.4 Processamento de cada documento

1. Idempotência. Se o NSU já foi processado para a empresa, a mensagem é ignorada.
2. Decodificação. O conteúdo é decodificado de Base64, descompactado de GZip e lido como UTF-8.
3. Classificação pelo elemento raiz: NFS-e autorizada, DPS, evento (cancelamento, cancelamento por substituição, confirmações e rejeições de prestador, tomador e intermediário, atos de ofício), pedido de registro de evento ou CNC. Documentos de tipo desconhecido são guardados com o XML e também notificados.
4. Armazenamento. O XML é gravado compactado no armazenamento de objetos.
5. PDF. Para NFS-e autorizadas, o DANFSe é gerado. Se o serviço de PDF estiver indisponível, o PDF fica pendente e é gerado no momento do download.
6. Metadados. Prestador, tomador, intermediário, códigos de serviço, valores e tributos, incluindo o grupo IBS/CBS da Reforma Tributária quando presente. Eventos são vinculados à NFS-e correspondente; a chave da NFS-e substituta é registrada nos eventos de substituição.
7. Direção. A NFS-e é "emitida" somente quando a empresa é a prestadora e não é tomadora nem intermediária.
8. Regras de entrega. O webhook não é enviado para documentos anteriores à data de corte (enquanto o histórico não for liberado) nem para NFS-e emitidas pela própria empresa quando essa captura estiver desligada.
9. Webhook e uso. O webhook service_invoice_inbound é enviado com a ação issued_successfully (NFS-e recebida), outbound_successfully (NFS-e emitida pela própria empresa) ou event_raised_successfully (eventos). O corpo traz também o campo eventName (inbound.serviceInvoice.received, inbound.serviceInvoice.issued ou inbound.serviceInvoice.event.received). O uso é registrado. Em caso de falha de entrega, há novas tentativas com espera exponencial, de 1 minuto até 1 hora.

6.5 Manifestação do tomador

• O cliente registra, pela API, Confirmação do Tomador (203202) ou Rejeição do Tomador (203206), esta com o motivo.
• A NFE.io não envia manifestação da NFS-e automaticamente. As duas são manifestações conclusivas do tomador e só são enviadas quando o cliente as registra. A NFS-e Nacional não tem um evento equivalente à Ciência da Operação da NF-e.
• O envio é assíncrono. A NFE.io confere o certificado e se o CNPJ do certificado é o do tomador, assina o pedido de registro de evento e o envia à Sefin Nacional.
• A manifestação registrada gera o webhook event_raised_successfully. A rejeição não gera webhook e fica disponível para consulta na API. Não é possível manifestar NFS-e emitidas pela própria empresa.

6.6 Captura sob demanda pela chave de acesso

O cliente pode pedir, pela API, a captura imediata de uma NFS-e pela chave de acesso de 50 dígitos. A NFE.io valida a chave, consulta a NFS-e diretamente na Sefin Nacional, armazena o XML, gera o PDF e devolve o documento na própria resposta. Se o documento já existir na base, ele é devolvido sem nova consulta. A captura sob demanda não gera webhook. Quando o mesmo documento chegar depois pela distribuição normal, ele é reconhecido, não é duplicado, e o webhook é enviado nesse momento.

6.7 Recuperação de lacunas

Todos os dias, às 23h (horário de Brasília), a rotina confere a sequência de NSUs capturados nos últimos 3 dias. Se encontrar lacuna, reinicia a captura da empresa a partir do NSU anterior à primeira lacuna. Os documentos já existentes são reconhecidos pela idempotência e apenas os ausentes são gravados e notificados.

6.8 Como a NFS-e Inbound obedece às regras do governo

Regra (Sistema Nacional NFS-e)	Implementação na NFE.io
Distribuição por NSU (GET /DFe/{NSU})	Cursor por empresa, gravado a cada lote, sempre com o maior NSU recebido.
TLS mútuo com certificado ICP-Brasil do contribuinte	Certificado A1 da própria empresa a cada requisição, TLS 1.2 ou 1.3, conexão isolada por requisição.
Somente documentos em que a empresa é parte	O ADN devolve apenas os documentos em que a empresa é prestadora, tomadora ou intermediária; a NFE.io classifica a direção de cada um.
Limite de consumo sinalizado pelo ADN	HTTP 429 respeitado com o tempo do Retry-After.
Uso moderado do serviço	Espera de 1 hora sem documentos, espera de 10 minutos após rejeição sem documentos capturados, uma captura por empresa por vez, disjuntores e retentativas curtas limitadas.

---

7. Quadro comparativo de periodicidade

Item	NF-e	CT-e	NFS-e
Serviço do governo	NFeDistribuicaoDFe (AN)	CTeDistribuicaoDFe (AN)	ADN — GET /DFe/{NSU}
Ciclo do agendador	3 min	60 s	30 s
Consulta com fila em dia	1 vez por hora (62 a 65 min)	1 vez por hora	1 vez por hora
Consulta com documentos pendentes	encadeada até ultNSU = maxNSU	encadeada até ultNSU = maxNSU	até 50 lotes por execução, a cada 30 s
Documentos por lote	até 50 (regra do AN)	até 50 (regra do AN)	definido pelo ADN
Após rejeição	empresa bloqueada 1 h, inclusive 656; o 656 também suspende as consultas pontuais	empresa bloqueada 1 h, inclusive 656	espera de 10 min se nada foi capturado na execução; HTTP 429 conforme Retry-After
Paralisação do serviço	pausa global de 5 min (108) ou 20 min (109)	pausa global de 5 min (108) ou 20 min (109)	retentativa, disjuntor de 60 s e reagendamento exponencial
Consulta por chave	somente reprocessamento pontual	inexistente no Web Service	captura sob demanda pela API
Consultas pontuais	até 20 com documento por hora por CNPJ (consNSU e consChNFe)	até 20 com documento por hora por CNPJ (consNSU)	não se aplica
Recuperação de lacunas	diária às 23h, janela de 3 dias	diária às 23h, janela de 3 dias	diária às 23h, janela de 3 dias
Manifestação	210200, 210210, 210220, 210240 e eventos da RTC, a pedido do cliente; Ciência automática opcional, após o tempo de espera configurado, é a única manifestação automática	não se aplica	203202 e 203206, somente a pedido do cliente

8. Tempo esperado até o documento chegar ao cliente

O tempo total tem duas parcelas:

1. Publicação no ambiente nacional. O intervalo entre a autorização do documento e a sua disponibilização no Ambiente Nacional ou no ADN depende do governo e não é controlado pela NFE.io.
2. Captura pela NFE.io. Com a fila da empresa em dia, a NFE.io consulta o ambiente nacional uma vez por hora, como exigem as regras de uso. Um documento publicado logo após uma consulta é, portanto, capturado em até cerca de 1 hora (na NF-e, até cerca de 65 minutos). O processamento, o armazenamento e o envio do webhook levam poucos segundos em condições normais.

Na ativação e em picos de emissão, a captura é mais rápida, porque as consultas são encadeadas enquanto houver documentos pendentes. Em datas de alto volume (como fechamento de mês) ou em indisponibilidades do governo, o tempo pode ser maior.

Documentos com urgência:

• NFS-e: use a captura sob demanda pela chave de acesso (seção 6.6).
• NF-e: o XML completo depende da manifestação do destinatário. Com a Ciência automática ativa, o evento é enviado depois do tempo de espera configurado pela empresa, e o XML completo chega na captura seguinte ao registro do evento. Um tempo de espera menor antecipa o XML completo.

9. Responsabilidades do cliente

Responsabilidade	Detalhe
Certificado digital válido	Manter o certificado A1 da empresa atualizado na NFE.io. Certificado vencido interrompe a captura (NF-e e CT-e) ou a coloca em espera (NFS-e).
Manifestação conclusiva da NF-e	A Ciência da Operação não é conclusiva. O registro de Confirmação, Desconhecimento ou Operação não Realizada dentro do prazo legal é decisão e responsabilidade do destinatário. A NFE.io nunca envia manifestação conclusiva automaticamente.
Manifestação do tomador da NFS-e	Confirmação (203202) e Rejeição (203206) do tomador são decisão do cliente e só são enviadas quando ele as registra pela API.
Webhook idempotente	Tratar notificações repetidas usando a chave de acesso, o identificador do evento ou o NSU, e responder com HTTP 2xx.
Validação da assinatura do webhook	Validar a assinatura de cada notificação, conforme a documentação de webhooks da NFE.io.
Downloads	Não armazenar as URLs assinadas de download; solicitar uma nova quando necessário.

10. Referências governamentais

• Portal Nacional da NF-e — https://www.nfe.fazenda.gov.br/portal
  • Nota Técnica 2014.002 — Web Service de Distribuição de DF-e de Interesse dos Atores da NF-e (regras de uso, consumo indevido e limites).
  • Schemas distDFeInt_v1.01.xsd e retDistDFeInt_v1.01.xsd (modalidades de consulta, lote de até 50 documentos, janela de 3 meses).
  • Nota Técnica 2020.001 — Manifestação do Destinatário.
  • Nota Técnica 2025.002 — Eventos da Reforma Tributária do Consumo.
• Portal Nacional do CT-e — https://www.cte.fazenda.gov.br/portal
  • Nota Técnica 2015.002 — Web Service de Distribuição de DF-e de Interesse dos Atores do CT-e.
  • Schemas distDFeInt_v1.00.xsd e retDistDFeInt_v1.00.xsd.
• Sistema Nacional NFS-e — https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual
  • Manual dos Contribuintes — Guia para utilização das APIs do ADN.
• CONFAZ — Ajuste SINIEF 07/05, que institui a NF-e: https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05