---
title: "Fluxos de processamento — NF-e, CT-e e NFS-e Inbound"
description: "Diagramas dos fluxos de processamento da Captura Fiscal: agendamento, consulta ao ambiente nacional, processamento por NSU, manifestação e recuperação de lacunas para NF-e, CT-e e NFS-e."
source_url: https://nfe.io/docs/distribuicao-fluxos-de-processamento/
last_updated: 2026-09-25
---

# Fluxos de Processamento da Captura Fiscal — NF-e, CT-e e NFS-e Inbound

| | |
|---|---|
| **Produto** | Captura Fiscal NFE.io (`dfetech-distribution-api`) |
| **Documento** | 2 de 3 — Desenho dos fluxos de processamento |
| **Versão** | 1.1 — 24/09/2026 |
| **Público** | Clientes, times de arquitetura, TI e área fiscal |
| **Documentos relacionados** | [1 de 3 — Arquitetura](./01-arquitetura.md) · [3 de 3 — Detalhamento do processamento e regras de periodicidade](./03-processamento-e-periodicidade.md) · [English version](./english/02-processing-flows.md) |

## 1. Como ler este documento

Este documento traz os diagramas dos fluxos de processamento de cada subproduto. Cada fluxo está dividido em quatro partes:

1. **Agendamento:** como e quando a NFE.io decide consultar o ambiente nacional para uma empresa.
2. **Captura:** a consulta ao governo e o tratamento de cada resposta possível.
3. **Processamento por documento:** o que acontece com cada NSU recebido.
4. **Fluxos complementares:** manifestação, recuperação de lacunas e capturas sob demanda.

As regras de tempo mostradas nos diagramas (intervalos, esperas e bloqueios) estão explicadas e justificadas no documento 3, com referência às Notas Técnicas do governo.

### 1.1 Fluxo comum aos três produtos

```mermaid
flowchart LR
    A["Terceiro emite o documento<br/>contra o CNPJ do cliente"] --> B["Governo autoriza e publica<br/>no ambiente nacional<br/>com um NSU"]
    B --> C["Agendador NFE.io<br/>seleciona a empresa"]
    C --> D["Consulta de distribuição<br/>a partir do último NSU"]
    D --> E["Lote de documentos"]
    E --> F["Processamento por NSU:<br/>descompacta, classifica,<br/>armazena XML e metadados"]
    F --> G["Webhook ao cliente"]
    F --> H["Disponível na API<br/>e no console"]
    D -. "sem documentos novos" .-> I["Espera regulamentar<br/>de 1 hora"]
    I -.-> C
```

---

## 2. NF-e Inbound

### 2.1 Agendamento e captura

```mermaid
flowchart TD
    S["Agendador — a cada 3 minutos"] --> L["Lista as empresas com<br/>captura de NF-e ativa"]
    L --> E{"Empresa elegível?<br/>• pendente de continuação, ou<br/>• última consulta há mais de 61 min"}
    E -- não --> FIM1["Aguarda o próximo ciclo"]
    E -- sim --> M["Envia mensagem de captura<br/>com o NSU do cursor"]
    M --> P{"SEFAZ em pausa ou<br/>empresa bloqueada por rejeição?"}
    P -- sim --> FIM2["Não consulta.<br/>Aguarda o fim da pausa"]
    P -- não --> R{"Cursor já alcançou o maxNSU<br/>e a última consulta<br/>tem menos de 62 min?"}
    R -- sim --> FIM3["Não consulta.<br/>Respeita a espera de 1 hora"]
    R -- não --> C["Obtém o certificado A1 da empresa"]
    C --> Q["distNSU com ultNSU = cursor<br/>NFeDistribuicaoDFe — Ambiente Nacional"]
    Q --> ARQ["Interpreta a resposta"]
    ARQ --> K{"cStat"}
    K -- "138 — documentos localizados" --> B1["Arquiva a resposta, grava o lote<br/>e cria um item por NSU"]
    B1 --> B2["Envia uma mensagem de<br/>processamento por NSU"]
    B2 --> B3["Atualiza o cursor:<br/>ultNSU e maxNSU"]
    B3 --> B4{"ultNSU menor que maxNSU?"}
    B4 -- sim --> M
    B4 -- não --> FIM4["Fila zerada.<br/>Próxima consulta após 1 hora"]
    K -- "137 — nenhum documento" --> N1["Registra o horário da consulta"] --> FIM4
    K -- "108 ou 109 — serviço paralisado" --> G1["Pausa global da consulta:<br/>5 min — 108<br/>20 min — 109"]
    K -- "656 — consumo indevido" --> G4["Bloqueia a empresa por 1 hora,<br/>suspende as consultas pontuais do CNPJ<br/>e ajusta o cursor ao ultNSU, só para a frente"]
    K -- "outra rejeição" --> G2["Bloqueia a empresa por 1 hora<br/>e registra o erro"]
    K -- "falha de comunicação" --> G3["Nova tentativa automática.<br/>Após o limite de tentativas,<br/>a consulta é interrompida<br/>para análise da operação"]
```

### 2.2 Processamento de cada NSU

```mermaid
flowchart TD
    A["Mensagem de processamento do NSU"] --> B["Lê o lote arquivado e localiza<br/>o docZip do NSU"]
    B --> C["Decodifica Base64 e descompacta GZip"]
    C --> D{"schema do documento"}
    D -- "resNFe" --> R1["Resumo da NF-e"]
    D -- "procNFe" --> R2["NF-e completa autorizada"]
    D -- "resEvento" --> R3["Resumo de evento"]
    D -- "procEventoNFe" --> R4["Evento completo"]
    R1 & R2 & R3 & R4 --> E["Extrai metadados:<br/>chave, emitente, destinatário,<br/>transportador, valores, datas"]
    E --> F["Determina a direção:<br/>recebido ou emitido pela empresa"]
    F --> G["Grava o XML no armazenamento<br/>e os metadados no banco"]
    G --> H["Vincula eventos à NF-e da mesma chave"]
    H --> I["Envia o webhook"]
    I --> J["Registra o uso"]
    J --> K{"Resumo resNFe com<br/>Ciência automática ativa?"}
    K -- sim --> MAN["Fluxo de manifestação — seção 2.3"]
    K -- não --> FIM["Concluído"]
```

### 2.3 Manifestação do destinatário e liberação do XML completo

```mermaid
sequenceDiagram
    autonumber
    participant AN as Ambiente Nacional NF-e
    participant W as Worker NF-e
    participant EV as NFeRecepcaoEvento4
    participant API as API NFE.io
    participant CLI as Sistema do cliente

    W->>AN: distNSU
    AN-->>W: resNFe — resumo da NF-e, NSU n
    W->>CLI: webhook product_invoice_inbound_summary
    alt Ciência automática ativa
        W->>W: Agenda o evento 210210 — Ciência da Operação, sem duplicidade por chave
        Note over W: Aguarda o tempo de espera configurado pela empresa
        W->>W: Confere de novo: Ciência automática ligada e nenhuma manifestação conclusiva aceita
        W->>EV: envEvento assinado com o certificado A1
        EV-->>W: cStat 135 ou 136 — evento registrado
    else Manifestação pelo cliente
        CLI->>API: POST manifestação — 210200, 210210, 210220 ou 210240
        API-->>CLI: 202 — pendente
        API->>W: mensagem de envio
        W->>EV: envEvento assinado
        EV-->>W: resultado do registro
    end
    Note over AN,W: Após Ciência, Confirmação ou Operação não Realizada, o Ambiente Nacional libera o XML completo ao destinatário
    Note over W,CLI: A Ciência é a única manifestação automática. Confirmação, Desconhecimento e Operação não Realizada são sempre enviadas a pedido do cliente
    W->>AN: distNSU — ciclo normal
    AN-->>W: procNFe — NF-e completa, novo NSU m
    W->>CLI: webhook product_invoice_inbound — issued_successfully
    AN-->>W: procEventoNFe — evento de manifestação
    W->>CLI: webhook input_event_raised_successfully
```

### 2.4 Recuperação de lacunas de NSU

```mermaid
flowchart LR
    A["Rotina diária — 23h, horário de Brasília<br/>uma única instância, por trava distribuída"] --> B["Para cada empresa ativa:<br/>NSUs capturados nos últimos 3 dias"]
    B --> C["Confere a sequência no intervalo<br/>mínimo–máximo"]
    C --> D["NSU ausente vira pendência<br/>de recuperação"]
    D --> E["Despachante — a cada 5 min"]
    E --> F["consNSU do NSU ausente<br/>dentro do limite de consultas pontuais — seção 2.5"]
    F -- sucesso --> G["Processa como na seção 2.2<br/>e encerra a pendência"]
    F -- falha --> H["Nova tentativa com espera exponencial<br/>1 min até 30 min, com variação aleatória,<br/>até 8 tentativas"]
    H -- esgotou --> I["Pendência volta a ser avaliada<br/>na próxima rotina diária"]
```

### 2.5 Consultas pontuais e limite de consumo (NF-e e CT-e)

Vale para `consNSU` e `consChNFe` na NF-e e para `consNSU` no CT-e, tanto na recuperação de lacunas quanto no reprocessamento pedido pelo cliente.

```mermaid
flowchart TD
    A["Pedido de consulta pontual<br/>recuperação de lacuna ou reprocessamento"] --> L{"NF-e: documento já existe<br/>na base da NFE.io?"}
    L -- sim --> LOC["Reenvia a partir da base.<br/>Não consulta a SEFAZ nem consome cota"]
    L -- "não, ou CT-e" --> V{"Vaga no limite do CNPJ?<br/>20 consultas com documento por hora"}
    V -- "não, ou CNPJ bloqueado por 656" --> AD{"Origem do pedido"}
    AD -- "fila interna" --> DEF["Adia até a próxima vaga,<br/>com espaçamento aleatório de até 30 min.<br/>Não conta como tentativa"]
    AD -- "API" --> R429["Responde HTTP 429<br/>com Retry-After"]
    V -- sim --> C["Obtém o certificado e<br/>consulta a SEFAZ"]
    C --> K{"Resposta"}
    K -- "documento retornado" --> OK["Processa o documento.<br/>A consulta fica na cota"]
    K -- "656 — consumo indevido" --> B["Bloqueia as consultas pontuais do CNPJ<br/>por 1 hora. Na NF-e, também a distribuição.<br/>A vaga é devolvida"]
    K -- "sem documento, outra rejeição<br/>ou falha" --> DV["Devolve a vaga:<br/>só as consultas com documento contam"]
```

---

## 3. CT-e Inbound

### 3.1 Agendamento e captura

```mermaid
flowchart TD
    S["Agendador — a cada 60 segundos"] --> L["Lista as empresas com<br/>captura de CT-e ativa"]
    L --> E{"Empresa elegível?<br/>• pendente de continuação, ou<br/>• última consulta há mais de 60 min"}
    E -- não --> FIM1["Aguarda o próximo ciclo"]
    E -- sim --> M["Envia mensagem de captura<br/>com o NSU do cursor"]
    M --> P{"SEFAZ em pausa ou<br/>empresa bloqueada por rejeição?"}
    P -- sim --> FIM2["Não consulta.<br/>Aguarda o fim da pausa"]
    P -- não --> R{"Última resposta indicou fim da fila<br/>e foi há menos de 1 hora?"}
    R -- sim --> FIM3["Não consulta.<br/>Respeita a espera de 1 hora"]
    R -- não --> C["Obtém o certificado A1 da empresa"]
    C --> Q["distNSU com ultNSU = cursor<br/>CTeDistribuicaoDFe — Ambiente Nacional"]
    Q --> ARQ["Arquiva requisição e resposta"]
    ARQ --> K{"cStat"}
    K -- "138 — documentos localizados" --> B1["Grava o lote e um item por NSU,<br/>com paralelismo controlado"]
    B1 --> B2{"Lote persistido?"}
    B2 -- sim --> B3["Avança o cursor:<br/>ultNSU e maxNSU"]
    B2 -- "não" --> B5["Cursor não avança.<br/>NSUs com falha viram pendência<br/>de recuperação"]
    B3 --> B4{"ultNSU menor que maxNSU?"}
    B4 -- sim --> M
    B4 -- não --> FIM4["Fila zerada.<br/>Retoma no próximo ciclo elegível"]
    K -- "137 — nenhum documento" --> N1["Avança o cursor e registra<br/>o horário"] --> FIM5["Próxima consulta após 1 hora"]
    K -- "108 ou 109 — serviço paralisado" --> G1["Pausa global da consulta:<br/>5 min — 108<br/>20 min — 109"]
    K -- "outra rejeição, inclusive 656" --> G2["Bloqueia a empresa por 1 hora<br/>e registra o erro"]
```

### 3.2 Processamento de cada NSU

```mermaid
flowchart TD
    A["Mensagem de processamento do NSU"] --> B["Lê o lote arquivado e localiza<br/>o docZip do NSU"]
    B --> C["Decodifica Base64 e descompacta GZip"]
    C --> D{"schema do documento"}
    D -- "procCTe" --> R1["CT-e completo autorizado"]
    D -- "procEventoCTe" --> R2["Evento do CT-e"]
    R1 --> E1["Extrai metadados: chave, emitente,<br/>remetente, expedidor, recebedor,<br/>destinatário, tomador, valor da prestação,<br/>NF-e referenciadas"]
    R2 --> E2["Extrai metadados do evento:<br/>tipo, sequência, data de registro"]
    E2 --> F2{"Tipo de evento está na<br/>lista configurada pela empresa?"}
    F2 -- não --> IG["Guarda como evento ignorado.<br/>Sem webhook"]
    F2 -- sim --> G
    E1 --> DIR["Determina a direção:<br/>emitido somente se a empresa for<br/>apenas a emitente"]
    DIR --> G["Grava o XML e os metadados"]
    G --> PI{"Filtro de parte interessada<br/>configurado?"}
    PI -- "não" --> WH["Envia o webhook"]
    PI -- "sim e a empresa ocupa o papel" --> WH
    PI -- "sim e a empresa não ocupa o papel" --> SUP["Documento fica disponível na API,<br/>sem webhook"]
    WH --> U["Registra o uso"]
```

### 3.3 Recuperação de lacunas e reprocessamento

```mermaid
flowchart LR
    A["Rotina diária — 23h<br/>horário de Brasília"] --> B["NSUs dos últimos 3 dias<br/>e varredura até o cursor atual"]
    B --> C["NSU ausente vira pendência"]
    C --> D["Despachante — a cada 5 min"]
    D --> E["consNSU do NSU ausente<br/>dentro do limite de consultas pontuais — seção 2.5"]
    E -- "sucesso" --> F["Processa como na seção 3.2"]
    E -- "137 — NSU inexistente" --> T["Encerra a pendência"]
    E -- "outras respostas" --> H["Nova tentativa com espera exponencial<br/>1 min até 30 min, com variação aleatória,<br/>até 8 tentativas"]
    R["Pedido de reprocessamento<br/>pela API — item, lote ou webhook"] --> D
```

O CT-e não possui consulta por chave de acesso no Web Service de distribuição. Toda recuperação é feita por NSU.

---

## 4. NFS-e Inbound

### 4.1 Agendamento e captura

```mermaid
flowchart TD
    S["Agendador — a cada 30 segundos"] --> L["Seleciona empresas ativas<br/>fora de período de espera"]
    L --> M["Envia mensagem de captura por empresa"]
    M --> LK{"Trava da empresa livre?<br/>uma captura por empresa por vez"}
    LK -- não --> FIM1["Descarta: já há captura em andamento"]
    LK -- sim --> CERT{"Certificado A1 válido?"}
    CERT -- "ausente, vencido ou em HSM" --> CD1["Espera de 1 hora.<br/>Empresa continua ativa e<br/>retoma sozinha"]
    CERT -- sim --> Q["GET /DFe/NSU — ADN<br/>lote de distribuição a partir do cursor"]
    Q --> K{"Resposta do ADN"}
    K -- "DOCUMENTOS_LOCALIZADOS" --> B1["Envia uma mensagem de<br/>processamento por documento"]
    B1 --> B2["Grava o cursor — maior NSU recebido"]
    B2 --> B3{"Limite de 50 lotes<br/>nesta execução?"}
    B3 -- não --> Q
    B3 -- sim --> FIM2["Continua no próximo ciclo"]
    K -- "NENHUM_DOCUMENTO_LOCALIZADO" --> CD2["Grava o cursor.<br/>Espera de 1 hora"]
    K -- "HTTP 429 — limite de consumo" --> CD3["Espera o tempo indicado pelo ADN<br/>ou 1 hora"]
    K -- "REJEICAO" --> RJ["Registra os códigos de erro.<br/>Nada capturado nesta execução: espera de 10 min.<br/>Com documentos já capturados: retoma no ciclo seguinte"]
    K -- "certificado rejeitado" --> CB["Conta falha consecutiva.<br/>Com 10 falhas, a captura da<br/>empresa é desativada"]
    K -- "falha transitória 5xx ou timeout" --> PO["Até 3 novas tentativas — 1 s, 2 s, 4 s.<br/>Disjuntor por certificado e global.<br/>Persistindo, reagendamento com espera<br/>exponencial de 1 min até 1 h"]
```

### 4.2 Processamento de cada documento

```mermaid
flowchart TD
    A["Mensagem de processamento"] --> ID{"NSU já processado<br/>para a empresa?"}
    ID -- sim --> FIM1["Ignora — idempotência"]
    ID -- não --> B["Decodifica Base64, GZip e UTF-8"]
    B --> C{"Elemento raiz do XML"}
    C -- "NFSe" --> T1["NFS-e autorizada"]
    C -- "DPS" --> T2["Declaração de Prestação de Serviço"]
    C -- "evento ou pedido de evento" --> T3["Evento — cancelamento, substituição,<br/>manifestações, atos de ofício"]
    C -- "CNC" --> T4["Cadastro Nacional de Contribuintes"]
    T1 & T2 & T3 & T4 --> D["Grava o XML compactado<br/>no armazenamento"]
    D --> P{"É NFS-e?"}
    P -- sim --> PDF["Gera o DANFSe.<br/>Se indisponível, fica pendente e é<br/>gerado sob demanda no download"]
    P -- não --> MD
    PDF --> MD["Extrai metadados: prestador, tomador,<br/>intermediário, serviço, valores e tributos,<br/>inclusive IBS e CBS"]
    MD --> DIR["Determina a direção:<br/>recebida ou emitida"]
    DIR --> CUT{"Documento anterior à<br/>data de corte da empresa?"}
    CUT -- "sim, histórico não liberado" --> SK["Guarda sem webhook.<br/>Entregue só se o histórico for liberado"]
    CUT -- não --> OUT{"NFS-e emitida pela própria empresa?"}
    OUT -- "sim e captura de emitidas desligada" --> SK2["Guarda sem webhook"]
    OUT -- "não, ou captura de emitidas ligada" --> WH["Envia o webhook"]
    WH --> U["Registra o uso"]
```

### 4.3 Manifestação do tomador e captura sob demanda

```mermaid
sequenceDiagram
    autonumber
    participant CLI as Sistema do cliente
    participant API as API NFE.io
    participant W as Worker NFS-e
    participant SEFIN as Sefin Nacional / ADN

    rect rgba(127,127,127,0.08)
    Note over CLI,SEFIN: Manifestação do tomador — sempre a pedido do cliente, nunca automática
    CLI->>API: POST manifestação — 203202 Confirmação ou 203206 Rejeição
    API-->>CLI: 202 — pendente
    API->>W: mensagem de envio
    W->>W: Confere certificado e CNPJ do tomador
    W->>SEFIN: POST pedido de registro de evento, assinado
    SEFIN-->>W: evento registrado ou rejeitado
    alt evento registrado
        W->>CLI: webhook event_raised_successfully
    else evento rejeitado
        W->>W: registra a rejeição, consultável na API
    end
    end

    rect rgba(127,127,127,0.08)
    Note over CLI,SEFIN: Captura sob demanda pela chave de acesso
    CLI->>API: POST captura por chave — 50 dígitos
    API->>SEFIN: GET NFS-e pela chave
    SEFIN-->>API: XML da NFS-e
    API->>API: Armazena, gera PDF e grava metadados
    API-->>CLI: 200 — documento capturado, sem webhook neste momento
    Note over CLI,SEFIN: O webhook é enviado quando o documento chegar pela distribuição normal
    end
```

### 4.4 Recuperação de lacunas

```mermaid
flowchart LR
    A["Rotina diária — 23h<br/>horário de Brasília"] --> B["NSUs capturados nos últimos 3 dias"]
    B --> C["Confere a sequência no intervalo"]
    C --> D{"Há lacuna?"}
    D -- sim --> E["Reinicia a captura da empresa<br/>a partir do NSU anterior à primeira lacuna"]
    E --> F["Documentos já existentes são ignorados<br/>pela idempotência; os ausentes são gravados"]
    D -- não --> G["Nada a fazer"]
```

---

## 5. Ciclo de vida da cadência de consulta (os três produtos)

```mermaid
stateDiagram-v2
    [*] --> Ativa: captura ativada
    Ativa --> Consultando: agendador seleciona a empresa
    Consultando --> Consultando: há documentos pendentes no ambiente nacional
    Consultando --> EmEspera: fim da fila — nenhum documento novo
    EmEspera --> Consultando: após 1 hora
    Consultando --> Bloqueada: rejeição do ambiente nacional
    Bloqueada --> Consultando: fim do bloqueio
    Consultando --> PausaGlobal: ambiente nacional paralisado ou com erro
    PausaGlobal --> Consultando: fim da pausa
    Ativa --> [*]: captura desativada
```

| Estado | NF-e | CT-e | NFS-e |
|---|---|---|---|
| **Consultando** | Consultas encadeadas enquanto `ultNSU` for menor que `maxNSU` | Consultas encadeadas enquanto `ultNSU` for menor que `maxNSU` | Até 50 lotes seguidos por execução, retomando a cada 30 s |
| **Em espera** | Mínimo de 1 hora após alcançar o `maxNSU` ou receber cStat 137 (até cerca de 65 min) | Mínimo de 1 hora após o ambiente indicar fim da fila (cStat 137) | 1 hora após `NENHUM_DOCUMENTO_LOCALIZADO` |
| **Bloqueada** | 1 hora por empresa após rejeição, inclusive 656; o 656 também suspende as consultas pontuais do CNPJ | 1 hora por empresa após rejeição, inclusive 656; o 656 em consulta pontual suspende as consultas pontuais do CNPJ | Tempo informado pelo ADN no HTTP 429, ou 1 hora; 10 min após `REJEICAO` sem documentos capturados; 1 hora por certificado indisponível |
| **Pausa global** | 5 min (cStat 108) e 20 min (cStat 109) | 5 min (cStat 108) e 20 min (cStat 109) | Disjuntor global e por certificado, 60 s |