Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

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

ProdutoCaptura Fiscal NFE.io (dfetech-distribution-api) — NF-e Inbound, CT-e Inbound e NFS-e Inbound
Documento1 de 3 — Desenho de arquitetura
Versão1.1 — 24/09/2026
PúblicoClientes, times de arquitetura, TI, segurança da informação e área fiscal
Documentos relacionados2 de 3 — Fluxos de processamento · 3 de 3 — Detalhamento do processamento e regras de periodicidade · English version

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:

SubprodutoDocumentos capturadosOrigem governamentalProtocolo de origem
NF-e InboundNF-e (modelo 55) e seus eventosAmbiente Nacional da NF-e — Web Service NFeDistribuicaoDFeSOAP com TLS mútuo
CT-e InboundCT-e (modelo 57) e seus eventosAmbiente Nacional do CT-e — Web Service CTeDistribuicaoDFeSOAP com TLS mútuo
NFS-e InboundNFS-e do Padrão Nacional, DPS e eventosAmbiente de Dados Nacional (ADN) do Sistema Nacional NFS-eREST 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)​

4. Visão de componentes​

4.1 Responsabilidades de cada componente​

ComponenteResponsabilidade
Gateway HTTPSTermina o TLS e roteia as rotas públicas de Captura Fiscal (/v2/companies/...) para a API.
API REST de Captura FiscalAtiva 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 InboundAgenda 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 InboundAgenda 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 InboundAgenda 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 mensagensTransporta 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 documentosGuarda 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 objetosGuarda 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ídoFornece 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 CertificadosServiç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 usoContabiliza as operações para fins de bilhetagem.
Geração de PDF da NFS-eGera o DANFSe a partir do XML da NFS-e.
ObservabilidadeColeta traces, métricas e logs via OpenTelemetry. Um heartbeat externo alerta a equipe se algum worker parar de responder.

4.2 Pilha tecnológica​

CamadaTecnologia
Linguagem e runtime.NET (C#), ASP.NET Core
ExecuçãoContêineres em Kubernetes, entrega contínua via Helm e GitOps
MensageriaRabbitMQ com o framework Rebus
Banco de dadosMongoDB
Cache e travasCache compatível com Redis
Armazenamento de arquivosArmazenamento de objetos compatível com S3
Integração SEFAZBiblioteca de comunicação com os Web Services da NF-e e do CT-e (SOAP, assinatura XML, TLS mútuo)
Integração NFS-e NacionalCliente HTTP com TLS mútuo e políticas de resiliência (retentativa exponencial e circuit breaker)
ConsultasREST com paginação e OData para NF-e e CT-e
ObservabilidadeOpenTelemetry e monitoramento externo de heartbeat

5. Implantação​

  • 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/....
ProdutoPrincipais recursos
NF-eAtivar, 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-eAtivar, 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-eAtivar 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.

ProdutoTipo do eventoAções
NF-eproduct_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-etransportation_invoice_inboundissued_successfully, outbound_successfully, event_raised_successfully
NFS-eservice_invoice_inboundissued_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​

TemaComo é tratado
Certificado digitalA 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 governoTodas 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 clienteHTTPS no gateway, autenticação por chave de API e autorização por perfil de produto.
Isolamento entre clientesIsolamento lógico: todo registro e toda consulta carregam o identificador da conta e da empresa. Uma conta não enxerga documentos de outra.
DownloadsURLs assinadas e com prazo de validade curto.
Credenciais internasMantidas em cofre de segredos, com comunicação autenticada entre os serviços da plataforma.
AuditoriaCada 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.
LGPDOs 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​

MecanismoDescrição
Filas com novas tentativasToda 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 mensagensCada mensagem tem identificador estável, e o consumidor descarta duplicatas dentro de uma janela de tempo.
Cursor gravado após a persistênciaNo 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 governoQuando 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 pontuaisNa 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 breakerNa 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 NSUTodos 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 externoUm monitor externo recebe sinais periódicos de cada worker e alerta a equipe se algum deixar de enviá-los.

9. Referências governamentais​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.