Guia de Solução de Problemas e Boas Práticas: Emissão de NF-e/NFC-e (RTC)

Este guia é um recurso completo para desenvolvedores e usuários que estão integrando seus sistemas com nossa API de emissão de NF-e/NFC-e. Ele aborda desde os erros mais comuns até as especificidades da Reforma Tributária (RTC), além de fornecer boas práticas e tabelas de referência para garantir uma integração suave e eficiente.

Se você está começando, recomendamos ler a seção de Boas Práticas de Integração antes de iniciar o desenvolvimento.

info

• Se você está procurando por perguntas e respostas rápidas sobre a Reforma Tributária, visite nossa página de Perguntas e Respostas sobre a Reforma Tributária. Lá, reunimos as dúvidas mais comuns e suas respostas de forma clara e objetiva, resolução de problemas comuns e orientações práticas.
• Se você quer uma visão geral rápida, com um plano de ação por perfil (gestores, fiscal/contábil, desenvolvedores e operação/faturamento), recomendamos começar pela página Visão geral da Reforma Tributária na NFE.io

---

1. Rejeições Comuns (Gerais)

Esta seção cobre os erros mais frequentes que não estão diretamente ligados à Reforma Tributária.

Rejeição 204: Duplicidade de NF-e

• O que significa: Já existe uma nota com o mesmo número, série e CNPJ do emitente na base da SEFAZ.
• Causa Comum: Tentativa de reenvio de uma nota já autorizada ou em processamento, ou erro no controle de numeração sequencial.
• Como Resolver: Verifique o status da nota original. Se já estiver autorizada, não reenvie. Se precisar emitir uma nova nota, incremente o campo number para o próximo valor disponível na sequência da serie.

Rejeição 225: Falha no Schema XML

• O que significa: A estrutura do JSON enviado não corresponde ao layout esperado pela API, resultando em um XML inválido para a SEFAZ.
• Causa Comum: Campos com tipos de dados incorretos (ex: enviar texto onde se espera número), nomes de propriedades errados ou estrutura de objetos aninhados incorreta.
• Como Resolver: Revise o corpo da requisição e compare com a especificação OpenAPI e os exemplos da documentação funcional. Dê atenção especial aos tipos de dados e à hierarquia dos objetos.

Rejeição 210: IE do destinatário inválida

• O que significa: A Inscrição Estadual (stateTaxNumber) informada para o comprador (buyer) não é válida para o estado de destino.
• Causa Comum: Erro de digitação, IE inexistente ou IE de outro estado diferente do endereço do comprador.
• Como Resolver: Confirme a Inscrição Estadual correta do destinatário. Se o destinatário for isento ou não contribuinte, ajuste o campo stateTaxNumberIndicator para Exempt (Isento) ou NonTaxPayer (Não Contribuinte) e não envie o campo stateTaxNumber.

Rejeição 539: Duplicidade de NF-e com diferença na Chave de Acesso

• O que significa: Você tentou emitir uma nota com o mesmo number e serie de uma nota anterior, mas com algum dado diferente (data, valor, cliente), o que gerou uma chave de acesso nova.
• Como Resolver: A numeração é única. Se a nota anterior foi autorizada, você deve usar o próximo número sequencial. Se a nota anterior não serve, ela deve ser cancelada (se estiver no prazo) ou você deve emitir uma nova nota com um novo número.

Rejeição 610: Total da NF-e difere do somatório dos valores que compõem o valor total

• O que significa: O campo totals.icms.invoiceAmount não corresponde à soma dos valores dos itens e demais campos que compõem o total.
• Causa Comum: Erro de cálculo no somatório de items.totalAmount mais frete, seguro, despesas acessórias, impostos e subtração de descontos.
• Como Resolver: Recalcule o valor total da nota. A fórmula básica é: vProd (soma de totalAmount dos itens) - vDesc + vST + vFrete + vSeg + vOutro + vIPI + vIPIDevol. Com a RTC, o campo totalInvoiceAmount também deve ser validado, incluindo os novos impostos.

Rejeição 321: NF-e de devolução de mercadoria não possui documento fiscal referenciado

• O que significa: A nota foi emitida com finalidade de Devolução (purposeType = Devolution), mas não foi informada a chave de acesso da nota original que está sendo devolvida.
• Causa Comum: Esquecimento de preencher o grupo additionalInformation.taxDocumentsReference.
• Como Resolver: Adicione o grupo taxDocumentsReference dentro de additionalInformation, contendo um objeto documentElectronicInvoice com a accessKey da NF-e que originou a devolução.

Rejeição 703: Data-Hora de Emissão posterior ao horário de recebimento

• O que significa: A data/hora de emissão (dhEmi) está no futuro em relação ao relógio da SEFAZ. Na API, o dhEmi vem do campo issuedOn ou, quando ele é omitido, do operationOn.
• Causa: Relógio do servidor adiantado ou configuração incorreta de Fuso Horário (Timezone) em issuedOn/operationOn.
• Solução: Verifique o relógio do servidor e certifique-se de enviar o offset do fuso horário correto (ex: -03:00) no formato da data. A API já recusa com 400 um issuedOn mais de 5 minutos à frente do horário atual, antes de a nota consumir numeração.

Rejeição 520: CFOP de Operação com Exterior e UF destinatária diferente de "EX"

• O que significa: Foi usado um CFOP iniciado em 7 (exportação), mas o endereço do destinatário é no Brasil.
• Solução: Se é uma operação de exportação, o estado (state) do destinatário deve ser "EX". Se for uma venda interna, corrija o CFOP para um código iniciado em 5 (operação estadual) ou 6 (operação interestadual).

Rejeição 778: NCM Inexistente

• O que significa: O código NCM informado no produto não existe mais na tabela oficial do governo.
• Causa: A Receita Federal atualiza periodicamente a tabela TIPI, extinguindo códigos antigos e criando novos.
• Solução: Atualize o cadastro do produto com um NCM válido e vigente. Consulte a tabela TIPI mais recente.

Situação Comum: Confusão de Ambientes (Homologação vs. Produção)

• Sintoma: "A API retornou que a nota foi autorizada, mas não consigo consultá-la no Portal da SEFAZ."
• Causa: A nota foi emitida no ambiente de Homologação (Teste), mas a consulta está sendo feita no portal de Produção.
• Solução: Notas emitidas em homologação não têm validade jurídica e não aparecem na consulta pública principal. Certifique-se de que está consultando no ambiente correto ou mude a configuração da API para Production se desejar emitir uma nota real.

---

2. Rejeições da Reforma Tributária (RTC)

Erros específicos do novo modelo de tributação (IBS e CBS).

Rejeição 1115: IBS/CBS não informado

• O que significa: Para uma operação no novo regime, o grupo IBSCBS não foi informado em um ou mais itens. Pela NT 2025.002-RTC v1.51 (RV UB12-10), a rejeição vale em homologação para emitente CRT 3 em notas emitidas a partir de 01/07/2026; em produção, a regra é de implementação futura.
• Causa Comum: A operação já se enquadra nas regras da RTC, mas o sistema emissor ainda não está enviando o grupo items.tax.IBSCBS.
• Como Resolver: Para cada item da nota, adicione o objeto IBSCBS dentro de tax, preenchendo os campos obrigatórios como situationCode, classCode, basis e os subgrupos state, municipal e cbs. Alternativamente, envie o grupo com calculationMode: "OfficialService", situationCode e classCode (obrigatório nesse modo), e a plataforma calcula os demais campos.

Rejeição 1023: Classificação Tributária IBS/CBS informada inexistente

• O que significa: O código informado em items.tax.IBSCBS.classCode não existe na tabela oficial cClassTrib da SEFAZ.
• Causa Comum: Erro de digitação ou uso de código desatualizado.
• Como Resolver: Consulte o Apêndice B deste guia ou a tabela cClassTrib mais recente no Portal Nacional da NF-e e utilize um código válido.

Rejeição 1024: Classificação Tributária IBS e CBS incompatível com o CST informado

• O que significa: A combinação entre situationCode (CST) e classCode (Classificação Tributária) não é permitida.
• Causa Comum: Um classCode que representa isenção foi combinado com um situationCode de tributação integral, por exemplo.
• Como Resolver: Verifique o Apêndice B deste guia. Ele contém as combinações válidas entre CST e Classificação Tributária. Ajuste um dos dois campos para que a combinação seja válida.

Rejeição 1104: Valor da base de cálculo do IBS e CBS difere do somatório dos valores que a compõem

• O que significa: O valor informado em items.tax.IBSCBS.basis não corresponde à soma dos valores que formam a base de cálculo do item.
• Causa Comum: Erro no cálculo da base. Pela NT 2025.002 (regra UB16-10, ainda de implementação futura na SEFAZ), a base é vProd + vServ + vFrete + vSeg + vOutro + vII − vDesc − vPIS − vCOFINS − vICMS − vICMSUFDest − vFCP − vFCPUFDest − vICMSMono − vISSQN + vIS; o IPI não entra. No modo Manual, a API já recusa com 400 a basis diferente da composição que ela calcula a partir do item: vProd + vFrete + vSeg + vOutro + vII + ICMS-ST + FCP-ST − vDesc − vICMS − vICMSUFDest − vFCPUFDest − vFCP − vICMSMono − vPIS − vCOFINS.
• Como Resolver: Recalcule o campo basis de cada item, garantindo que ele reflita o somatório correto dos valores que compõem a base de cálculo para os novos impostos.

Rejeição 1026: Alíquota do IBS Estadual inválida

• O que significa: A alíquota do IBS estadual (items.tax.IBSCBS.state.rate) não corresponde à alíquota vigente para o período de emissão.
• Causa Comum: Uso de alíquota incorreta. No período de transição, as alíquotas são fixas (ex: 0,1% para 2025/2026).
• Como Resolver: Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota. Consulte a documentação para os valores vigentes.

Rejeição 1036: Alíquota do IBS do Município inválida

• O que significa: A alíquota do IBS municipal (items.tax.IBSCBS.municipal.rate) não corresponde à alíquota vigente para o período de emissão.
• Causa Comum: Uso de alíquota incorreta. No período de transição, as alíquotas são fixas: 0% em 2025 e 2026 e 0,05% em 2027 e 2028 (NT 2025.002, regra UB37-10).
• Como Resolver: Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota.

Rejeição 1001: NF-e com finalidade de débito ou crédito somente para IBS/CBS

⚠️ Limitação da API: no modo Manual (padrão), a API exige icms, pis e cofins no item para calcular a base do IBS/CBS, exceto nos CSTs 410, 810, 930, 800, 620 e 811. Em notas sujeitas à regra B25-80 cujo item usa um CST de tributação regular (por exemplo, débito 04 ou 06, que não restringem o cClassTrib), omitir esses grupos leva a 400 (ICMS is required to compute IBS/CBS basis.). Nesses casos, use calculationMode: OfficialService.

• O que significa: Pela NT 2025.002 (regra B25-80), a Nota de Crédito e a Nota de Débito não podem informar ICMS, ISSQN, IPI, II, PIS, PIS-ST, COFINS, COFINS-ST, ICMS UF Destino nem Imposto Devolvido. A API não retira esses grupos: o que você envia em items[].tax vai para o XML.

  Observação: a finalidade débito/crédito vai no purposeType (DebitInvoice = finNFe 6, CreditInvoice = finNFe 5) e o subtipo em debitType (tpNFDebito) ou creditType (tpNFCredito).

• Quando a regra não se aplica (B25-80, Exceção 1): Notas de Crédito RefusedDeliveryTotalOrNotFound (03) e RefusedDeliveryPartial (06), Nota de Crédito 04 (Redução de valores, ainda não aceita pela API) e Nota de Débito InventoryLoss (07). A Nota de Débito AdvancePayment (06) pode informar PIS, PIS-ST, COFINS e COFINS-ST em NF-e emitida em 2026 (Exceção 2) e IPI (Exceção 3).
• Causa Comum: Nota de Crédito ou de Débito de um tipo sujeito à regra enviada com os grupos do regime antigo, por exemplo copiados da NF-e original.
• Como Resolver: Nos tipos sujeitos à regra, remova icms, ipi, ii, pis, cofins e icmsDestination do objeto tax de todos os itens. Nos tipos da Exceção 1, esses grupos continuam permitidos.

Exemplo Incorreto (Nota de Débito TransferCreditsToCooperatives, tipo 01, sujeita à regra):

{
  "purposeType": "DebitInvoice",
  "debitType": "TransferCreditsToCooperatives",
  "operationType": "Outgoing",
  "operationNature": "Transferência de créditos para cooperativa",
  "additionalInformation": {
    "taxDocumentsReference": [
      { "documentElectronicInvoice": { "accessKey": "35260911222333000181550010000012341000012341" } }
    ]
  },
  "items": [
    {
      "tax": {
        "icms": { "origin": "0", "cst": "90" }, // INCORRETO: grupo do regime antigo na Nota de Débito 01
        "IBSCBS": {
          "situationCode": "800",
          "classCode": "800002",
          "creditTransfer": { "ibsAmount": 150.00, "cbsAmount": 90.00 }
        }
      }
    }
  ]
}

Exemplo Correto:

{
  "purposeType": "DebitInvoice",
  "debitType": "TransferCreditsToCooperatives",
  "operationType": "Outgoing",
  "operationNature": "Transferência de créditos para cooperativa",
  "additionalInformation": {
    "taxDocumentsReference": [
      { "documentElectronicInvoice": { "accessKey": "35260911222333000181550010000012341000012341" } }
    ]
  },
  "items": [
    {
      "tax": {
        "IBSCBS": { // CORRETO: apenas o grupo IBSCBS é informado
          "situationCode": "800",
          "classCode": "800002", // tpNFDebito 01 exige cClassTrib 800002 (NT 2025.002, regra UB14-70)
          "creditTransfer": { "ibsAmount": 150.00, "cbsAmount": 90.00 }
        }
      }
    }
  ]
}

Rejeição 1094: Total da NF-e difere da soma do total dos itens

• O que significa: O valor total da NF-e com IBS/CBS (vNFTot) não corresponde à soma do vItem dos itens (NT 2025.002, regra W60-10, ainda de implementação futura).
• Causa Comum: Erro de cálculo no valor total final da nota, que deve considerar tanto os tributos do regime antigo (se houver) quanto os do novo regime.
• Como Resolver: O vNFTot não faz parte da requisição: a plataforma o preenche. Em 2025 e 2026 ele equivale a totals.icms.invoiceAmount (vNF), porque o vItem ainda não soma IBS, CBS e IS (regra VB01-10, exceção 1). Confira se totals.icms.invoiceAmount e os totais de totals.ibsCbs batem com a soma dos itens. Se a rejeição persistir, fale com o suporte informando o ID da nota.

Rejeição 1116: Grupo gIBSCBSMono não informado

• O que significa: O CST do IBS/CBS exige o grupo de tributação monofásica (indicador ind_gIBSCBSMono = 1, caso do CST 620), mas o item não trouxe items[].tax.IBSCBS.monophase (NT 2025.002, regra UB13-40). A NT marca essa regra como implementação futura em produção e em homologação.
• Causa Comum: Item de combustível ou de outro produto monofásico enviado com CST 620 sem o grupo monophase.
• Como Resolver: Informe monophase com os subgrupos que o cClassTrib exige (standard, withholding, previouslyWithheld ou deferment). O caminho inverso também é recusado: informar monophase com um CST que não o permite gera a rejeição 1151 (regra UB13-39).

Situação Comum: calculationMode: "OfficialService" com campos de valor preenchidos

• O que acontece: Não é uma rejeição da SEFAZ nem da API: o payload é aceito. A API substitui basis, state, municipal, ibsTotalAmount e a alíquota e o valor de cbs pelo retorno do serviço oficial. Subgrupos enviados que o serviço não devolve, como cbs.deferment, monophase ou regularTaxation, podem seguir para o XML e provocar rejeição na SEFAZ.
• Como Resolver: Com calculationMode: "OfficialService", envie no grupo IBSCBS apenas situationCode, classCode e calculationMode.

Exemplo Incorreto:

"IBSCBS": {
  "situationCode": "000",
  "classCode": "000001",
  "calculationMode": "OfficialService",
  "basis": 1500.00,                       // INCORRETO: calculado pelo serviço
  "state": { "rate": 0.1, "amount": 1.50 },
  "cbs": { "rate": 0.9, "amount": 13.50, "deferment": { "rate": 10.0, "amount": 1.35 } } // o diferimento enviado permanece
}

Exemplo Correto:

"IBSCBS": {
  "situationCode": "000",
  "classCode": "000001",
  "calculationMode": "OfficialService" // CORRETO: os valores vêm do serviço oficial
}

---

3. Guia Passo a Passo: Tratando Erros Comuns

3.1. Rejeição 204: Duplicidade de NF-e

A rejeição 204 é uma das mais comuns e indica que a SEFAZ já recebeu uma nota com a mesma chave de acesso ou com o mesmo número e série para o emitente. Siga este fluxo para resolver:

Passo 1: Verificar o Status da Nota Original

Antes de tentar emitir uma nova nota ou incrementar a numeração, descubra o status da nota que causou a duplicidade.

1. Consulte a nota: Consulte o webhook encaminhado pelo nosso sistema ou utilize o endpoint de consulta da API para buscar a nota pelo ID.
2. Analise o Retorno:
   • Autorizada: Se a nota já consta como Issued, o envio anterior teve sucesso. Ação: Atualize o status no seu sistema e capture o XML/DANFE. Não reenvie.
   • Cancelada: A nota existe, mas foi cancelada. Ação: O número não pode ser reutilizado. Emita uma nova nota com um novo número (number).
   • Denegada: A nota existe e foi denegada por irregularidade fiscal. Ação: O número não pode ser reutilizado. Resolva a pendência fiscal e emita uma nova nota com novo número.

Passo 2: Decidir sobre a Numeração

Se a consulta não retornar uma nota autorizada, mas a rejeição 204 persistir ao tentar enviar:

• Cenário A (Correção): Se a nota original foi rejeitada (não autorizada), teoricamente o número poderia ser reutilizado. Se a SEFAZ acusa duplicidade, pode haver uma nota autorizada que seu sistema desconhece. Consulte a chave diretamente no Portal da SEFAZ para ter certeza.
• Cenário B (Nova Emissão): Se você precisa emitir com urgência ou não consegue recuperar o status da anterior, a solução é usar um novo número.
  • Ação: Incremente o campo number para o próximo sequencial disponível e envie a requisição novamente.

Passo 3: Inutilizar a Numeração (Se necessário)

Se você optou por pular a numeração (Cenário B) e emitiu a nota com número seguinte (ex: pulou a 100 e emitiu a 101), criou-se uma quebra na sequência.

1. Identifique o número pulado: No exemplo, o número 100.
2. Confirme o não-uso: Certifique-se de que a nota 100 realmente não foi autorizada, cancelada ou denegada.
3. Solicite a Inutilização: Envie uma requisição de inutilização para a API informando:
   • serie: A série da nota.
   • beginNumber e lastNumber: O número ou faixa a ser inutilizada (ex: 100).
   • reason: Justificativa (ex: "Ocorrência de erro técnico na emissão").

---

4. Procedimentos Fiscais: Cancelamento, Inutilização e Devolução

É comum haver dúvidas sobre qual procedimento adotar para corrigir ou anular uma operação fiscal. Abaixo esclarecemos a diferença entre os três principais mecanismos.

4.1. Cancelamento

• O que é: Ato de invalidar uma NF-e autorizada, tornando-a sem efeito fiscal.
• Quando usar: Quando a operação comercial não se concretizou (ex: desistência da compra) e, crucialmente, a mercadoria ainda não circulou.
• Regras Principais:
  • Deve ser solicitado dentro do prazo legal, geralmente 24 horas após a autorização.
  • A mercadoria não pode ter saído do estabelecimento emitente.
  • O destinatário não pode ter realizado a "Ciência da Emissão".

4.2. Inutilização de Numeração

• O que é: Processo de comunicar à SEFAZ que uma faixa de números de NF-e não foi e não será utilizada.
• Quando usar: Quando há um salto na sequência da numeração das notas. Exemplo: a nota 100 foi emitida e a próxima a ser emitida é a 102, ficando o número 101 vago.
• Regras Principais:
  • A inutilização aplica-se apenas a números que não foram usados em nenhuma NF-e (nem mesmo em nota rejeitada ou denegada).
  • Serve para o Fisco saber que o "buraco" na sequência não é sonegação, mas uma falha técnica ou operacional.

4.3. Nota de Devolução

• O que é: Emissão de uma nova NF-e (com purposeType = Devolution) para anular os efeitos de uma operação anterior.
• Quando usar: Quando a mercadoria circulou e o destinatário a está devolvendo, seja por recusa no recebimento ou devolução após entrega. É a única forma de anular uma operação após a circulação da mercadoria.
• Regras Principais:
  • É uma nota de entrada (operationType = Incoming) para o emitente original.
  • Deve referenciar a chave de acesso da NF-e original que está sendo devolvida.
  • Os impostos são "espelhados" para anular o débito da nota de saída.

---

5. Boas Práticas de Integração e Checklist

Esta seção detalha as recomendações para garantir uma integração mais eficiente, robusta e resiliente com a API.

5.1. Boas Práticas Detalhadas

Controle de Numeração e Série

• O controle da numeração sequencial (number) para cada série (serie) é fundamental para evitar a "Rejeição 204: Duplicidade de NF-e".
• O controle pode ser realizado de duas formas: pelo cliente, enviando os campos serie e number na requisição, ou automaticamente pelo nosso sistema.
• Para o controle automático, o usuário pode definir o valor inicial da série e do número no cadastro da Inscrição Estadual. Se os campos serie e number não forem enviados na requisição, nosso sistema gerenciará a sequência.
• Atenção: Se o controle for realizado pelo nosso sistema, o número de uma nota fiscal que resultar em erro não será reaproveitado. Nesse caso, o cliente deverá gerenciar a quebra de numeração para inutilizar os números pulados posteriormente.
• O sistema cliente deve sempre verificar a ocorrência de pulos na sequência numérica. Caso um número não seja utilizado, é necessário solicitar a sua inutilização para evitar problemas com o Fisco.
• Sempre que for necessário alterar ou iniciar o uso de uma nova série fiscal, é mandatório que o cadastro da Inscrição Estadual do emitente seja previamente atualizado no sistema.

Validação de Dados Pré-Envio

• Reduza chamadas desnecessárias: Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema.
• Valide dados cadastrais e de endereço: Use APIs de consulta para verificar CNPJs, CPFs, Inscrições Estaduais e CEPs, evitando rejeições por dados incorretos.
• Garanta que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM).

Tratamento de Erros e Rejeições

• Utilize os logs detalhados de requisições (JSON enviado) e respostas (JSON recebido) para análise e depuração em caso de erros.
• Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com exponential backoff, não sendo necessário implementar essa lógica no cliente.

Gerenciamento do Ciclo de Vida da NF-e

• Utilize webhooks para receber notificações automáticas sobre o status final da nota ('Emitida', 'Erro'), em vez de realizar consultas periódicas.
• Nosso sistema armazena o XML de cada NF-e autorizada por no mínimo 5 anos. O download do XML e DANFE está disponível a qualquer momento.
• Esteja preparado para a contingência. O modo de emissão em contingência pode ser configurado em nossa plataforma para gerenciamento automático, permitindo que sua operação continue sem interrupções.

Performance e Eficiência

• Mantenha uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, cClassTrib, etc.).
• Envie apenas os campos e grupos necessários para a sua operação, omitindo grupos opcionais não aplicáveis para um payload mais limpo e validação mais rápida.

Segurança

• Trate as chaves de acesso à API (API Keys) e os certificados digitais como informações altamente sensíveis. Não as exponha no código-fonte do lado do cliente (frontend) e armazene-as de forma segura no seu backend.

5.2. Checklist Rápido de Integração

• Validação Pré-Envio: Implementar validações no seu sistema para campos obrigatórios (CFOP, NCM, etc.) antes de enviar a requisição para a API.
• Consulta de Cadastros: Utilizar APIs de consulta para validar dados de CNPJ, CPF, Inscrição Estadual e endereços (via CEP).
• Cache de Tabelas Auxiliares: Manter uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, e as novas tabelas da RTC como cClassTrib).
• Controle de Numeração: Definir a estratégia de controle de numeração sequencial (number) e série (serie) para evitar a Rejeição 204.
• Tratamento de "Pulos" na Numeração: Implementar um processo para solicitar a inutilização de números que não foram utilizados.
• Gerenciamento de Status com Webhooks: Configurar um endpoint (webhook) para receber notificações de status em tempo real (Emitida, Erro, Cancelada).
• Estratégia de Contingência: Configurar o modo de contingência automático na plataforma ou preparar o sistema para gerenciá-lo.
• Payloads Otimizados: Enviar na requisição apenas os campos e grupos necessários para a operação.
• Proteção de Credenciais: Armazenar as chaves de acesso da API e os certificados digitais de forma segura no backend.
• Implementar Fluxos de Correção: Preparar o sistema para os eventos pós-emissão, como Cancelamento, Carta de Correção (CC-e) e emissão de Nota de Devolução.

---

6. Apêndices

6.1. Apêndice A: Mapeamento de Grupos (JSON para XML)

Para desenvolvedores familiarizados com o layout XML da SEFAZ, a tabela abaixo resume o mapeamento dos principais grupos do JSON da API.

Grupo na API (JSON)	Grupo no XML (SEFAZ)	Descrição
(raiz do objeto)	ide	Identificação da NF-e
issuer	emit	Dados do Emitente
buyer	dest	Dados do Destinatário
delivery	entrega	Local de Entrega
withdrawal	retirada	Local de Retirada
items	det	Detalhamento de Produtos e Serviços (Itens)
items.tax	imposto	Tributos incidentes no item
items.tax.icms	ICMS	Grupo de ICMS
items.tax.ipi	IPI	Grupo de IPI
items.tax.pis	PIS	Grupo de PIS
items.tax.cofins	COFINS	Grupo de COFINS
items.tax.IBSCBS	IBSCBS	Grupo de IBS e CBS (RTC)
totals	total	Grupo de Valores Totais
totals.icms	ICMSTot	Totais de ICMS
totals.issqn	ISSQNtot	Totais de ISSQN
totals.ibsCbs	IBSCBSTot	Totais de IBS e CBS (RTC)
transport	transp	Dados do Transporte
billing	cobr	Dados da Cobrança (Fatura e Duplicatas)
payment	pag	Dados do Pagamento
additionalInformation	infAdic	Informações Adicionais
purchaseInformation	compra	Informações de Compra (empenho, pedido)
export	exporta	Informações de Exportação
transactionIntermediate	infIntermed	Informações do Intermediador da Transação

6.2. Apêndice B: Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

A combinação correta do Código de Situação Tributária (situationCode) e do Código de Classificação Tributária (classCode) é essencial para a validação da NF-e no novo regime.

Código CST	Descrição CST	Código Class.	Descrição da Classificação Tributária
000	Tributação integral	000001	Situações tributadas integralmente pelo IBS e CBS.
000	Tributação integral	000002	Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025.
010	Tributação com alíquotas uniformes - operações do FGTS	010001	Operações do FGTS não realizadas pela Caixa Econômica Federal...
011	Tributação com alíquotas uniformes reduzidas em 60%	011001	Planos de assistência funerária...
011	Tributação com alíquotas uniformes reduzidas em 60%	011002	Planos de assistência à saúde...
200	Alíquota zero	200001	Aquisições de máquinas, aparelhos, instrumentos... em zonas de processamento de exportação.
200	Alíquota zero	200003	Vendas de produtos da Cesta Básica Nacional de Alimentos.
200	Alíquota reduzida em 60%	200028	Fornecimento dos serviços de educação...
200	Alíquota reduzida em 30%	200052	Prestação de serviços de profissões intelectuais (advogados, arquitetos, etc.).
400	Isenção	400001	Fornecimento de serviços de transporte público coletivo...
410	Imunidade e não incidência	410002	Transferências entre estabelecimentos do mesmo contribuinte.
410	Imunidade e não incidência	410004	Exportações de bens e serviços.
510	Diferimento	510001	Operações com energia elétrica...
550	Suspensão	550001	Exportações de bens materiais.
620	Tributação monofásica	620001	Tributação monofásica sobre combustíveis.
800	Transferência de crédito	800001	Fusão, cisão ou incorporação.

Nota: A tabela acima é um extrato simplificado. Para a lista completa e detalhada, consulte a documentação oficial no Portal Nacional da NF-e.