Arquitetura da Emissão de NF-e, NFC-e e do Cálculo de Impostos

Produto	Emissão de Nota Fiscal de Produto NFE.io (dfetech-product-invoice-api): NF-e, NFC-e, Cálculo de Impostos (Taxes) e Guias de Recolhimento (Taxes Payment Forms)
Documento	1 de 4: Desenho de arquitetura
Versão	1.0 (24/09/2026)
Público	Clientes, times de arquitetura, TI, segurança da informação e área fiscal
Documentos relacionados	2 de 4: Fluxos de processamento · 3 de 4: Processamento, resiliência, idempotência e contingência · 4 de 4: Mensageria e filas · English version

1. Resumo

A plataforma de emissão de documentos fiscais de produto da NFE.io recebe, por API REST, os dados de uma venda ou de uma movimentação de mercadorias, calcula os tributos quando o cliente pede, gera e assina o XML com o certificado digital da empresa, obtém a autorização da SEFAZ, guarda os arquivos e avisa o sistema do cliente por webhook.

A solução é formada por quatro subprodutos, que compartilham a mesma plataforma:

Subproduto	O que faz	Documento fiscal	Interlocutor governamental
NF-e	Emite, cancela, corrige (CC-e) e inutiliza a Nota Fiscal Eletrônica. Também emite notas de devolução, complementares, de crédito e de débito.	NF-e, modelo 55	SEFAZ autorizadora da UF do emitente (própria ou virtual) e Ambiente Nacional (EPEC)
NFC-e	Emite, cancela e inutiliza a Nota Fiscal de Consumidor Eletrônica, com emissão assíncrona ou síncrona e contingência offline.	NFC-e, modelo 65	SEFAZ autorizadora da UF do emitente (própria ou virtual)
Taxes (Cálculo de Impostos)	Calcula ICMS, ICMS-ST, FCP, DIFAL, IPI, PIS, COFINS, IBS e CBS por item e mantém o cadastro tributário de produtos. Atende a NF-e, a NFC-e e chamadas diretas do cliente.	Não emite documento	Não se comunica com a SEFAZ
Taxes Payment Forms (Guias de Recolhimento)	Gera a guia de recolhimento do DIFAL interestadual (GNRE ou DUA) a partir de uma NF-e autorizada.	GNRE / DUA	Portal GNRE e SEFAZ-ES

A NF-e e a NFC-e compartilham o mesmo domínio de negócio, o mesmo motor de geração de XML e a mesma camada de comunicação com a SEFAZ, mas rodam em aplicações separadas, com filas, bases e escalas próprias. Uma indisponibilidade ou um pico de volume em um dos produtos não afeta o outro.

2. Princípios de arquitetura

1. Emissão assíncrona orientada a mensagens. A API valida a requisição, registra o pedido e responde de imediato com o identificador da nota. A emissão segue em segundo plano, em etapas desacopladas por fila (numeração, assinatura, envio, consulta, notificação). Cada etapa pode ser repetida sem refazer as anteriores. A NFC-e oferece, além disso, um modo síncrono com prazo máximo de resposta.
2. Event Sourcing. Cada nota é um agregado cujo estado é a soma dos seus eventos (criada, numerada, assinada, autorizada, cancelada etc.). Nada é sobrescrito: o histórico completo fica disponível para auditoria e o fluxo sempre retoma a partir do último evento gravado.
3. Uma execução por nota. Uma trava distribuída por nota garante que só um processo trabalhe em cada nota por vez, e um controle de admissão impede que a mesma operação sobre uma nota gere duas execuções concorrentes (não se aplica ao reenvio do POST de emissão, que cria uma nota nova).
4. Nunca reenviar às cegas. Quando a comunicação com a SEFAZ termina sem resposta conclusiva (tempo esgotado), a plataforma consulta a situação da nota pela chave de acesso antes de qualquer reenvio. Isso evita a rejeição por duplicidade e a emissão em dobro.
5. Separação por produto. NF-e, NFC-e, Taxes e Payment Forms são aplicações independentes, com imagem de contêiner, ciclo de versão, filas e escala próprios.
6. Cálculo tributário como serviço. O cálculo de impostos é um serviço à parte, chamado pela NF-e e pela NFC-e durante a criação da nota e disponível também para o cliente consultar antes de emitir.
7. Falha fechada no cálculo. Se o cálculo de impostos não puder ser feito com segurança, a nota não é emitida com valores presumidos: ela aguarda o serviço voltar ou é recusada com o motivo.
8. Contingência prevista em lei. Os modos de contingência seguem o Manual de Orientação do Contribuinte (MOC) e os Ajustes SINIEF: EPEC para a NF-e e contingência offline para a NFC-e.
9. 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

Componente	Responsabilidade
Gateway HTTPS	Termina o TLS e roteia as rotas públicas de NF-e, NFC-e, Taxes e Payment Forms para as respectivas APIs.
API NF-e	Recebe os pedidos de emissão, cancelamento, carta de correção (CC-e), inutilização e eventos fiscais. Valida o payload e o cadastro, registra o pedido e o coloca na fila. Entrega a consulta da nota, a listagem, o XML e o PDF (DANFE). Executa de forma síncrona a inutilização de faixa de numeração. Escala horizontalmente conforme o uso de CPU e memória.
Worker NF-e	Executa cada etapa da emissão: criação da nota e cálculo de impostos, numeração, assinatura, envio à SEFAZ, consulta pela chave de acesso, montagem do XML de distribuição (nfeProc) e notificação. Executa cancelamento, CC-e, inutilização e a contingência EPEC.
API NFC-e	Mesmas responsabilidades da API NF-e para a NFC-e. No modo síncrono, cria a nota e calcula os impostos na própria requisição e aciona o worker diretamente para obter a autorização dentro do prazo.
Worker NFC-e	Executa as etapas da NFC-e, inclusive a autorização síncrona com prazo máximo, a contingência offline e a retransmissão das notas emitidas em contingência.
Worker de Read Model	Mantém atualizado o índice de consulta (listagens e buscas) a partir dos eventos das notas. A consulta de uma nota específica é sempre feita no event store, que é a fonte da verdade.
API Taxes	Calcula os tributos por item, mantém o cadastro tributário de produtos e publica as tabelas de códigos (natureza da operação, finalidade de aquisição, perfis tributários). Processa em segundo plano a validação e a ativação de produtos cadastrados.
API Taxes Payment Forms	Gera guias de recolhimento do DIFAL interestadual (GNRE ou DUA) a partir de uma NF-e autorizada, transmite o lote ao portal governamental e entrega o PDF e o XML da guia.
Broker de mensagens	Transporta as mensagens entre as etapas. Cada produto tem fila própria, fila de erro (dead-letter) e agendamento de novas tentativas com atraso. O documento 4 detalha a topologia e as filas.
Event store e snapshots	Guarda os eventos de cada nota, com controle de concorrência otimista, e fotografias periódicas (snapshots) para acelerar a leitura.
Armazenamento de objetos	Guarda o pedido original, o XML assinado, o lote enviado, o XML autorizado (nfeProc), o XML de rejeição, o XML do evento EPEC, os XMLs e PDFs de CC-e e o DANFE.
Índice de consulta	Elasticsearch, usado nas listagens e buscas de notas e de guias.
Cache distribuído	Travas por nota, controle de admissão de trabalho, indicador de contingência por UF (NF-e) e disjuntor de contingência por UF (NFC-e). Também guarda os indicadores de funcionalidade do Taxes.
MongoDB	Agendamento das novas tentativas, deduplicação de mensagens recebidas, cadastro de produtos e cenários do Taxes e registro das guias de recolhimento.
Empresas, Inscrições Estaduais e numeração	Serviço da plataforma que mantém o cadastro da empresa e das inscrições estaduais (série, ambiente, CSC da NFC-e, estratégia de contingência) e controla a sequência de numeração por série.
Custódia de Certificados A1	Serviço da plataforma que custodia os certificados digitais ICP-Brasil das empresas. O certificado é obtido a cada operação e usado em memória.
Notificações (Webhooks)	Serviço da plataforma que entrega os eventos ao endpoint configurado pelo cliente, com assinatura HMAC e reentrega automática.
Registro de uso	Contabiliza as operações para fins de bilhetagem.
Motor de regras tributárias	Base de regras de parceiro especializado, consultada pelo Taxes para ICMS, ICMS-ST, FCP, DIFAL, IPI, PIS e COFINS. O IBS e a CBS são calculados por serviço próprio da NFE.io.

4.2 Pilha tecnológica

Camada	Tecnologia
Linguagem e runtime	.NET 10 (C#), ASP.NET Core
Execução	Contêineres em Kubernetes, entrega contínua via Helm e GitOps
Mensageria	RabbitMQ com o framework Rebus
Persistência das notas	Event Sourcing sobre armazenamento de tabelas em nuvem, com snapshots
Arquivos	Armazenamento de objetos em nuvem
Consulta e listagem	Elasticsearch
Cache, travas e controles	Cache compatível com Redis
Agendamento e deduplicação	MongoDB
Integração SEFAZ	Biblioteca de comunicação com os Web Services da NF-e e da NFC-e (SOAP 1.2, assinatura XML, TLS mútuo, validação por schema XSD)
Leiaute	NF-e/NFC-e versão 4.00, com os grupos da Reforma Tributária do Consumo (IBS, CBS e IS) da NT 2025.002
DANFE	Geração própria de PDF (DANFE retrato e paisagem, DANFE NFC-e e DANFE de CC-e)
Observabilidade	OpenTelemetry (traces, métricas e logs) e monitoramento externo de heartbeat

5. Implantação

• As sete aplicações são implantadas de forma independente, cada uma com a sua imagem de contêiner e o seu ciclo de versão.
• As APIs operam com múltiplas réplicas e autoescalonamento horizontal por CPU (e, na NF-e, também por memória). Os workers processam várias mensagens em paralelo por réplica.
• Todas as aplicações expõem verificação de vivacidade (/healthz/live) e de prontidão (/healthz/ready). Nas aplicações de emissão, a prontidão confere o event store, o armazenamento de objetos, o broker, o cache e os serviços de cadastro e de certificados. O Kubernetes retira do balanceamento uma instância que não esteja pronta e reinicia 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.
• 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.
• Os parâmetros operacionais (prazos da NFC-e síncrona, contingência offline, filas, travas) são definidos na configuração de implantação de cada ambiente e versionados junto com o código.

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.
• Versões: v2 e v3. A v3 aceita o CNPJ alfanumérico; uma nota com CNPJ alfanumérico não é exibida pela v2.
• Modelo de dados: conta → empresa (CNPJ) → inscrição estadual (IE) → nota. As rotas são escopadas pela empresa.

Produto	Principais recursos
NF-e	Emitir (POST /v2/companies/{companyId}/productinvoices ou .../statetaxes/{statetaxId}/productinvoices); consultar, listar e consultar itens e eventos; cancelar (DELETE .../{id}); carta de correção (PUT .../{id}/correctionletter); baixar XML autorizado, XML de rejeição, XML do EPEC e PDF (DANFE); inutilizar a numeração de uma nota recusada (POST .../{id}/disablement) ou uma faixa (POST .../productinvoices/disablement); vincular e listar notas de crédito.
NFC-e	Emitir de forma assíncrona (POST /v2/companies/{companyId}/consumerinvoices) ou síncrona (POST .../consumerinvoices/sync); consultar, listar, itens e eventos; cancelar; baixar XML e PDF (DANFE NFC-e); inutilizar a numeração de uma nota recusada ou uma faixa.
Taxes	Calcular os tributos (POST /tax-rules/{tenantId}/engine/calculate); cadastrar, consultar e alterar produtos (/{tenantId}/products); consultar as tabelas de códigos (/tax-codes/...).
Payment Forms	Gerar guia a partir de uma NF-e emitida pela NFE.io (POST /v1/tax-payment-forms/{accountId}/{companyId}/gnre) ou a partir de um XML (.../gnre/xml); consultar a guia e baixar o PDF.
Cadastro	Empresas, certificados e inscrições estaduais, inclusive a troca manual de autorizador para contingência (POST /v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer).

Os downloads de XML e PDF são entregues como URL de acesso ao arquivo. Os contratos completos estão nas especificações OpenAPI publicadas na documentação da NFE.io.

6.2 Webhooks

Cada mudança relevante de estado gera uma notificação para o endpoint cadastrado pelo cliente.

Produto	Tipo do evento	Ações
NF-e	product_invoice	issued_successfully, issued_error, issued_failed, cancelled_successfully, cancelled_error, cancelled_failed, cce_successfully, cce_error, cce_failed, disabled_successfully, disabled_error, disabled_failed e, para os eventos fiscais da Reforma Tributária, dfe_event_successfully, dfe_event_error, dfe_event_failed, dfe_event_cancelled
NFC-e	consumer_invoice	issued_successfully, issued_error, issued_failed, issued_contingency, cancelled_*, disabled_*
Taxes	product_tax	created_successfully (produto ativo), custom_rules_requested (tributação personalizada em análise), creation_failed (erro)
Payment Forms	tax_payment_form	created_successfully (guia gerada), creation_failed (erro), creation_not_needed (guia desnecessária)

• O sufixo _error indica uma falha pontual (rejeição da SEFAZ ou erro de validação). O sufixo _failed indica que as tentativas se esgotaram. Alguns limites terminam com _error, como o das consultas que retornam 217 e o das tentativas do cálculo de impostos (documento 3).
• O corpo traz o recurso completo da nota, com status e o histórico recente em lastEvents.
• A entrega é do tipo pelo menos uma vez (at-least-once), com reentrega automática e assinatura HMAC. O sistema do cliente deve tratar notificações repetidas de forma idempotente, usando o cabeçalho X-Hook-Id e o id da nota. A política completa está no catálogo de eventos de webhook.

6.3 Console

O console app.nfe.io usa as mesmas APIs para emitir, consultar, baixar arquivos, cancelar e inutilizar. Não há diferença de dados entre console e API.

7. Segurança e privacidade

Tema	Como é tratado
Certificado digital	A assinatura do XML e o TLS mútuo com a SEFAZ usam o certificado A1 (ICP-Brasil) da própria empresa, custodiado pelo serviço de certificados da NFE.io. O certificado é obtido a cada operação, usado em memória e descartado ao fim da chamada. A validade é conferida antes da assinatura: um certificado vencido ou ainda não válido encerra a emissão com erro, sem chamada à SEFAZ.
Canal com o governo	HTTPS com autenticação mútua, TLS 1.2 ou superior. O XML é validado contra os schemas oficiais antes do envio.
Canal com o cliente	HTTPS no gateway, autenticação por chave de API e autorização por perfil de produto. No Taxes, a conta informada na rota precisa ser a da chave de API; caso contrário, a resposta é HTTP 403.
Isolamento entre clientes	Isolamento lógico: todo registro e toda consulta carregam o identificador da conta e da empresa. Uma conta não enxerga notas de outra.
Credenciais internas	Mantidas em cofre de segredos, com comunicação autenticada entre os serviços da plataforma.
CSC da NFC-e	O Código de Segurança do Contribuinte e o seu identificador ficam no cadastro da inscrição estadual e são usados apenas para gerar o QR Code.
Auditoria	Cada nota guarda a sequência completa de eventos (pedido, cálculo, numeração, assinatura, envio, resposta da SEFAZ, notificação), com data e hora, além dos XMLs enviados e recebidos.
LGPD	As notas contêm dados pessoais de destinatários (nome, CPF, endereço). A NFE.io atua como operadora desses dados em nome do cliente emitente, que é o controlador. Os dados são usados apenas para a emissão, a guarda e a entrega dos documentos.

8. Resiliência

Mecanismo	Descrição
Etapas com novas tentativas	Cada etapa que falha por motivo transitório é reagendada com espera crescente. Quando o limite de tentativas se esgota, a nota termina com a ação _failed (ou _error, nos limites de consultas com 217 e de cálculo de impostos) e o motivo. O documento 3 traz os intervalos.
Filas de erro	Mensagens que falham repetidamente na entrega vão para uma fila de erro e podem ser reprocessadas pela equipe de operação, sem perda do pedido.
Consulta antes de reenviar	Tempo esgotado ou duplicidade na SEFAZ levam a uma consulta pela chave de acesso, nunca a um reenvio às cegas.
Trava por nota e controle de admissão	Uma única execução por nota e por operação; pedidos repetidos de uma operação sobre a mesma nota, enquanto ela está em curso, são descartados. O reenvio do POST de emissão cria uma nota nova.
Deduplicação de mensagens	O consumidor descarta a reentrega de uma mensagem já processada dentro de uma janela de 5 minutos.
Retomada pelo event store	Qualquer etapa retoma a partir do último evento gravado da nota.
Validação do certificado antes do envio	Evita tentativas inúteis com certificado inválido.
Contingência	EPEC para a NF-e e contingência offline para a NFC-e, detalhadas no documento 3.
Cálculo de impostos com retentativa e reserva	Retentativas em falhas transitórias do motor tributário e uso de cálculo recente armazenado quando o motor está indisponível, dentro de regras restritas.
Verificações de saúde e heartbeat	Instâncias doentes saem do balanceamento; um monitor externo alerta a equipe se algum componente parar de responder.

9. Referências governamentais

• Portal Nacional da NF-e, Manual de Orientação do Contribuinte (MOC) versão 7.0 (Visão Geral, Anexo I: Leiaute e Regras de Validação, Anexo III: Manual de Contingência da NF-e, Anexo IV: Manual de Contingência da NFC-e): https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=ndIjl+iEFdE%3D
• Portal Nacional da NF-e, Notas Técnicas, inclusive a NT 2025.002 (Reforma Tributária do Consumo) e a NT 2014.001 (EPEC): https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=04BIflQt1aY%3D
• Portal Nacional da NF-e, Relação de Serviços Web (autorizadores por UF e SVC): https://www.nfe.fazenda.gov.br/portal/webServices.aspx?tipoConteudo=OUC/YVNWZfo%3D
• CONFAZ, Ajuste SINIEF 07/05 (NF-e): https://www.confaz.fazenda.gov.br/legislacao/ajustes/2005/AJ007_05
• CONFAZ, Ajuste SINIEF 19/16 (NFC-e): https://www.confaz.fazenda.gov.br/legislacao/ajustes/2016/AJ_019_16