Arquitetura de Mensageria e Filas: NF-e, NFC-e, Taxes e Taxes Payment Forms
1. Resumo
O processamento assíncrono da plataforma é feito por mensagens trocadas entre as aplicações por meio de um broker RabbitMQ, com o framework Rebus (.NET). A mensageria é o que permite à API responder de imediato ao cliente e seguir a emissão em segundo plano, etapa por etapa, com novas tentativas agendadas, fila de erro e deduplicação.
- Cada produto tem a sua própria fila de trabalho e a sua fila de erro (dead-letter). Um pico de volume da NF-e não disputa fila com a NFC-e, com o Taxes ou com o Payment Forms.
- As etapas das notas usam envio direto a uma fila. Dois fluxos usam tópicos (publicação e assinatura): o aviso de mudança da nota ao Read Model e as etapas das guias do Payment Forms (seção 4).
- As APIs apenas publicam. Quem consome são os workers (NF-e, NFC-e e Read Model) e as próprias aplicações Taxes e Payment Forms, que processam as suas filas em segundo plano.
- As mensagens carregam identificadores e o estado do fluxo e, quando a operação exige, o texto da justificativa ou da correção. O pedido de emissão, o XML e os dados do destinatário ficam no armazenamento da plataforma, nunca no broker.
- A entrega é pelo menos uma vez (at-least-once). A plataforma tem três camadas de proteção contra processamento duplicado: controle de admissão por nota e operação, deduplicação de mensagens e trava por nota.
2. Princípios
- Publicador de via única. As APIs de NF-e e NFC-e só enviam mensagens: não têm fila de entrada nem consomem mensagens. Isso mantém a API leve e escalável.
- Uma fila por produto. Todas as etapas de todas as notas de um produto circulam pela mesma fila de trabalho. A etapa a executar vem dentro da mensagem.
- Mensagem enxuta. A mensagem diz qual nota e qual etapa; o worker lê o estado da nota no event store antes de agir. Isso torna a mensagem pequena, independente da versão do leiaute e sem os dados do pedido.
- Encadeamento por etapa. Ao terminar uma etapa, o worker publica a mensagem da etapa seguinte, ou da mesma etapa com espera, no caso de nova tentativa. Não existe uma mensagem longa que atravessa todo o fluxo.
- Esperas persistidas. Novas tentativas com espera são mensagens agendadas, gravadas em armazenamento durável até o momento da entrega. Um reinício do worker não perde o agendamento.
- Falha isolada. Uma mensagem que falha repetidamente vai para a fila de erro do produto, sem bloquear as demais e sem alterar a nota.
3. Topologia
- NF-e e NFC-e: a API publica a primeira etapa de cada operação na fila do produto; o worker consome, executa e publica a etapa seguinte na mesma fila.
- Read Model: toda gravação de evento de nota publica um aviso por tópico. O Worker de Read Model assina esse tópico e atualiza o índice de consulta (listagens e buscas).
- Taxes e Payment Forms: cada aplicação publica para a sua própria fila e consome dela, para executar em segundo plano a validação de produtos cadastrados (Taxes) e as etapas de geração das guias (Payment Forms).
4. Inventário de filas, exchanges e tópicos
4.1 Filas
| Fila | Consumidor | Quem publica | O que transporta | Fila de erro |
|---|
product-invoice-v5 | Worker NF-e | API NF-e (entrada de cada operação) e Worker NF-e (etapas seguintes e novas tentativas) | Etapas de emissão, cancelamento, CC-e, inutilização, eventos fiscais, vínculo de nota de crédito e reprocessamento da NF-e | dlq-product-invoice-v5 |
consumer-invoice-v5 | Worker NFC-e | API NFC-e (entrada) e Worker NFC-e (etapas seguintes, novas tentativas, retransmissão da contingência offline e a continuação da emissão síncrona) | Etapas de emissão, cancelamento, inutilização e retransmissão da NFC-e | dlq-consumer-invoice-v5 |
read-model-v4 | Worker de Read Model | Todas as aplicações que gravam eventos de NF-e e NFC-e | Aviso de que uma nota mudou (tipo do agregado, identificador e tipo do evento) | dlq-read-model-v4 |
taxes-v4 | Taxes | Taxes | Validação do cálculo, registro e conferência de regras de produtos com tributação personalizada e webhook de produto | dlq-taxes-v4 |
taxes-payment-forms-v4 | Taxes Payment Forms | Taxes Payment Forms | Etapas da guia (criada, preparada, transmitida, gerada, erro, desnecessária) | dlq-taxes-payment-forms-v4 |
nf-product-invoice-contingency | Não é consumida diretamente pelos workers | Worker NF-e | NF-e emitidas em EPEC aguardando a volta à SEFAZ de origem | Não se aplica |
Fila de contingência da NF-e. Depois que uma nota é emitida em EPEC, o worker grava nesta fila, com espera de 30 minutos, a mensagem da transmissão posterior à SEFAZ de origem. A fila funciona como área de espera: os workers não a consomem diretamente. No encerramento da contingência, a regularização das notas em EPEC é conduzida pela equipe de operação da NFE.io (documento 3, seção 11.2).
4.2 Exchanges
No RabbitMQ, a mensagem não é entregue diretamente à fila: ela é publicada em um exchange, que a encaminha às filas vinculadas a ele conforme a chave de roteamento. A plataforma usa os dois exchanges padrão do framework de mensageria, ambos duráveis:
| Exchange | Tipo | Uso | Como as filas se vinculam |
|---|
RebusDirect | Direto (direct) | Envio ponto a ponto a uma fila específica: todas as etapas de NF-e e NFC-e, as mensagens do Taxes, a fila de contingência da NF-e e as mensagens agendadas no momento da entrega | Cada fila é vinculada com o próprio nome como chave de roteamento. Enviar para product-invoice-v5 significa publicar em RebusDirect com a chave product-invoice-v5 |
RebusTopics | Tópico (topic) | Publicação e assinatura: um publicador anuncia um fato sem conhecer os consumidores, e cada fila assinante recebe uma cópia | Cada fila assinante é vinculada com o nome do tópico como chave de roteamento |
4.3 Tópicos
O nome de cada tópico é o nome completo do tipo de mensagem, com o nome do módulo que o define. Esta é a convenção padrão do framework de mensageria.
| Tópico | Publicadores | Fila assinante | Consumidores na fila | Quando é publicado |
|---|
DFeTech.ProductInvoice.Workers.ReadModelAggregateInfo, DFeTech.ProductInvoice | API NF-e, Worker NF-e, API NFC-e e Worker NFC-e | read-model-v4 | Atualização do índice de NF-e e atualização do índice de NFC-e. Cada uma filtra pelo tipo da nota e pelos tipos de evento que afetam a consulta | A cada evento gravado em uma NF-e ou NFC-e, logo após a gravação no event store, e no reprocessamento do índice solicitado pela operação |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormCreated, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Processamento da guia, índice de consulta e registro de uso | Guia criada |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormPrepared, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Processamento da guia e índice de consulta | Guia preparada para transmissão |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormTransmitted, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Processamento da guia e índice de consulta | Lote transmitido ao portal |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormGenerated, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Índice de consulta, webhook e registro de uso | Guia gerada, com PDF |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormError, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Índice de consulta, webhook e registro de uso | Erro na geração |
DFeTech.Api.Taxes.PaymentForms.Workers.TaxPaymentFormErrorNotNeeded, DFe.Api.Taxes.PaymentForms | Taxes Payment Forms | taxes-payment-forms-v4 | Índice de consulta, webhook e registro de uso | Guia desnecessária |
- Assinatura. Cada consumidor registra as suas assinaturas ao iniciar: o Worker de Read Model assina o tópico do aviso de mudança, e o Payment Forms assina os seis tópicos das etapas da guia. A assinatura é um vínculo persistido no broker. Enquanto o consumidor está fora do ar, as mensagens publicadas ficam retidas na fila assinante e são processadas quando ele volta.
- Uma cópia por fila assinante. Hoje cada tópico tem uma única fila assinante. Um novo consumidor pode assinar o mesmo tópico sem alterar o publicador.
- Todos os consumidores de uma mensagem rodam juntos. Quando uma fila recebe uma mensagem de tópico, todos os consumidores daquele tipo de mensagem na aplicação são executados na mesma entrega. No Payment Forms, uma falha em qualquer um deles repete a entrega inteira (a cada 10 segundos, até 100 vezes).
- O que não usa tópicos. As etapas de NF-e e NFC-e, as mensagens do Taxes e a fila de contingência usam apenas o envio direto (
RebusDirect). Assim, nenhuma outra aplicação recebe cópia das etapas de emissão.
4.4 Roteamento
5. Mensagens
5.1 Mensagem de trabalho da NF-e e da NFC-e
Todas as etapas das notas usam o mesmo tipo de mensagem, com estes campos:
| Campo | Conteúdo |
|---|
| Identificadores | Conta, empresa, inscrição estadual, nota e UF (código IBGE) |
| Tipo de processo | Operação em curso (tabela 5.2) |
| Etapa | Etapa a executar (tabela 5.3) |
| Contador de tentativas | Número de repetições da etapa atual; recomeça a cada mudança de etapa |
| Contador de espera por trava | Número de reagendamentos por nota ocupada |
| Execução | Identificador único da execução, usado para rastrear e limpar o controle de admissão |
| Dados da operação | Quando aplicável: identificador do evento fiscal, dados da nota de crédito a vincular (inclusive a chave de acesso) e o texto da justificativa do cancelamento ou da correção da CC-e |
A mensagem também leva esses identificadores em cabeçalhos, o que permite rastrear a nota no broker e nos logs sem abrir o corpo. O pedido original de emissão é guardado no armazenamento de objetos antes da publicação; a mensagem só aponta para ele.
5.2 Tipos de processo
| Tipo | Uso |
|---|
Issue | Emissão |
Cancel | Cancelamento |
CorrectionLetter | Carta de Correção (NF-e) |
Disable | Inutilização da numeração de uma nota recusada |
DFeEvent | Eventos fiscais da Reforma Tributária (NF-e) |
LinkCreditInvoice | Vínculo de nota de crédito (NF-e) |
Contingency | Transmissão posterior das notas em EPEC (NF-e) |
Reprocess | Reprocessamento solicitado pela equipe de operação |
5.3 Etapas
| Grupo | Etapas |
|---|
| Emissão | Requested (criação e cálculo de impostos), DefineNumber, Send, CheckAuthorizationByAccessKey, CheckAuthorization, MergeAuthorization, Notify |
| Contingência | MergeAuthorizationContingency (EPEC), TransmitOfflineContingency (NFC-e offline) |
| Carta de Correção | AddCorrectionLetter, MergeCorrectionLetter |
| Cancelamento | Cancel, MergeCancellation |
| Inutilização | Disable, MergeDisablement |
| Eventos fiscais | AddDFeEvent, MergeDFeEvent |
| Nota de crédito | LinkCreditInvoiceAgainst |
| Fim | Finished: nenhuma mensagem é publicada; o controle de admissão da operação é encerrado |
5.4 Demais mensagens
| Fila | Mensagens | Conteúdo |
|---|
read-model-v4 | Aviso de mudança da nota | Tipo do agregado, identificador e tipo do evento. O Worker de Read Model relê a nota no event store e atualiza o índice. Validade da mensagem: 3 dias |
taxes-v4 | Validação do cálculo do produto, registro no motor de regras, conferência das regras, webhook de produto | Conta, coleção e produto (e, no webhook, o tipo e a ação do evento) |
taxes-payment-forms-v4 | Guia criada, preparada, transmitida, gerada, com erro ou desnecessária | Pedido, conta, empresa e tipo da guia |
6. Encadeamento das etapas
- Próxima etapa. A mensagem seguinte só é publicada depois que a trava da nota é liberada, o que evita que a próxima etapa encontre a nota ocupada pela anterior.
- Nova tentativa. Se a etapa termina em falha transitória, o worker publica a mesma etapa com espera, conforme a escada da etapa (documento 3, seção 9.1). A primeira execução de cada etapa é imediata.
- Esperas. As mensagens com espera ficam gravadas em armazenamento durável (MongoDB) até o momento da entrega, e só então entram na fila.
- Trava ocupada. Se a nota estiver ocupada por outra execução, a etapa é reagendada com espera de 2, 5, 15, 30, 60 e, daí em diante, 120 segundos (variação aleatória de 20%), sem consumir o contador de tentativas da etapa. Após 30 reagendamentos (cerca de 52 minutos), a plataforma desiste e encerra a nota com o motivo.
- Fim do fluxo. A etapa
Finished não gera mensagem: ela encerra o controle de admissão e registra a conclusão recente da operação.
6.1 Esperas por etapa
| Etapa | Espera entre as tentativas |
|---|
| Envio à SEFAZ | 5 s, 10 s, 15 s, 1 min, 5 min e, a partir daí, 10 min |
| Consulta pela chave de acesso | 30 s, 1 min, 2 min, 4 min, 8 min, 16 min, 32 min e, a partir daí, 64 min |
| Consulta pelo recibo (lote assíncrono) | 5 s, 10 s, 1 min, 5 min, 10 min, 1 h e, a partir daí, 13 min |
| Retransmissão da NFC-e em contingência offline | A cada 10 min |
| Demais etapas | 5 s até a 10ª tentativa, 1 min até a 20ª, 5 min até a 50ª e, a partir daí, 10 min |
Exceções: no fluxo de contingência (transmissão das notas em EPEC), o envio e a consulta pelo recibo seguem a escada das demais etapas; na consulta pela chave que acabou de reenviar a nota no ciclo do cStat 217 (NFC-e), vale a escada do envio.
7. Garantias de entrega e tratamento de erros
7.1 Entrega
- A entrega é pelo menos uma vez. Uma mensagem só é removida da fila depois que o processamento termina; se a instância cair no meio, a mensagem é entregue de novo. As proteções da seção 8 impedem o efeito duplicado.
- Não há garantia de ordem entre mensagens no broker. A ordem das etapas de uma nota é garantida pelo desenho: há uma única mensagem em curso por nota e operação, e a seguinte só é publicada ao fim da anterior.
7.2 Falhas de negócio e falhas técnicas
| Situação | Tratamento |
|---|
| Falha transitória numa etapa de nota (SEFAZ indisponível, serviço interno fora do ar) | O worker captura a falha e publica uma nova tentativa com espera, até os limites da etapa (100 tentativas de negócio e teto técnico de 150). Ao atingir o limite, a nota é encerrada com o motivo |
| Falha técnica que impede o processamento da mensagem (por exemplo, falha ao publicar a próxima etapa ou ao ler a mensagem) | O framework de mensageria processa a mesma mensagem de novo, até 10 tentativas de entrega |
| Falha persistente após as 10 entregas | A mensagem vai para a fila de erro do produto (dlq-*). A nota não é alterada: ela continua na etapa em que estava, porque pode estar, por exemplo, já autorizada na SEFAZ |
| Payment Forms | Cada falha reagenda a mensagem em 10 segundos, até 100 vezes, antes de enviá-la à fila de erro |
7.3 Filas de erro e reprocessamento
- Ao enviar uma mensagem de nota à fila de erro, a plataforma encerra o controle de admissão daquela execução, o que libera a nota para reprocessamento.
- A equipe de operação reprocessa pelas rotas internas de manutenção: nova tentativa da etapa atual, nova criação de nota represada, nova consulta pela chave de acesso e atualização do índice de consulta. Essas rotas recusam o reprocessamento de uma nota que ainda tenha execução em curso.
- Mensagens da fila de erro também podem ser reenviadas à fila de origem, depois de sanada a causa.
8. Idempotência e ordenação
| Camada | Como funciona | Janela |
|---|
| Controle de admissão | Na entrada de cada operação sobre uma nota (cancelamento, CC-e, inutilização, evento, vínculo de nota de crédito), a plataforma grava um registro condicional por nota e operação. Se já existe uma execução viva, o pedido repetido é descartado sem nova mensagem, sem nova chamada à SEFAZ e sem novo webhook (o registro de entrada do pedido é gravado normalmente). Se a publicação falhar, o registro é desfeito. Na emissão, cada POST gera uma nota nova: o controle protege as republicações internas (por exemplo, o reprocessamento), não o reenvio do pedido pelo cliente | Enquanto a execução estiver viva; um registro sem atividade por 24 horas é considerado abandonado |
| Conclusão recente | Logo após o fim da operação, um registro de curta duração impede a readmissão imediata do mesmo trabalho | 5 minutos |
| Deduplicação de mensagens (workers de NF-e e NFC-e) | Cada mensagem tem um identificador único, composto por nota, operação, etapa, contadores e um identificador da publicação. O worker registra cada mensagem processada com sucesso e descarta a reentrega do mesmo identificador | 5 minutos |
| Trava por nota | Uma única etapa por nota é executada por vez, com trava distribuída de validade de 5 minutos | Por etapa |
| Estado da nota | O worker sempre relê a nota no event store: uma etapa repetida parte do estado já gravado e não refaz o que foi concluído (por exemplo, a assinatura) | Permanente |
O identificador único da mensagem é registrado só depois do processamento bem-sucedido. Assim, uma reentrega provocada por falha continua sendo processada, e apenas a repetição de uma mensagem já concluída é descartada.
9. Concorrência e escala
| Consumidor | Processamento paralelo por réplica | Réplicas em produção |
|---|
| Worker NF-e | Até 64 mensagens | 2 a 5, com autoescalonamento por CPU e memória |
| Worker NFC-e | Até 64 mensagens | 1 |
| Worker de Read Model | Até 20 mensagens | 2 |
| Taxes | Até 24 mensagens | 2 a 10, com autoescalonamento por CPU |
| Taxes Payment Forms | Até 24 mensagens | 1 a 6, com autoescalonamento por CPU |
As APIs de NF-e e NFC-e, que só publicam, operam com 2 a 10 réplicas.
10. Indisponibilidade do broker
| Situação | Comportamento |
|---|
| Broker indisponível na entrada do pedido | A API responde 503. Nenhuma nota é criada e o controle de admissão é desfeito, de modo que o pedido pode ser reenviado com segurança |
| Broker indisponível no meio do fluxo | A mensagem em curso não é confirmada e volta a ser entregue quando o broker retorna; a nota retoma da etapa em que estava |
| Verificação de prontidão | Nas APIs e nos workers de NF-e e NFC-e, a prontidão confere a conexão com o broker. Uma instância sem broker sai do balanceamento |
| Aviso ao Read Model | A publicação do aviso de mudança não bloqueia a emissão: se falhar, é registrada em log, e o índice de consulta é reconciliado pela equipe de operação. A consulta de uma nota específica continua correta, porque lê o event store |
11. O que não passa pela fila
| Comunicação | Meio |
|---|
| Emissão síncrona da NFC-e | Chamada HTTP interna direta da API ao worker. Só a etapa seguinte (notificação, consulta pela chave ou retransmissão da contingência) vai para a fila |
| Cálculo de impostos pela NF-e e pela NFC-e | Chamada HTTP ao Taxes, dentro da etapa de criação |
| Webhooks ao cliente | Chamada HTTP à plataforma de notificações da NFE.io, que faz a entrega com reentrega própria |
| Comunicação com a SEFAZ | Web Services SOAP com TLS mútuo |
| Inutilização de faixa de numeração | Chamada direta da API à SEFAZ, dentro da requisição |
| Registro de uso | Chamada HTTP ao serviço de bilhetagem; uma falha nesse registro não interrompe o fluxo |
12. Observabilidade
- O framework de mensageria é instrumentado com OpenTelemetry: cada mensagem gera rastreamento distribuído, ligado ao rastreamento da requisição que a originou.
- Métricas próprias da mensageria incluem: execuções com sucesso e com falha por etapa, duração de cada etapa e do fluxo completo, disputa e desistência de trava, pedidos suprimidos pelo controle de admissão, mensagens duplicadas descartadas e mensagens de nota enviadas à fila de erro (com a liberação do controle de admissão).
- Os logs de cada mensagem trazem conta, empresa, inscrição estadual, nota, UF, etapa e contador de tentativas, o que permite reconstruir a cronologia de uma nota.
13. O que isso significa para o cliente
- O cliente não se conecta ao broker: a integração é sempre pela API REST e pelos webhooks.
- A resposta da API confirma que o pedido foi registrado e enfileirado, não que a nota foi autorizada. O resultado chega por webhook e pela consulta.
- Um 503 na entrada significa que nada foi enfileirado: o pedido pode ser reenviado.
- Como a entrega é at-least-once em toda a cadeia, os webhooks podem chegar repetidos: trate-os de forma idempotente (documento 3, seção 10.2).
- Pedidos repetidos de cancelamento, CC-e ou inutilização enquanto a operação anterior da mesma nota ainda está em curso são descartados pela plataforma, sem duplicar a chamada à SEFAZ. A resposta a esse pedido repetido é a mesma de sucesso, embora nada novo seja enfileirado. Isso vale também para uma segunda CC-e com texto diferente: aguarde a conclusão da anterior (webhook ou consulta) antes de enviar outra.
- Na emissão, cada
POST cria uma nota nova. Não reenvie o pedido sem antes consultar a listagem de notas (documento 3, seção 10.2).