---
title: "Detalhamento do processamento e regras de periodicidade"
description: "Como a Captura Fiscal processa NF-e, CT-e e NFS-e, com que periodicidade consulta os ambientes nacionais e como obedece às regras das Notas Técnicas (NT 2014.002, NT 2015.002 e APIs do ADN)."
source_url: https://nfe.io/docs/distribuicao-processamento-e-periodicidade/
last_updated: 2026-09-25
---

# 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](./01-arquitetura.md) · [2 de 3 — Fluxos de processamento](./02-fluxos-de-processamento.md) · [English version](./english/03-processing-and-polling-rules.md) |

## Sumário

1. [Resumo executivo](#1-resumo-executivo)
2. [Conceitos](#2-conceitos)
3. [Regras do governo que regem a captura](#3-regras-do-governo-que-regem-a-captura)
4. [NF-e Inbound](#4-nf-e-inbound)
5. [CT-e Inbound](#5-ct-e-inbound)
6. [NFS-e Inbound](#6-nfs-e-inbound)
7. [Quadro comparativo de periodicidade](#7-quadro-comparativo-de-periodicidade)
8. [Tempo esperado até o documento chegar ao cliente](#8-tempo-esperado-até-o-documento-chegar-ao-cliente)
9. [Responsabilidades do cliente](#9-responsabilidades-do-cliente)
10. [Referências governamentais](#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