---
title: "Arquitetura da Captura Fiscal — NF-e, CT-e e NFS-e"
description: "Desenho de arquitetura da Captura Fiscal (DFe Inbound) da NFE.io: componentes, integrações com os ambientes do governo, implantação, segurança e resiliência dos subprodutos NF-e, CT-e e NFS-e Inbound."
source_url: https://nfe.io/docs/distribuicao-arquitetura/
last_updated: 2026-09-25
---

# Arquitetura da Captura Fiscal (DFe Inbound) — NF-e, CT-e e NFS-e

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

## 1. Resumo

A **Captura Fiscal** da NFE.io recebe automaticamente os documentos fiscais eletrônicos emitidos por terceiros contra o CNPJ do cliente. Ela consulta os ambientes nacionais de distribuição mantidos pelo governo, armazena os XMLs, extrai os metadados, disponibiliza os arquivos por API REST e notifica o sistema do cliente por webhook.

O serviço é composto por três subprodutos independentes, que compartilham a mesma plataforma:

| Subproduto | Documentos capturados | Origem governamental | Protocolo de origem |
|---|---|---|---|
| **NF-e Inbound** | NF-e (modelo 55) e seus eventos | Ambiente Nacional da NF-e — Web Service `NFeDistribuicaoDFe` | SOAP com TLS mútuo |
| **CT-e Inbound** | CT-e (modelo 57) e seus eventos | Ambiente Nacional do CT-e — Web Service `CTeDistribuicaoDFe` | SOAP com TLS mútuo |
| **NFS-e Inbound** | NFS-e do Padrão Nacional, DPS e eventos | Ambiente de Dados Nacional (ADN) do Sistema Nacional NFS-e | REST com TLS mútuo |

Cada subproduto é ativado **por empresa (CNPJ)** e opera de forma isolada. Uma falha ou indisponibilidade em um ambiente governamental não interrompe os demais.

## 2. Princípios de arquitetura

1. **Separação por tipo de documento.** Cada subproduto tem o seu próprio processo de captura (*worker*), as suas filas e os seus limites de consumo. Um volume alto de NF-e não disputa recursos com a captura de NFS-e.
2. **Processamento assíncrono orientado a mensagens.** A captura, o processamento de cada documento e a notificação são etapas desacopladas por filas de mensagens. Cada etapa pode ser reprocessada sem refazer as anteriores.
3. **Cursor por NSU.** O avanço da captura é controlado pelo **NSU** (Número Sequencial Único) que o ambiente nacional atribui a cada documento destinado ao CNPJ. O último NSU processado fica persistido por empresa, e a próxima consulta parte dele.
4. **Consumo disciplinado dos serviços do governo.** As regras de periodicidade e de espera da captura rotineira definidas nas Notas Técnicas estão implementadas no próprio motor de captura, junto com pausas e bloqueios automáticos diante de rejeições e paralisações. O detalhamento está no documento 3.
5. **Idempotência.** Cada documento tem um identificador determinístico (empresa + chave de acesso, empresa + identificador do evento ou empresa + NSU). Reprocessar um documento sobrescreve o registro existente em vez de duplicá-lo.
6. **Recuperação automática de lacunas.** Uma rotina diária confere a continuidade da sequência de NSUs e recupera, individualmente, qualquer documento que tenha deixado de ser persistido.
7. **Observabilidade de ponta a ponta.** Todos os componentes emitem rastreamento distribuído, métricas e logs estruturados, e expõem verificações de saúde.

## 3. Visão geral (diagrama de contexto)

```mermaid
flowchart LR
    subgraph GOV["Ambientes do governo"]
        AN_NFE["Ambiente Nacional NF-e<br/>NFeDistribuicaoDFe"]
        AN_EVT["Recepção de Eventos NF-e<br/>NFeRecepcaoEvento4"]
        AN_CTE["Ambiente Nacional CT-e<br/>CTeDistribuicaoDFe"]
        ADN["Sistema Nacional NFS-e<br/>ADN e Sefin Nacional"]
    end

    subgraph NFEIO["Plataforma NFE.io — Captura Fiscal"]
        API["API REST de Captura Fiscal"]
        WNFE["Worker NF-e Inbound"]
        WCTE["Worker CT-e Inbound"]
        WNFSE["Worker NFS-e Inbound"]
        CAD["Serviço de Empresas e<br/>Certificados Digitais"]
        HOOK["Plataforma de Notificações<br/>Webhooks"]
    end

    CLI["Sistema do cliente<br/>ERP, TMS, Contas a Pagar"]
    CON["Console app.nfe.io"]

    WNFE -- "distNSU / consNSU / consChNFe" --> AN_NFE
    WNFE -- "Ciência da Operação e<br/>manifestações" --> AN_EVT
    WCTE -- "distNSU / consNSU" --> AN_CTE
    WNFSE -- "GET DFe por NSU e<br/>manifestação do tomador" --> ADN
    API -- "captura sob demanda<br/>pela chave de acesso" --> ADN

    WNFE & WCTE & WNFSE -- "certificado A1 da empresa" --> CAD
    WNFE & WCTE & WNFSE -- "eventos de documento" --> HOOK
    HOOK -- "POST webhook" --> CLI
    CLI -- "HTTPS + chave de API" --> API
    CON -- "HTTPS" --> API
```

## 4. Visão de componentes

```mermaid
flowchart TB
    subgraph EDGE["Borda"]
        GW["Gateway HTTPS<br/>api.nfse.io"]
    end

    subgraph APP["Camada de aplicação — cluster Kubernetes"]
        API["API REST de Captura Fiscal<br/>escalonamento horizontal automático"]
        subgraph WORKERS["Workers de captura"]
            WNFE["Worker NF-e Inbound"]
            WCTE["Worker CT-e Inbound"]
            WNFSE["Worker NFS-e Inbound"]
        end
    end

    subgraph DATA["Camada de dados"]
        MQ[("Broker de mensagens<br/>RabbitMQ — filas por produto<br/>e filas de erro")]
        DB[("Banco de documentos<br/>MongoDB — metadados, cursores,<br/>configurações e auditoria")]
        OBJ[("Armazenamento de objetos<br/>compatível com S3 — XML e PDF")]
        CACHE[("Cache distribuído<br/>compatível com Redis — travas,<br/>controle de concorrência e<br/>limite de consultas pontuais")]
    end

    subgraph PLAT["Serviços internos da plataforma NFE.io"]
        CAD["Empresas e Certificados"]
        HOOK["Notificações — Webhooks"]
        USO["Registro de uso"]
        PDF["Geração de PDF da NFS-e"]
        IDP["Identidade e chaves de API"]
    end

    subgraph OBS["Observabilidade"]
        OTEL["OpenTelemetry<br/>traces, métricas e logs"]
        HB["Monitor externo de<br/>heartbeat e disponibilidade"]
    end

    GW --> API
    API --> MQ
    API --> DB
    API --> OBJ
    API --> CACHE
    MQ --> WNFE & WCTE & WNFSE
    WNFE & WCTE & WNFSE --> DB
    WNFE & WCTE & WNFSE --> OBJ
    WNFE & WCTE & WNFSE --> CACHE
    WNFE & WCTE & WNFSE --> CAD
    WNFE & WCTE & WNFSE --> HOOK
    WNFE & WCTE & WNFSE --> USO
    WNFSE --> PDF
    API --> IDP
    API & WNFE & WCTE & WNFSE -.-> OTEL
    WNFE & WCTE & WNFSE -.-> HB
```

### 4.1 Responsabilidades de cada componente

| Componente | Responsabilidade |
|---|---|
| **Gateway HTTPS** | Termina o TLS e roteia as rotas públicas de Captura Fiscal (`/v2/companies/...`) para a API. |
| **API REST de Captura Fiscal** | Ativa e desativa a captura por empresa, consulta documentos e eventos, entrega XML, PDF e JSON, recebe pedidos de manifestação e de reprocessamento. Autentica por chave de API e autoriza por perfil de produto. Executa a captura de NFS-e sob demanda pela chave de acesso. Escala horizontalmente conforme o uso de CPU. |
| **Worker NF-e Inbound** | Agenda e executa a consulta ao `NFeDistribuicaoDFe`, processa cada NSU (resumo, NF-e completa, eventos), agenda a Ciência da Operação automática para depois do tempo de espera configurado pela empresa (a única manifestação enviada automaticamente), envia as manifestações ao ambiente de eventos (`NFeRecepcaoEvento4` do Ambiente Nacional; eventos da Reforma Tributária pelo ambiente de eventos correspondente) e roda a conciliação diária de NSU. |
| **Worker CT-e Inbound** | Agenda e executa a consulta ao `CTeDistribuicaoDFe`, processa cada NSU (CT-e e eventos), aplica os filtros de evento e de parte interessada, oferece reprocessamento e consolidação de lotes e roda a conciliação diária de NSU. |
| **Worker NFS-e Inbound** | Agenda e executa a consulta ao ADN, decodifica e classifica cada documento (NFS-e, DPS, eventos), gera o DANFSe, aplica a data de corte e a liberação de histórico, envia manifestações do tomador à Sefin Nacional e roda a conciliação diária de NSU. |
| **Broker de mensagens** | Transporta as mensagens entre as etapas. Há filas dedicadas por produto e por etapa, filas de erro (*dead-letter*) e agendamento de novas tentativas com atraso. |
| **Banco de documentos** | Guarda a configuração de cada empresa, os cursores de NSU, os metadados de documentos e eventos, os controles de reprocessamento e a trilha de auditoria de notificações. |
| **Armazenamento de objetos** | Guarda os XMLs originais recebidos do governo, os lotes de resposta, os PDFs gerados e os registros de requisição e resposta das consultas. |
| **Cache distribuído** | Fornece travas distribuídas (uma captura por empresa por vez, uma instância por rotina diária), limites de concorrência por empresa, o controle do limite de consultas pontuais da NF-e e do CT-e (20 com documento por hora por CNPJ) e parâmetros operacionais ajustáveis em tempo de execução. Se o cache ficar indisponível, as consultas pontuais seguem sem o controle, e um cStat 656 continua bloqueando a empresa pelo registro no banco. |
| **Empresas e Certificados** | Serviço da plataforma NFE.io que mantém o cadastro das empresas e custodia os certificados digitais A1. A Captura Fiscal obtém o certificado a cada consulta, em memória. |
| **Notificações (Webhooks)** | Serviço da plataforma NFE.io que entrega os eventos ao endpoint configurado pelo cliente. |
| **Registro de uso** | Contabiliza as operações para fins de bilhetagem. |
| **Geração de PDF da NFS-e** | Gera o DANFSe a partir do XML da NFS-e. |
| **Observabilidade** | Coleta traces, métricas e logs via OpenTelemetry. Um heartbeat externo alerta a equipe se algum worker parar de responder. |

### 4.2 Pilha tecnológica

| Camada | Tecnologia |
|---|---|
| Linguagem e runtime | .NET (C#), ASP.NET Core |
| Execução | Contêineres em Kubernetes, entrega contínua via Helm e GitOps |
| Mensageria | RabbitMQ com o framework Rebus |
| Banco de dados | MongoDB |
| Cache e travas | Cache compatível com Redis |
| Armazenamento de arquivos | Armazenamento de objetos compatível com S3 |
| Integração SEFAZ | Biblioteca de comunicação com os Web Services da NF-e e do CT-e (SOAP, assinatura XML, TLS mútuo) |
| Integração NFS-e Nacional | Cliente HTTP com TLS mútuo e políticas de resiliência (retentativa exponencial e *circuit breaker*) |
| Consultas | REST com paginação e OData para NF-e e CT-e |
| Observabilidade | OpenTelemetry e monitoramento externo de heartbeat |

## 5. Implantação

```mermaid
flowchart LR
    subgraph K8S["Cluster Kubernetes — namespace da Captura Fiscal"]
        direction TB
        APIP["API — múltiplas réplicas<br/>autoescalonamento por CPU"]
        NFEP["Worker NF-e"]
        CTEP["Worker CT-e"]
        NFSEP["Worker NFS-e"]
    end
    GW["Gateway HTTPS"] --> APIP
    SEC["Cofre de segredos"] -. "credenciais injetadas<br/>em tempo de execução" .-> K8S
```

- Os quatro componentes (API e três workers) são implantados como aplicações independentes, cada uma com a sua própria imagem de contêiner e o seu próprio ciclo de versão.
- A API opera com múltiplas réplicas e autoescalonamento horizontal. Os workers escalam o paralelismo internamente, por fila.
- Todas as aplicações expõem verificações de prontidão (*readiness*), que conferem banco, cache, broker, armazenamento e serviços dependentes, e de vivacidade (*liveness*). O Kubernetes retira do balanceamento uma instância que não esteja pronta e reinicia automaticamente uma instância que deixe de responder.
- O desligamento é gracioso: a instância para de receber mensagens e conclui as que estão em andamento antes de encerrar.
- As credenciais (strings de conexão, chaves e certificados de serviço) ficam em cofre de segredos e são injetadas em tempo de execução. Nenhuma credencial fica no código-fonte.
- As rotinas agendadas (conciliação diária de NSU) rodam dentro dos workers, com eleição de líder por trava distribuída. Apenas uma instância executa cada ciclo.

## 6. Integração com o cliente

### 6.1 API REST

- **Endereço de produção:** `https://api.nfse.io`
- **Autenticação:** chave de API da conta NFE.io, com autorização por perfil de produto (NF-e, CT-e e NFS-e) ou pela chave geral de Nota Fiscal.
- **Modelo de dados:** conta → empresa (CNPJ) → configuração de captura por produto. As rotas de documentos são escopadas pela empresa: `/v2/companies/{companyId}/inbound/...`.

| Produto | Principais recursos |
|---|---|
| NF-e | Ativar, consultar e desativar a captura (`.../inbound/productinvoices`); listar e detalhar NF-e (`.../inbound/nfe`); baixar XML e PDF (DANFE); consultar eventos; registrar manifestações; consultas OData (`.../inbound/odata/ProductInvoices` e `ProductInvoiceEvents`); reenviar webhook. |
| CT-e | Ativar, consultar e desativar a captura (`.../inbound/transportationinvoices`); baixar XML, JSON e PDF (DACTE); configurar filtro de parte interessada do webhook; reprocessar itens, lotes e webhooks; consultas OData (`.../inbound/odata/TransportationInvoices` e `TransportationInvoiceEvents`). |
| NFS-e | Ativar a captura (`POST /v2/companies/inbound/nfse`) e consultar, alterar ou desativar a configuração (`.../inbound/nfse/details`); listar e detalhar documentos (`.../inbound/nfse`); baixar XML, PDF (DANFSe) e JSON; capturar sob demanda pela chave de acesso; registrar manifestação do tomador; reprocessar e reenviar webhook. |

Os downloads de XML e PDF são entregues por URL assinada temporária (em geral, por redirecionamento HTTP) ou diretamente no corpo da resposta, como no PDF do CT-e. As URLs assinadas expiram em até 1 hora e não devem ser armazenadas; basta solicitar uma nova ao endpoint quando necessário.

### 6.2 Webhooks

Cada documento ou evento capturado gera uma notificação para o endpoint cadastrado pelo cliente na plataforma de notificações da NFE.io.

| Produto | Tipo do evento | Ações |
|---|---|---|
| NF-e | `product_invoice_inbound` (documento completo e eventos) e `product_invoice_inbound_summary` (resumos) | `issued_successfully` (documento recebido), `outbound_successfully` (documento emitido pela própria empresa), `event_raised_successfully` (evento), `input_event_raised_successfully` (manifestação do destinatário) |
| CT-e | `transportation_invoice_inbound` | `issued_successfully`, `outbound_successfully`, `event_raised_successfully` |
| NFS-e | `service_invoice_inbound` | `issued_successfully` (NFS-e recebida), `outbound_successfully` (NFS-e emitida pela própria empresa, quando essa captura estiver ligada), `event_raised_successfully` (eventos e manifestação registrada). O corpo traz também o campo `eventName` no formato `inbound.serviceInvoice.*` |

A entrega é do tipo **pelo menos uma vez** (*at-least-once*). O sistema do cliente deve tratar notificações repetidas de forma idempotente, usando a chave de acesso, o identificador do evento ou o NSU. A validação da assinatura do webhook segue a documentação oficial de webhooks da NFE.io.

### 6.3 Console

O console `app.nfe.io` usa a mesma API para ativar a captura, consultar documentos, baixar arquivos e registrar manifestações. Não há diferença de dados entre console e API.

## 7. Segurança e privacidade

| Tema | Como é tratado |
|---|---|
| **Certificado digital** | A captura usa o certificado **A1 (ICP-Brasil)** da própria empresa, custodiado pelo serviço de certificados da NFE.io. O certificado é obtido a cada consulta e carregado apenas em memória. Certificados com chave privada custodiada em HSM **ainda não são suportados** pela Captura Fiscal, que usa o certificado A1 (arquivo) para o TLS mútuo exigido pelos ambientes de distribuição. |
| **Canal com o governo** | Todas as chamadas aos ambientes nacionais usam HTTPS com autenticação mútua (TLS 1.2 ou superior). Na NFS-e, cada requisição abre uma conexão própria, o que isola o certificado de uma empresa das demais. |
| **Canal com o cliente** | HTTPS no gateway, autenticação por chave de API e autorização por perfil de produto. |
| **Isolamento entre clientes** | Isolamento lógico: todo registro e toda consulta carregam o identificador da conta e da empresa. Uma conta não enxerga documentos de outra. |
| **Downloads** | URLs assinadas e com prazo de validade curto. |
| **Credenciais internas** | Mantidas em cofre de segredos, com comunicação autenticada entre os serviços da plataforma. |
| **Auditoria** | Cada notificação enviada é registrada (horário de aceite e alcance), com retenção de 365 dias. No CT-e, a requisição e a resposta de cada consulta ao governo ficam arquivadas; na NF-e, as consultas que retornam documentos ou rejeições. |
| **LGPD** | Os documentos capturados contêm dados de terceiros (emitentes, transportadores, prestadores). A NFE.io atua como operadora desses dados em nome do cliente, que é o destinatário legítimo dos documentos segundo as regras de distribuição do governo. |

## 8. Resiliência

| Mecanismo | Descrição |
|---|---|
| Filas com novas tentativas | Toda etapa que falha é reentregue automaticamente. Mensagens que esgotam as tentativas vão para filas de erro e podem ser reenviadas pela equipe de operação. |
| Deduplicação de mensagens | Cada mensagem tem identificador estável, e o consumidor descarta duplicatas dentro de uma janela de tempo. |
| Cursor gravado após a persistência | No CT-e, o cursor de NSU só avança depois que o lote foi persistido. No NF-e e na NFS-e, falhas de persistência ficam registradas para reprocessamento e são cobertas pela conciliação diária. |
| Pausas por indisponibilidade do governo | Quando o ambiente nacional informa paralisação do serviço, a captura é pausada por um período definido e retomada sozinha (detalhes no documento 3). |
| Limite de consultas pontuais | Na NF-e e no CT-e, as consultas por NSU ou por chave de acesso respeitam o limite de 20 consultas com documento por hora por CNPJ. Quem não tem vaga é adiado sem consumir tentativa, com espaçamento aleatório para não concentrar as retomadas. |
| *Circuit breaker* | Na NFS-e há disjuntores global e por certificado. Na NF-e, uma consulta que falha repetidamente é interrompida após o limite de tentativas, para não consumir o serviço do governo indefinidamente. |
| Conciliação diária de NSU | Todos os dias, às 23h (horário de Brasília), cada produto confere a sequência de NSUs dos últimos 3 dias e recupera os que faltarem. |
| Heartbeat externo | Um monitor externo recebe sinais periódicos de cada worker e alerta a equipe se algum deixar de enviá-los. |

## 9. Referências governamentais

- Portal Nacional da NF-e — Nota Técnica 2014.002 (Web Service de Distribuição de DF-e de Interesse dos Atores da NF-e) e schemas `distDFeInt` e `retDistDFeInt`: https://www.nfe.fazenda.gov.br/portal
- Portal Nacional da NF-e — Nota Técnica 2020.001 (Manifestação do Destinatário) e Nota Técnica 2025.002 (eventos da Reforma Tributária do Consumo).
- Portal Nacional do CT-e — Nota Técnica 2015.002 (Web Service de Distribuição de DF-e de Interesse dos Atores do CT-e): https://www.cte.fazenda.gov.br/portal
- Sistema Nacional NFS-e — Manual dos Contribuintes: Guia para utilização das APIs do ADN: https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/documentacao-atual
- CONFAZ — Ajuste SINIEF 07/05 (NF-e): https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05