Detalhamento do Processamento, Resiliência, Idempotência e Contingência: NF-e, NFC-e, Taxes e Taxes Payment Forms

Produto	Emissão de Nota Fiscal de Produto NFE.io (dfetech-product-invoice-api)
Documento	3 de 4: Detalhamento do processamento e das regras de resiliência, idempotência e contingência
Versão	1.0 (24/09/2026)
Público	Clientes, times de arquitetura, TI, auditoria e área fiscal
Documentos relacionados	1 de 4: Arquitetura · 2 de 4: Fluxos de processamento · 4 de 4: Mensageria e filas · English version

Sumário

1. Resumo executivo
2. Conceitos
3. Regras do governo que regem a emissão
4. NF-e
5. NFC-e
6. Taxes: cálculo de impostos
7. Taxes Payment Forms: guias de recolhimento
8. Relação entre NF-e, NFC-e e Taxes
9. Regras de resiliência
10. Regras de idempotência
11. Contingência
12. Responsabilidades do cliente
13. Referências governamentais

---

1. Resumo executivo

• Emissão assíncrona com resposta imediata. A NF-e e a NFC-e aceitam o pedido, devolvem o identificador da nota (id) e seguem a emissão em segundo plano. O resultado chega por webhook e fica disponível na consulta. A NFC-e também tem um modo síncrono, que devolve o resultado na mesma requisição dentro de um prazo de 10 segundos no processamento da autorização.
• Etapas independentes e retomáveis. Criação e cálculo de impostos, numeração, assinatura, envio, consulta e notificação são etapas separadas. Cada nota é persistida como uma sequência de eventos (Event Sourcing), e qualquer etapa retoma a partir do último evento gravado.
• Resiliência. Falhas transitórias (SEFAZ fora do ar, tempo esgotado, serviço interno indisponível) geram novas tentativas com espera crescente. Falhas definitivas (rejeição da SEFAZ, erro de validação, certificado vencido) encerram a nota com o motivo, sem tentativas inúteis. Na NFC-e síncrona sem contingência offline habilitada, a indisponibilidade da SEFAZ encerra a nota com erro, para não prender o ponto de venda.
• Idempotência. Uma nota nunca é enviada duas vezes às cegas: diante de tempo esgotado ou de duplicidade, a plataforma consulta a nota pela chave de acesso. Uma trava por nota e um controle de admissão garantem uma única execução por nota e por operação, e o consumidor descarta mensagens repetidas.
• Contingência. A NF-e usa o EPEC (tpEmis 4), ativado pelo próprio cliente (estratégia Manual) ou pela NFE.io por UF (estratégia StateTaxAuthorityStatusUnavailable). A NFC-e usa a contingência offline (tpEmis 9), acionada automaticamente por tempo esgotado ou indisponibilidade e, de forma preventiva, por um disjuntor por UF.
• Relação com o Taxes. A NF-e e a NFC-e chamam o Taxes durante a criação da nota, antes da numeração, quando o cliente pede o cálculo automático nos itens. Se o cálculo não puder ser feito, a nota aguarda ou é recusada: nunca é emitida com tributo presumido.

2. Conceitos

Termo	Significado
Chave de acesso	Identificador de 44 posições da NF-e/NFC-e. Inclui a UF, o ano e o mês de emissão, o CNPJ do emitente, o modelo, a série, o número e o tipo de emissão (tpEmis).
cStat	Código de situação devolvido pela SEFAZ. Exemplos: 100 (autorizado), 150 (autorizado fora de prazo), 204 e 539 (duplicidade), 217 (nota não consta na base), 301, 302 e 303 (uso denegado).
tpEmis	Tipo de emissão: 1 (normal), 4 (EPEC), 6 (SVC-AN), 7 (SVC-RS) e 9 (contingência offline da NFC-e), entre outros.
dhCont e xJust	Data e hora de entrada em contingência e justificativa, obrigatórias nas notas emitidas em contingência.
EPEC	Evento Prévio de Emissão em Contingência. Registra a nota no Ambiente Nacional quando a SEFAZ de origem está indisponível.
Contingência offline	Modalidade da NFC-e em que a nota é emitida e entregue ao consumidor sem autorização prévia e transmitida depois.
Inscrição estadual (IE)	No cadastro da NFE.io, cada IE da empresa define o tipo de documento (NF-e ou NFC-e), a série, o ambiente (produção ou homologação), o CSC da NFC-e e a estratégia de contingência.
CSC	Código de Segurança do Contribuinte, usado no QR Code da NFC-e.
Event Sourcing	Forma de persistência em que o estado da nota é a soma dos seus eventos, gravados em ordem e nunca sobrescritos.
Idempotência	Garantia de que repetir uma operação não produz efeito duplicado.
At-least-once	Garantia de entrega "pelo menos uma vez": uma mensagem ou webhook pode chegar repetido, nunca perdido.

3. Regras do governo que regem a emissão

Tema	Regra	Fonte
Leiaute e validação	Leiaute 4.00 da NF-e e da NFC-e e regras de validação do MOC 7.0, atualizadas por Notas Técnicas	MOC 7.0, Anexo I
Reforma Tributária do Consumo	Grupos de IBS, CBS e IS no leiaute, com a versão vigente da NT 2025.002	NT 2025.002
Contingência da NF-e	Modalidades FS-IA, EPEC, FS-DA, SVC-AN e SVC-RS. No EPEC, a NF-e deve ser transmitida à SEFAZ de origem em até 168 horas da emissão	MOC 7.0, Anexo III; Ajuste SINIEF 07/05
Restrição de UF para o EPEC	A partir de 05/10/2026, a regra de validação 2P10-20 veda o EPEC para emitentes do PR e da PB	NT 2014.001 v1.41
Contingência da NFC-e	A NFC-e em contingência offline deve ser transmitida até o final do primeiro dia útil subsequente à emissão. Se rejeitada, deve ser regenerada com o mesmo número e série, sem alterar valores, partes e datas. A numeração de NFC-e emitida em contingência não pode ser inutilizada	Ajuste SINIEF 19/16; MOC 7.0, Anexo IV
Cancelamento da NF-e	Em até 24 horas da autorização, desde que não tenha havido circulação da mercadoria. Cancelamento fora do prazo fica a critério de cada UF	Ajuste SINIEF 07/05
Cancelamento da NFC-e	Em até 24 horas, prazo que cada UF pode reduzir	Ajuste SINIEF 19/16
Carta de Correção (CC-e)	Evento 110110, só depois da autorização. Não corrige valores que determinam o imposto, dados de remetente ou destinatário, nem datas de emissão ou saída. A CC-e mais recente substitui as anteriores e deve conter todas as correções. Até 20 CC-e por nota. Não se aplica à NFC-e	Ajuste SINIEF 07/05
Inutilização	Para números que não serão usados, até o dia 10 do mês seguinte	Ajuste SINIEF 07/05 e 19/16
Consulta de status do serviço	Quem consulta a disponibilidade da SEFAZ em laço deve respeitar intervalo mínimo de 3 minutos	MOC 7.0, Visão Geral

---

4. NF-e

4.1 Pré-requisitos

1. Empresa cadastrada e ativa na NFE.io, com certificado digital A1 (ICP-Brasil) válido.
2. Inscrição estadual ativa do tipo NF-e, com série e ambiente (produção ou homologação) definidos.
3. Chave de API com o perfil de Nota Fiscal.
4. Opcionalmente, webhook cadastrado para o tipo de evento product_invoice.

4.2 Recepção e validação (síncrono, na API)

O POST /v2/companies/{companyId}/productinvoices (ou .../statetaxes/{statetaxId}/productinvoices, para escolher a inscrição estadual) executa, dentro da requisição:

1. Autenticação da chave de API e autorização pelo perfil do produto.
2. Conversão do payload. Um payload mal formado retorna 400 com a lista de erros.
3. Leitura da empresa e aplicação das regras de validação do payload e do cadastro (por exemplo, obrigatoriedades do leiaute, da Reforma Tributária e das notas de devolução, crédito e débito). Uma violação retorna 400.
4. Geração do identificador da nota (id) e armazenamento do pedido original.
5. Publicação da etapa de criação na fila de emissão.

A resposta é 200 com o recurso da nota e o id. A partir daí, o processamento é assíncrono. Se a publicação na fila falhar, a API responde 503 e nenhuma nota é criada, de modo que o pedido pode ser reenviado com segurança.

Sem statetaxId na rota, a plataforma usa a primeira inscrição estadual da lista de inscrições da empresa. Se ela não for do tipo NF-e ou não estiver ativa, o pedido é recusado com 400. Quando a empresa tiver mais de uma inscrição estadual, informe o statetaxId.

4.3 Criação da nota e cálculo de impostos (worker)

1. O worker obtém a trava da nota (seção 9.4).
2. Se a nota já existe no event store, o pedido é tratado como repetição e o fluxo retoma da etapa em que a nota está.
3. Confere se a empresa e a inscrição estadual estão ativas e se a IE é do tipo NF-e.
4. Aplica as verificações de negócio (estratégia de contingência da IE, regras de nota de crédito e débito, Zona Franca de Manaus, obrigatoriedade de IBS/CBS, totais de nota complementar).
5. Calcula os impostos no Taxes, quando o cliente pediu (seção 8).
6. Verifica se há contingência EPEC ativa para a IE ou para a UF (seção 11.2). Se houver, a nota nasce marcada para EPEC.
7. Cria o agregado e grava os eventos iniciais. A nota passa a existir com status Created.

Qualquer falha definitiva nesta etapa recusa a nota: ela é gravada com status Error e o cliente recebe product_invoice.issued_error com o motivo.

4.4 Numeração

• Se o pedido informou a série e o número, eles são usados como vieram.
• Se não informou, a série vem da inscrição estadual e o número vem da sequência de numeração mantida pelo cadastro da NFE.io para aquela IE e série.
• Uma falha definitiva de numeração (por exemplo, série não cadastrada) recusa a nota.

Numeração informada pelo cliente

Quando o cliente informa o número, a plataforma não consulta a sequência. Um número já usado por outra nota da mesma série é rejeitado pela SEFAZ por duplicidade (cStat 539). Se o seu sistema controla a numeração, garanta a unicidade por série do lado do seu sistema.

4.5 Assinatura e autorização

1. Geração da chave de acesso e do código numérico.
2. Obtenção do certificado A1 da empresa no serviço de custódia. A validade do certificado é conferida antes da assinatura: certificado vencido ou ainda não válido encerra a emissão com erro, sem chamada à SEFAZ.
3. Geração do XML no leiaute 4.00, assinatura digital e validação contra os schemas XSD oficiais. Uma falha de schema encerra a emissão com erro.
4. Armazenamento do XML assinado.
5. Envio ao Web Service de autorização (NFeAutorizacao4) da SEFAZ autorizadora da UF do emitente, com processamento síncrono (indSinc=1), por HTTPS com TLS mútuo. O tempo máximo de cada chamada é de 120 segundos.

A SEFAZ autorizadora é a da própria UF ou a SEFAZ Virtual que atende a UF (SVRS ou SVAN), conforme a relação oficial de Web Services do Portal Nacional da NF-e. Emitentes sem inscrição estadual (contribuintes exclusivamente de IBS/CBS) são direcionados à SVRS.

4.6 Tratamento das respostas da SEFAZ

Resposta	Classificação	O que a plataforma faz	O que o cliente vê
cStat 100 ou 150 (autorizada)	Sucesso	Monta o nfeProc e notifica	Issued, issued_successfully
Lote recebido sem resultado síncrono	Inconclusiva	Consulta pela chave de acesso	Aguarda
Tempo esgotado ou resposta inconclusiva	Inconclusiva	Consulta pela chave de acesso. Nunca reenvia	Aguarda
204 ou 539 com a chave desta mesma nota	Duplicidade da própria nota	Consulta pela chave e recupera o protocolo	Issued, se autorizada
204 ou 539 com outra chave	Rejeição	Encerra	Error, issued_error
Sem comunicação, SEFAZ indisponível	Transitória	Nova tentativa do envio (seção 9.1)	Aguarda
Rejeição de regra de validação	Definitiva	Guarda o XML de rejeição e encerra	Error, issued_error com cStat e motivo
Uso denegado (301, 302, 303)	Definitiva	Encerra	IssueDenied (quando identificado na consulta) ou Error (quando devolvido no envio síncrono), sempre com issued_error e o cStat da denegação
Certificado recusado no TLS	Definitiva	Encerra sem novas tentativas	Error, issued_error
Tentativas esgotadas	Definitiva	Encerra	Error, issued_failed

Consulta pela chave de acesso. A plataforma consulta a nota no Web Service NFeConsultaProtocolo4 com espera crescente (seção 9.1). Se a nota está autorizada, o protocolo é recuperado e o fluxo segue normalmente. Se a SEFAZ responde 217 (nota não consta na base), a consulta é repetida até 8 vezes; persistindo o 217, a nota é encerrada com issued_error e o cStat 217, e pode ter a numeração inutilizada.

4.7 Conclusão, arquivos e notificação

1. O protocolo de autorização é juntado ao XML, formando o XML de distribuição (nfeProc), que é armazenado.
2. A nota passa a Issued e o cliente recebe product_invoice.issued_successfully, com o recurso completo da nota.
3. O índice de consulta é atualizado em seguida, para as listagens.
4. O DANFE é gerado na primeira solicitação a GET .../productinvoices/{id}/pdf e fica armazenado para as solicitações seguintes.
5. O XML autorizado, o XML de rejeição e o XML do evento EPEC ficam disponíveis nas rotas .../xml, .../xml/rejection e .../xml-epec.

4.8 Cancelamento

• DELETE .../productinvoices/{id}?reason= responde 204 e processa em segundo plano.
• Só é aceito para nota Issued. A justificativa (reason) deve ter de 15 a 255 caracteres, contados depois da substituição dos caracteres que não existem no padrão Latin-1 aceito pela SEFAZ (os acentos do português são mantidos); se omitida, a plataforma usa o texto padrão "Erro de preenchimento".
• O worker assina o evento 110111 e o envia ao Web Service de eventos da SEFAZ autorizadora.
• cStat 135, 136 ou 155: a nota passa a Cancelled e o cliente recebe cancelled_successfully. Rejeição: cancelled_error com o motivo. Indisponibilidade: novas tentativas, e, se esgotadas, cancelled_failed.
• O prazo legal é validado pela SEFAZ (seção 3).

4.9 Carta de Correção Eletrônica (CC-e)

• PUT .../productinvoices/{id}/correctionletter com o texto da correção no campo reason (15 a 1.000 caracteres) responde 204.
• Só é aceita para nota Issued. O worker assina o evento 110110 com o número sequencial seguinte e o envia à SEFAZ autorizadora.
• Resultado: cce_successfully, cce_error ou cce_failed. O XML e o PDF da CC-e ficam em .../correctionletter/xml e .../correctionletter/pdf.
• Cada CC-e substitui a anterior e deve trazer todas as correções (seção 3).

4.10 Inutilização de numeração

Modalidade	Rota	Processamento	Regras
Por nota recusada	POST .../productinvoices/{id}/disablement	Assíncrono (204)	A nota precisa estar em Error e ter número. Resultado por webhook (disabled_successfully, disabled_error, disabled_failed)
Por faixa	POST .../productinvoices/disablement	Síncrono	Informa ambiente, UF, série, número inicial e final e justificativa. Respostas: 204 (cStat 102 ou faixa já inutilizada, 206/563), 400 (rejeição de dados), 404, 409 (mesma faixa em processamento), 422 (outra rejeição), 503 (SEFAZ indisponível)

A inutilização de faixa é idempotente: repetir o pedido de uma faixa já inutilizada retorna sucesso.

4.11 Finalidades e documentos especiais

• Devolução, complementar, ajuste: emitidas pelo mesmo POST, com a finalidade informada no payload e validações específicas.
• Nota de crédito e nota de débito: emitidas pelo mesmo POST. As notas de crédito e as de débito dos tipos 01, 02, 03, 05 e 08 dispensam o cálculo de impostos. É possível vincular e listar as notas de crédito emitidas contra uma NF-e.
• Eventos fiscais da Reforma Tributária (NT 2025.002): a rota .../authority-events registra os eventos do emitente previstos na NT. Ela é liberada por habilitação da funcionalidade.

---

5. NFC-e

5.1 Pré-requisitos

1. Empresa ativa, com certificado A1 válido.
2. Inscrição estadual ativa do tipo NFC-e, com série, ambiente e CSC (identificador e código) cadastrados.
3. Estratégia de troca de autorizador da IE igual a Manual. Qualquer outra estratégia é recusada com o código de erro 40002: na emissão síncrona, com 400 na própria requisição; na emissão assíncrona, a nota é recusada no processamento e o cliente recebe issued_error.

5.2 Emissão assíncrona

POST /v2/companies/{companyId}/consumerinvoices segue os mesmos passos da NF-e (seções 4.2 a 4.7), com estas particularidades:

• A data e hora de emissão (dhEmi) é a do processamento.
• O XML inclui o QR Code (versão 2), gerado com o CSC da inscrição estadual.
• Tempo esgotado ou indisponibilidade da SEFAZ acionam a contingência offline quando a IE está habilitada (seção 11.3).
• Diante de 217 na consulta pela chave feita após tempo esgotado no envio, a NFC-e alterna consulta e reenvio por até 10 ciclos, antes de encerrar com erro.
• Tipo de evento dos webhooks: consumer_invoice. A ação issued_contingency avisa que a nota foi emitida em contingência offline.

5.3 Emissão síncrona

POST /v2/companies/{companyId}/consumerinvoices/sync devolve o resultado na mesma requisição.

1. A API valida o payload, calcula os impostos (quando pedido) e cria a nota.

2. A API aciona o worker por chamada interna direta. O worker obtém a trava da nota, numera, assina, gera o QR Code e envia a autorização à SEFAZ.

3. O prazo da chamada de autorização é calculado assim:

   prazo SEFAZ = menor valor entre 8 s e (10 s − tempo já decorrido no worker − 2 s de reserva), com mínimo de 1 s.

   Os 2 segundos de reserva existem para, se preciso, emitir a nota em contingência offline dentro do tempo total.

4. Respostas:

Situação	HTTP	status da nota
Autorizada dentro do prazo	200	Issued
Prazo esgotado ou SEFAZ indisponível, IE habilitada para contingência offline	200	IssuedContingency (a nota será transmitida depois)
Rejeitada pela SEFAZ	200	Error, com o cStat e o motivo
Payload ou cadastro inválido	400	Não criada
Cálculo de impostos rejeitado	422 (código 42201)	Error: a nota fica registrada como recusada
Nota ainda em processamento ao fim da chamada (prazo esgotado ou duplicidade com IE não habilitada para offline, trava ocupada ou falha interna)	503	Segue Processing no worker, que conclui o fluxo (por exemplo, consultando a nota pela chave)
SEFAZ indisponível, IE não habilitada para offline	200	Error: a nota é recusada; o pedido pode ser reenviado e a numeração da nota recusada deve ser inutilizada
Serviço de cálculo de impostos indisponível	503	Não criada; o pedido pode ser reenviado

HTTP 503 na emissão síncrona

Um 503 não significa que a nota deixou de existir: ela continua sendo tratada e o resultado chega por webhook. Antes de reenviar, consulte a listagem de notas da empresa. Um novo POST cria uma nova nota, com novo id e novo número.

O prazo de 10 segundos vale para o processamento no worker. O cálculo de impostos e a criação da nota, feitos na API antes dessa etapa, não entram nessa conta.

5.4 QR Code e DANFE NFC-e

• O QR Code usa a versão 2, com o CSC e o seu identificador cadastrados na IE. Na contingência offline, o QR Code traz os dados exigidos para essa modalidade (dia de emissão, valor total e digest value).
• O DANFE NFC-e é gerado na primeira solicitação a GET .../consumerinvoices/{id}/pdf. Na contingência offline, o DANFE traz a indicação de emissão em contingência.

5.5 Cancelamento e inutilização

• Cancelamento (DELETE .../consumerinvoices/{id}?reason=): exige a nota Issued, evento 110111, mesmas regras da NF-e. Uma nota em IssuedContingency ainda não transmitida só pode ser cancelada depois de autorizada.
• Inutilização por nota recusada ou por faixa, como na NF-e. A numeração de NFC-e emitida em contingência não pode ser inutilizada (Ajuste SINIEF 19/16).
• A NFC-e não tem Carta de Correção.

5.6 Diferenças entre NF-e e NFC-e

Aspecto	NF-e	NFC-e
Modo síncrono	Não	Sim (/sync)
Contingência	EPEC (tpEmis 4)	Offline (tpEmis 9)
Estratégias de contingência aceitas na IE	Manual e StateTaxAuthorityStatusUnavailable	Somente Manual
QR Code e CSC	Não se aplica	Obrigatórios
Data de emissão	Pode ser informada no pedido	Sempre a do processamento
CC-e	Sim	Não
Ciclo diante de 217	Até 8 consultas	Até 10 ciclos de consulta e reenvio (após tempo esgotado no envio)
Tipo de evento do webhook	product_invoice	consumer_invoice

---

6. Taxes: cálculo de impostos

6.1 Recursos

Rota	Função
POST /tax-rules/{tenantId}/engine/calculate	Calcula os tributos por item
/{tenantId}/products (POST) e /{tenantId}/products/{productId} (GET, PUT, PATCH)	Cadastro tributário de produtos
GET /tax-codes/operation-code, .../acquisition-purpose, .../issuer-tax-profile, .../recipient-tax-profile	Tabelas de códigos usadas no pedido de cálculo

tenantId é a conta do cliente: se não corresponder à conta da chave de API, a resposta é 403.

6.2 Como o cálculo é feito

O pedido informa o emitente e o destinatário (regime tributário, perfil tributário e UF), o tipo de operação e, por item, o código da operação, a finalidade de aquisição, os perfis tributários, o SKU, o NCM, o CEST, a origem da mercadoria e os valores (quantidade, valor unitário, frete, seguro, desconto e outras despesas).

1. Para cada item, o Taxes procura o produto no cadastro tributário (pelo SKU e pela origem). Produto cadastrado que não está ativo, ou produto não cadastrado e sem NCM, retorna 400.
2. O Taxes verifica se há um cálculo recente reutilizável para o mesmo cenário (seção 6.3).
3. Para os itens sem reuso, consulta o motor de regras tributárias, que devolve CFOP, CST/CSOSN, bases, reduções, alíquotas e valores.
4. Aplica a tributação personalizada do produto (customTax), quando houver (seção 6.4).
5. Devolve, por item: CFOP, CEST, código de benefício fiscal (cBenef), ICMS (inclusive ST, FCP, FCP-ST, diferimento, desoneração e monofásico), ICMS da UF de destino (DIFAL), IPI, PIS e COFINS, além de informações adicionais do produto.

6.3 Reuso de cálculos e reserva em caso de indisponibilidade

• Para cenários elegíveis, o resultado de um cálculo é armazenado por produto cadastrado (ou, sem produto, por NCM) e por cenário (tipo e código da operação, regimes, perfis, origem e UFs), e reaproveitado por até 500 horas. No reuso, as bases e os valores são sempre recalculados com os valores da requisição atual; o que se reaproveita é a regra (CST, alíquotas, reduções).
• O reuso vale para emitentes do Simples Nacional, para contas habilitadas e para o cálculo feito no cadastro de produtos. Ele é restrito a cenários de tributação simples (por exemplo, CST 00, 40, 41 e 60 e CSOSN 102, 400 e 500, sem IPI e com PIS e COFINS sem alíquota) e a perfis de emitente e destinatário específicos. Os demais cenários sempre consultam o motor.
• Se o motor de regras falhar, o Taxes usa, nesta ordem: (a) o resultado armazenado, mesmo vencido, quando o reuso se aplica ao cenário e há resultado para todos os itens; (b) quando o motor está indisponível ou não encontrou a regra, a regra de ICMS CST 40 cadastrada no produto (com CFOP e CST de PIS e COFINS), quando ela cobrir todos os itens. Sem nenhuma das duas, o cálculo falha com o erro original: nada é presumido.

6.4 Tributação personalizada e benefício fiscal

• O cadastro do produto pode trazer regras próprias (customTax) por cenário (operação, regimes e perfis, operação interna ou interestadual). Quando o cenário coincide, essas regras substituem as do motor: CFOP, CST/CSOSN, alíquotas, modalidade de base, redução de base, FCP, PIS e COFINS, código de benefício fiscal e informações adicionais.
• Quando a tributação personalizada define CST 40 ou 41, o motor indica um código de benefício fiscal (cBenef) para o cenário e o produto não informa o seu próprio código (benefitCode), o Taxes responde 422 antes da emissão, evitando a rejeição posterior da SEFAZ (cStat 930/931).

6.5 IBS e CBS

O IBS e a CBS são calculados por um serviço próprio da NFE.io, em chamada separada feita pela NF-e e pela NFC-e para os itens que pedem o cálculo oficial (ibscbs.calculationMode = OfficialService, com o código de classificação tributária). As alíquotas nominais seguem o cronograma de transição da Reforma Tributária do Consumo.

6.6 Cadastro de produtos

• O cadastro é validado de forma assíncrona. Produto sem tributação personalizada é ativado (Active). Produto com tributação personalizada passa por CustomTaxPending enquanto as regras são registradas e conferidas no motor e, ao final, fica Active ou Error.
• Mudanças de situação geram o webhook product_tax, com as ações created_successfully (ativo), custom_rules_requested (tributação personalizada em análise) e creation_failed (erro).

6.7 Respostas de erro

HTTP	Situação
400	Dados inválidos, produto não ativo, produto sem NCM, perfil tributário não suportado, dados recusados pelo motor de regras
403	Conta da rota diferente da conta da chave de API
422	Regra tributária não encontrada para o cenário, erro do motor de regras ou cBenef obrigatório ausente
500	Falha inesperada ou de comunicação com o motor de regras; na rota pública, também a indisponibilidade temporária do motor
503	Motor de regras temporariamente indisponível, na chamada interna feita pela emissão (tratada como falha transitória, seção 8.4)

---

7. Taxes Payment Forms: guias de recolhimento

• Finalidade: gerar a guia de recolhimento do DIFAL interestadual (vICMSUFDest) a partir de uma NF-e autorizada.
• Entrada: o id de uma NF-e emitida pela NFE.io (POST /v1/tax-payment-forms/{accountId}/{companyId}/gnre, com data de pagamento e vencimento) ou o XML nfeProc (.../gnre/xml). O accountId precisa ser o da chave de API.
• Destino: DUA na SEFAZ-ES para operações com destino ao Espírito Santo; lote GNRE no Portal GNRE para as demais UFs. O destino SP não é suportado.
• Validação: a operação precisa ser interestadual e ter DIFAL maior que zero; caso contrário, o pedido é recusado com 400. A guia termina como desnecessária (ErrorNotNeeded) quando o valor total a recolher é zero ou quando o portal informa valor abaixo do mínimo.
• Etapas: Created → Prepared → Transmitted → Generated, com o PDF da guia ao final. Qualquer falha no processamento gera nova tentativa a cada 10 segundos, até 100 vezes.
• Data de pagamento padrão: o próximo dia útil, pelo calendário de feriados de São Paulo. Data de pagamento no passado é recusada com 400.
• Notificação: webhook tax_payment_form, com as ações created_successfully, creation_failed e creation_not_needed.
• O Payment Forms não é chamado pela emissão da NF-e ou da NFC-e: o cliente o aciona depois que a NF-e está autorizada.

---

8. Relação entre NF-e, NFC-e e Taxes

8.1 Como o cliente pede o cálculo

Tributos	Como pedir no payload da NF-e ou da NFC-e
ICMS, ICMS-ST, FCP, DIFAL, IPI, PIS e COFINS	Informar, no item, o bloco taxDetermination (código da operação, perfis tributários do emitente e do destinatário, origem e finalidade de aquisição). Com esse bloco, o CFOP se torna opcional
IBS e CBS	Informar, no item, tax.ibscbs.calculationMode = OfficialService com o código de classificação tributária

Sem esses campos, os valores informados no payload são usados como vieram e o Taxes não é chamado.

8.2 Quando e onde o cálculo acontece

Produto e modo	Onde o Taxes é chamado	Momento
NF-e	Worker	Etapa de criação, antes da numeração e da assinatura
NFC-e assíncrona	Worker	Etapa de criação
NFC-e síncrona	API, dentro da requisição do cliente	Antes da criação da nota

O resultado é aplicado a cada item: CFOP (conferido com o informado pelo cliente, quando houver), CST/CSOSN, bases, alíquotas e valores, cBenef e CEST (quando o cliente não informou). As informações adicionais do produto são acrescentadas às do item.

8.3 Dispensa do cálculo

• As notas de crédito e as de débito dos tipos 01, 02, 03, 05 e 08 não passam pelo motor.
• Emitente contribuinte exclusivamente de IBS/CBS (sem inscrição estadual) não passa pelo cálculo de ICMS, IPI, PIS e COFINS, apenas pelo de IBS e CBS.

8.4 Falhas do cálculo durante a emissão

Resposta do Taxes	NF-e e NFC-e assíncrona	NFC-e síncrona
Sucesso	Segue a emissão	Segue a emissão
Rejeição (4xx), por exemplo, regra não encontrada	Nota recusada (Error, issued_error) com "Error while calculating taxes" e o motivo	422 com o código 42201; a nota fica registrada como recusada
Indisponível (5xx, falha de rede ou de credencial do serviço)	Novas tentativas com espera crescente por até 50 tentativas (cerca de 2 horas e meia). Esgotadas, a nota é recusada	503; nenhuma nota é criada e o pedido pode ser reenviado
IBS/CBS com falha de credencial	Até 5 novas tentativas	503
IBS/CBS com outra falha	Nota recusada	422

Além disso, cada chamada ao Taxes tem até 2 novas tentativas internas, com 5 segundos de intervalo, em falhas de rede, tempo esgotado de requisição (408) e erros de servidor, exceto 503.

---

9. Regras de resiliência

9.1 Novas tentativas por etapa

Cada etapa que termina em falha transitória é reagendada. A primeira execução de cada etapa é imediata; cada repetição espera o degrau seguinte desta escada, e a contagem recomeça quando a nota muda de 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 de NFC-e em contingência offline	A cada 10 min
Demais etapas (criação, numeração, notificação, cancelamento, CC-e, inutilização e transmissão das notas EPEC à SEFAZ de origem)	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.

9.2 Limites

Limite	Valor	Efeito ao ser atingido
Tentativas de negócio por etapa (envio, consulta, cancelamento, CC-e, inutilização)	100	A nota termina com a ação _failed (por exemplo, issued_failed). No envio, isso corresponde a cerca de 16 horas de indisponibilidade contínua
Consultas com 217 (NF-e)	8	issued_error com cStat 217
Ciclos de consulta e reenvio com 217 (NFC-e)	10	issued_error com cStat 217
Tentativas do cálculo de impostos indisponível	50 (cerca de 2 horas e meia)	Nota recusada
Teto técnico de tentativas por etapa	150	A nota é encerrada com erro e o motivo fica registrado nos eventos
Reentregas imediatas de uma mensagem com falha	10	A mensagem vai para a fila de erro, sem alterar a nota, e pode ser reprocessada pela equipe de operação

9.3 Classificação das falhas

Tipo	Exemplos	Tratamento
Transitória	SEFAZ indisponível, sem comunicação, serviço interno indisponível, cálculo de impostos indisponível	Repete a mesma etapa com espera crescente
Inconclusiva	Tempo esgotado, lote recebido sem resultado, duplicidade da própria nota	Consulta pela chave de acesso
Definitiva	Rejeição da SEFAZ, erro de schema, certificado vencido ou recusado, cadastro inativo, rejeição do cálculo de impostos	Encerra a nota com o motivo

9.4 Trava por nota

• Toda etapa é executada sob uma trava distribuída por nota, com validade de 5 minutos.
• Se a trava está ocupada, a etapa é reagendada com espera de 2, 5, 15, 30, 60 e, daí em diante, 120 segundos (com variação aleatória de 20%, para não concentrar as retomadas), sem consumir o contador de tentativas da etapa. Após 30 reagendamentos (cerca de 52 minutos), a nota é encerrada com erro e o motivo fica registrado.
• Na API, operações que também exigem a trava (por exemplo, a geração do DANFE) respondem 409 com o cabeçalho Retry-After: 2 quando a nota está em processamento.

9.5 Tempos máximos

Chamada	Tempo máximo
Web Services da SEFAZ	Até 120 s por chamada
Autorização na NFC-e síncrona	Até 8 s, dentro do limite total de 10 s
Cálculo de impostos (chamada da emissão)	260 s, com até 2 novas tentativas de 5 s
Motor de regras tributárias (chamada do Taxes)	200 s, com até 2 novas tentativas de 5 s e novas tentativas curtas (até 5, em até 5 s) para respostas transitórias

9.6 Webhooks

• A etapa de notificação é repetida enquanto a plataforma de notificações estiver indisponível.
• A entrega ao endpoint do cliente é at-least-once, com reentrega automática em falha de rede ou resposta diferente de 2xx (até 16 tentativas ao longo de cerca de 45 horas) e assinatura HMAC. Veja o catálogo de eventos de webhook.
• Se o cliente não tem webhook cadastrado, a plataforma registra o fato no histórico da nota; o resultado continua disponível na consulta.

9.7 Infraestrutura

• Réplicas das APIs com autoescalonamento horizontal.
• Verificações de vivacidade e de prontidão, que conferem event store, armazenamento, broker, cache e os serviços de cadastro e de certificados.
• Filas de erro por produto para as mensagens que esgotam as reentregas.
• Monitor externo de heartbeat e rastreamento distribuído de ponta a ponta.

---

10. Regras de idempotência

10.1 Garantias da plataforma

Garantia	Como é obtida
Uma única execução por nota e por operação	Controle de admissão: a entrada de uma operação sobre uma nota (cancelamento, CC-e, inutilização, evento, vínculo de nota de crédito) grava um registro condicional por nota e operação; um registro sem atividade por 24 horas é considerado abandonado. Um pedido repetido enquanto a execução está viva é descartado sem nova chamada à SEFAZ e sem novo webhook. Logo após a conclusão, uma janela de 5 minutos impede a readmissão imediata do mesmo trabalho. Na emissão, o controle protege as republicações internas; cada POST do cliente cria uma nota nova (seção 10.2)
Mensagem processada uma vez	O consumidor registra cada mensagem processada e descarta a reentrega dentro de uma janela de 5 minutos
Uma etapa por vez	Trava distribuída por nota (seção 9.4)
Nada é perdido ou sobrescrito	Event Sourcing com controle de concorrência otimista: dois processos não conseguem gravar a mesma versão da nota
Retomada segura	Uma etapa repetida parte do estado gravado: a criação de uma nota que já existe retoma o fluxo; a assinatura não é refeita se o XML já foi assinado
Nenhum reenvio às cegas	Tempo esgotado e duplicidade levam à consulta pela chave de acesso. A SEFAZ garante a unicidade da chave de acesso; o cStat 204 ou 539 com a chave da própria nota leva à consulta pela chave, que recupera o protocolo quando a nota está autorizada
Inutilização de faixa repetida	Retorna sucesso quando a faixa já está inutilizada
Webhook repetido	O cabeçalho X-Hook-Id identifica a notificação para o tratamento idempotente no cliente

10.2 O que é responsabilidade do cliente

• Cada POST de emissão cria uma nova nota, com novo id e, se o número não for informado, novo número. A API não tem chave de idempotência para o pedido de emissão.
• Guarde o id devolvido e use-o como referência para consulta, cancelamento e conciliação.
• Se a requisição de emissão terminar sem resposta (tempo esgotado ou queda de conexão), não reenvie de imediato: consulte a listagem de notas da empresa para verificar se a nota foi criada.
• Se o seu sistema informa o número da nota, garanta a unicidade por série: um número repetido é rejeitado pela SEFAZ com cStat 539.
• Trate os webhooks de forma idempotente e responda 2xx rapidamente.

---

11. Contingência

11.1 Visão geral

Produto	Modalidade usada	tpEmis	Como é acionada
NF-e	EPEC	4	Pelo cliente (estratégia Manual) ou pela NFE.io, por UF (estratégia StateTaxAuthorityStatusUnavailable)
NFC-e	Contingência offline	9	Automaticamente, por tempo esgotado ou indisponibilidade da SEFAZ, e preventivamente por disjuntor por UF, para inscrições estaduais habilitadas

As modalidades SVC-AN e SVC-RS (tpEmis 6 e 7) e as de formulário de segurança (FS-IA e FS-DA) não são utilizadas pela plataforma.

11.2 NF-e: EPEC

Parametrização

A estratégia de contingência é definida por inscrição estadual, no campo processingDetails.switchAuthorizerStrategy do cadastro da IE (API de Empresas, criação ou alteração da inscrição estadual):

Estratégia	Quem decide o início e o fim da contingência	Como
Manual	O cliente	POST /v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer com {"authorizer": "EPEC", "reason": "<justificativa>"} para entrar e {"authorizer": "Normal", "reason": "<justificativa>"} para sair. A resposta traz o autorizador anterior, o novo, a justificativa e a data e hora da troca
StateTaxAuthorityStatusUnavailable	A NFE.io	Ao identificar instabilidade da SEFAZ de uma UF, a equipe de operação da NFE.io ativa a contingência daquela UF. Todas as empresas da UF com essa estratégia passam a emitir em EPEC e voltam ao normal quando a NFE.io encerra a contingência da UF

• Na estratégia Manual, a justificativa informada (reason, de 15 a 256 caracteres para a entrada em EPEC) vira o xJust da nota e a data e hora da troca vira o dhCont.
• Na estratégia StateTaxAuthorityStatusUnavailable, o xJust e o dhCont vêm da ativação feita pela NFE.io para a UF.
• O status da SEFAZ não é sondado automaticamente pela plataforma: a ativação por UF é uma decisão da equipe de operação, com base no monitoramento da SEFAZ.

Regras de aplicação

• A contingência é aplicada na criação da nota. Notas criadas depois da ativação são emitidas em EPEC.
• Notas que já estavam em processamento no momento da ativação não migram para o EPEC: elas seguem tentando a SEFAZ de origem, com as regras de nova tentativa da seção 9, até a SEFAZ voltar.
• A partir de 05/10/2026, a regra de validação 2P10-20 da NT 2014.001 v1.41 veda o EPEC para emitentes do PR e da PB. A plataforma já tem essa verificação implementada, para ativação na data de vigência: a partir dela, a emissão em EPEC desses emitentes é recusada com a indicação da regra.

Fluxo

1. A NF-e é gerada com tpEmis 4, dhCont e xJust.
2. O evento EPEC (110140) é assinado e enviado ao Web Service de Recepção de Eventos do Ambiente Nacional.
3. Com o evento registrado, a nota fica com status IssuedContingency, o XML do evento fica disponível em .../xml-epec e o DANFE é impresso com a marcação de contingência. O cliente recebe product_invoice.issued_successfully com status igual a IssuedContingency.
4. A mercadoria pode circular com o DANFE em EPEC.

Retorno à normalidade

• A contingência termina quando o cliente troca o autorizador para Normal (estratégia Manual) ou quando a NFE.io encerra a contingência da UF (estratégia StateTaxAuthorityStatusUnavailable). As novas notas voltam a ser emitidas com tpEmis 1.
• A NF-e emitida em EPEC precisa ser transmitida à SEFAZ de origem em até 168 horas da emissão (Ajuste SINIEF 07/05), mantendo a mesma chave de acesso. A transmissão posterior usa o envio em lote com consulta de recibo; a nota passa a Issued ao ser autorizada.
• A regularização das notas em EPEC no encerramento da contingência é conduzida pela equipe de operação da NFE.io. O cliente acompanha as notas pendentes pelo status IssuedContingency.

11.3 NFC-e: contingência offline

Parametrização

Parâmetro	Valor em produção	Quem define
Habilitação da contingência offline	Por inscrição estadual	NFE.io, a pedido do cliente
Estratégia de troca de autorizador da IE	Somente Manual	Cliente, no cadastro da IE
Falhas consecutivas (tempo esgotado ou indisponibilidade) para abrir o disjuntor da UF	5	NFE.io
Intervalo de retransmissão	10 minutos	NFE.io
Tempo total da emissão síncrona no worker	10 s	NFE.io
Prazo máximo da chamada de autorização (síncrona)	8 s	NFE.io
Reserva de tempo para a contingência (síncrona)	2 s	NFE.io

A contingência offline é habilitada por inscrição estadual. Uma IE não habilitada não emite em contingência: diante de tempo esgotado, a nota segue o fluxo normal de consulta pela chave de acesso; diante de indisponibilidade da SEFAZ, a emissão assíncrona tenta novamente e a emissão síncrona recusa a nota (Error), que deve ser reenviada pelo cliente.

Modo reativo

1. A autorização normal (tpEmis 1) termina em tempo esgotado ou em indisponibilidade da SEFAZ.
2. A plataforma registra a falha no disjuntor da UF.
3. Para uma IE habilitada, a nota é regenerada com tpEmis 9: nova chave de acesso, dhCont igual à data e hora do momento e xJust igual a "Intermitência na comunicação com a SEFAZ.". O XML é assinado novamente, com o QR Code da contingência. A chave da tentativa normal é guardada como "chave abandonada".
4. A nota passa a IssuedContingency. No modo assíncrono, o cliente recebe consumer_invoice.issued_contingency; no modo síncrono, a resposta é 200 com esse status. O DANFE NFC-e pode ser entregue ao consumidor.
5. Se a regeneração falhar, a nota em contingência não é gravada e a tentativa normal segue as regras da IE não habilitada (parágrafo que antecede o Modo reativo).

Modo proativo (disjuntor por UF)

• Abertura: 5 falhas consecutivas por tempo esgotado ou indisponibilidade na mesma UF, em qualquer inscrição estadual, abrem o disjuntor daquela UF.
• Com o disjuntor aberto: as notas de IEs habilitadas vão direto para tpEmis 9, sem tentar a autorização normal, com dhCont igual à data e hora de abertura do disjuntor. Isso poupa o consumidor da espera por uma SEFAZ que já está falhando.
• Fechamento: qualquer autorização normal bem-sucedida na UF ou qualquer retransmissão de contingência autorizada fecha o disjuntor. Como proteção, o estado do disjuntor expira 24 horas depois da última falha registrada.
• Se o controle do disjuntor estiver inacessível, a plataforma o considera fechado e segue a autorização normal.

Transmissão posterior

1. A primeira transmissão é imediata e as seguintes ocorrem a cada 10 minutos, enviando o XML offline já assinado.
2. Autorizada: a nota passa a Issued, o cliente recebe issued_successfully e o disjuntor da UF é fechado.
3. Duplicidade com a chave abandonada: se a SEFAZ informar que a tentativa normal original (tpEmis 1) foi autorizada, prevalece a nota original: a plataforma reconcilia a nota para a chave tpEmis 1, consulta o protocolo e conclui como Issued.
4. Tempo esgotado ou indisponibilidade: nova transmissão no ciclo seguinte.
5. Rejeição definitiva: a nota termina com Error e issued_error. Pelo Ajuste SINIEF 19/16, cabe ao contribuinte regenerar a nota com o mesmo número e série, sem alterar valores, partes e datas, e obter a autorização.
6. Tentativas esgotadas: ao atingir o limite de 100 tentativas de envio (seção 9.2), a nota termina com issued_failed e exige tratamento.

O prazo legal de transmissão é o final do primeiro dia útil subsequente à emissão (Ajuste SINIEF 19/16). O ciclo de 10 minutos existe para regularizar a nota, assim que a SEFAZ voltar, muito antes desse prazo.

Regras complementares

• O cancelamento só é aceito depois que a nota em contingência é autorizada.
• A numeração de NFC-e emitida em contingência não pode ser inutilizada.
• O EPEC não é utilizado na NFC-e: a estratégia da IE de NFC-e deve ser Manual, e a contingência disponível é a offline.

11.4 Quadro-resumo da parametrização

Parâmetro	Produto	Onde se configura	Valores
processingDetails.switchAuthorizerStrategy	NF-e e NFC-e	Cadastro da inscrição estadual (API de Empresas)	Manual, StateTaxAuthorityStatusUnavailable (somente NF-e)
switch-authorizer (authorizer, reason)	NF-e	POST /v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer	EPEC ou Normal, com justificativa
Contingência por UF	NF-e	Operação NFE.io	Ativa ou inativa, com justificativa e início
Contingência offline por IE	NFC-e	Operação NFE.io, a pedido do cliente	Habilitada ou não
Limiar do disjuntor por UF	NFC-e	Configuração da plataforma	5 falhas consecutivas (tempo esgotado ou indisponibilidade)
Intervalo de retransmissão	NFC-e	Configuração da plataforma	10 minutos
Prazos da emissão síncrona	NFC-e	Configuração da plataforma	10 s total, 8 s para a SEFAZ, 2 s de reserva

---

12. Responsabilidades do cliente

1. Manter o certificado A1 válido e o cadastro da empresa e das inscrições estaduais em dia (série, ambiente, CSC da NFC-e, estratégia de contingência).
2. Guardar o id de cada nota e não reenviar pedidos sem antes consultar (seção 10.2).
3. Garantir a unicidade da numeração por série quando o seu sistema informar o número.
4. Cadastrar e tratar os webhooks de forma idempotente, respondendo 2xx rapidamente.
5. Na estratégia Manual da NF-e, decidir o início e o fim da contingência EPEC e acompanhar, pelo status IssuedContingency, a regularização das notas no prazo legal.
6. Na NFC-e em contingência offline, entregar ao consumidor o DANFE NFC-e com a indicação de contingência e regularizar as notas que terminarem com rejeição.
7. Respeitar os prazos legais de cancelamento, CC-e e inutilização.

13. Referências governamentais

• Portal Nacional da NF-e, Manual de Orientação do Contribuinte (MOC) versão 7.0: https://www.nfe.fazenda.gov.br/portal/listaConteudo.aspx?tipoConteudo=ndIjl+iEFdE%3D
  • Anexo III, Manual de Contingência da NF-e: https://www.confaz.fazenda.gov.br/legislacao/arquivo-manuais/moc7-anexo-iii-manual-contingencia-nf-e.pdf
  • Anexo IV, Manual de Contingência da NFC-e: https://www.confaz.fazenda.gov.br/legislacao/arquivo-manuais/moc7-anexo-iv-manual-contingencia-nfc-e.pdf
• Portal Nacional da NF-e, Notas Técnicas (NT 2025.002, Reforma Tributária do Consumo; 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: 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