Documentação Funcional: API de Emissão de NF-e/NFC-e (v3)

Versão do Documento: 1.0 Data da Última Revisão: 24 de Outubro de 2025

1. Introdução

1.1. Objetivo

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

Este documento serve como um guia funcional completo para a utilização da API de emissão de Nota Fiscal de Produto (NF-e, modelo 55) e Nota Fiscal de Consumidor (NFC-e, modelo 65). O objetivo é detalhar a estrutura do corpo da requisição (payload), a finalidade de cada grupo e propriedade, as regras de negócio, validações e o contexto de preenchimento de cada campo.

Esta documentação é destinada a desenvolvedores, analistas de sistemas e qualquer profissional que necessite integrar sistemas de terceiros com a plataforma de emissão de documentos fiscais.

1.2. Documentos de Referência

A estrutura desta API foi desenvolvida com base nos seguintes documentos oficiais:

Manual de Orientação do Contribuinte (MOC): Principalmente o "ANEXO I - Leiaute e Regra de Validação - NF-e e NFC-e".
Nota Técnica 2025.002 (v1.31): Detalha as adequações para a Reforma Tributária do Consumo (RTC), incluindo os novos tributos IBS, CBS e IS.
Schemas XSD Oficiais: Como tiposBasico_v4.00.xsd e o leiaute da NF-e.

Ao longo do documento, os campos da API são mapeados para seus respectivos campos no XML da SEFAZ (ex: (natOp)), facilitando a associação para quem já tem familiaridade com o leiaute oficial.

1.3. Conceitos Gerais

Ambiente de Emissão: A API opera em dois ambientes distintos:
- Test (Homologação): Para testes de integração, sem validade fiscal.
- Production (Produção): Para emissão de documentos com validade fiscal.
Modelos de Documento:
- NF-e (modelo 55): Nota Fiscal Eletrônica, utilizada para documentar operações de circulação de mercadorias entre pessoas jurídicas ou entre pessoa jurídica e física.
- NFC-e (modelo 65): Nota Fiscal de Consumidor Eletrônica, utilizada em operações de venda presencial ou para entrega a domicílio ao consumidor final.

2. Estrutura Geral da Requisição

A emissão de uma nota fiscal é realizada através de uma requisição POST para o endpoint /v2/companies/:companyId/productinvoices. O corpo da requisição é um objeto JSON que representa a totalidade da nota fiscal. A seguir, detalhamos cada grupo principal deste objeto.

NFC-e (modelo 65)

Para a NFC-e (modelo 65), a estrutura do corpo (payload) e os grupos de tributos da Reforma Tributária (IBS, CBS e IS) são os mesmos descritos neste documento — muda apenas o endpoint de emissão:

POST /v2/companies/{companyId}/consumerinvoices — emissão padrão da NFC-e.
POST /v2/companies/{companyId}/statetaxes/{statetaxId}/consumerinvoices — emissão informando explicitamente a Inscrição Estadual (StateTax) a ser utilizada. Recomendado quando a empresa possui mais de uma IE ativa. A IE informada deve ser do tipo NFCe e estar Active; caso contrário a requisição é rejeitada (400/404).

Ao longo do texto, os campos não aplicáveis à NFC-e (ex.: operationOn, expectedDeliveryOn) e as regras específicas do modelo 65 (ex.: valores permitidos de presenceType, séries de contingência) estão destacados nos respectivos grupos.

2.1. Grupo de Identificação da Nota Fiscal

Este grupo contém as informações que identificam unicamente a nota fiscal e definem suas características principais, como natureza da operação, datas e finalidade.

serie (integer): Série do Documento Fiscal (serie). Número que controla a sequência de numeração.
- Validações: Valor entre 0 e 999. Para NFC-e, as séries 890-899 são de uso exclusivo para emissão em contingência (SCAN).
number (integer): Número do Documento Fiscal (nNF). Número sequencial da nota dentro da série.
- Validações: Não pode ser duplicado para o mesmo emitente, modelo e série.
operationOn (string): Data e Hora de Saída/Entrada (dhSaiEnt). Data e hora em que a mercadoria saiu do estabelecimento (em notas de saída) ou entrou (em notas de entrada). Formato AAAA-MM-DDThh:mm:ssTZD. Não deve ser preenchido para NFC-e (modelo 65).
- Validações: Não pode ser maior que a data de processamento. Para NF-e de entrada, não pode ser menor que a data de emissão.
expectedDeliveryOn (string): Data da Previsão de Entrega (dPrevEntrega). Data prevista para a entrega do bem. Formato AAAA-MM-DD. Não aplicável à NFC-e.
- Validações: Não pode ser anterior à data de emissão, nem superior a 3 meses da data de saída. Não é permitida para finalidades de ajuste (finNFe=3) ou complementar (finNFe=2), nem para fretes por conta do destinatário (modFrete=1, FOB) ou sem frete (modFrete=9).
operationNature (string): Descrição da Natureza da Operação (natOp). Texto que descreve a operação (ex: "Venda de mercadoria", "Remessa para conserto"). Este campo deve ser consistente com o CFOP utilizado nos itens.
- Validações: Mínimo de 2 caracteres.
operationType (enum): Tipo do Documento Fiscal (tpNF). Define se a nota é de Incoming (Entrada) ou Outgoing (Saída).
- Validações: Uma nota de devolução (purposeType = Devolution) deve ser do tipo Incoming. Uma nota de crédito (finNFe=5) deve ser do tipo Incoming.
destination (enum): Identificador de Local de Destino (idDest). Indica se a operação é Internal_Operation (dentro do mesmo estado), Interstate_Operation (entre estados) ou International_Operation (com o exterior).
- Validações: Se a UF do destinatário for igual à do emitente, deve ser Internal_Operation. Se for diferente, Interstate_Operation. Se o país for diferente de Brasil, International_Operation.
consumptionCityCode (integer): Código do Município de Ocorrência do Fato Gerador (cMunFG). Código IBGE do município onde o imposto (ICMS) é devido. Geralmente, é o município do emitente, mas pode variar em casos específicos.
- Validações: Obrigatório se a UF do local de entrega for diferente da UF do emitente (para NF-e) ou se a venda for presencial fora do estabelecimento (para NFC-e).
ibsConsumptionCityCode (integer): Município do Fato Gerador do IBS/CBS (cMunFGIBS). Código IBGE do município onde ocorre o fato gerador dos novos tributos (IBS/CBS). Relevante para operações presenciais fora do estabelecimento, onde o consumo ocorre em município diferente.
- Validações: Obrigatório apenas se presenceType for 5 (Operação presencial, fora do estabelecimento) e o endereço do destinatário ou de entrega não for informado.
printType (enum): Formato de Impressão do DANFE (tpImp). Define o layout de impressão do Documento Auxiliar da Nota Fiscal Eletrônica.
purposeType (enum): Finalidade da Emissão (finNFe). Indica a finalidade da nota: Normal, Complement (complementar), Adjustment (ajuste) ou Devolution (devolução).
- Validações: Uma nota complementar (finNFe=2), de ajuste (finNFe=3), de devolução (finNFe=4) ou de crédito (finNFe=5) deve, obrigatoriamente, referenciar um documento fiscal.
debitType (enum): Tipo de Nota de Débito (tpNFDebito). Usado em notas de débito (finNFe=6) para cenários específicos da Reforma Tributária, como finesAndInterest (multas e juros).
- Validações: Só pode ser informado se a finalidade da nota (purposeType) for Debit (finalidade 6).
creditType (enum): Tipo de Nota de Crédito (tpNFCredito). Usado em notas de crédito (finNFe=5) para cenários como valueReduction (redução de valor) ou apropriação de créditos.
- Validações: Só pode ser informado se a finalidade da nota (purposeType) for Credit (finalidade 5).
consumerType (enum): Indicador de Operação com Consumidor Final (indFinal).
- FinalConsumer: A venda é para um consumidor final.
- Normal: A venda não é para consumidor final.
- Regra de Padrão: Se este campo não for informado, o valor será definido com base no federalTaxNumber do comprador (buyer): "Normal" para CNPJ e "FinalConsumer" para CPF/NIF.
presenceType (enum): Indicador de Presença do Comprador (indPres). Indica como a operação comercial ocorreu (ex: Presence para presencial, Internet para não presencial via internet). Essencial para diferenciar vendas em loja física de e-commerce.
- Validações: Para NFC-e, os valores permitidos são Presence (presencial) ou Delivery (entrega a domicílio).
contingencyOn (string) e contingencyJustification (string): Entrada em Contingência (dhCont, xJust). Usados para emissão em modo de contingência, quando o ambiente da SEFAZ está indisponível.
- Validações: A justificativa deve ter no mínimo 15 caracteres.
governmentPurchase (object): Grupo de Compras Governamentais (gCompraGov). Detalha operações de venda para órgãos públicos, que podem ter regras de tributação específicas.

2.2. Grupo do Comprador (`buyer`)

Contém todas as informações do destinatário da mercadoria. Grupo obrigatório para NF-e (modelo 55).

name (string): Nome ou Razão Social (xNome). (Obrigatório)
federalTaxNumber (integer): CNPJ ou CPF (CNPJ/CPF). (Obrigatório) Para operações com o exterior, pode ser o NIF (Número de Identificação Fiscal).
- Validações: Para operações internas ou interestaduais, deve ser um CNPJ ou CPF válido. Se for informado CNPJ, a Inscrição Estadual (stateTaxNumber) pode ser obrigatória dependendo da UF.
tradeName (string): Nome Fantasia (xFant).
stateTaxNumber (string): Inscrição Estadual (IE).
- Validações: Se stateTaxNumberIndicator for TaxPayer, a IE deve ser informada e válida para a UF do destinatário. Se for NonTaxPayer, não deve ser informada.
stateTaxNumberIndicator (enum): Indicador da IE do Destinatário (indIEDest). Define a relação do destinatário com o ICMS. Este campo é crucial para o cálculo correto de impostos como o DIFAL.
- TaxPayer: Contribuinte de ICMS.
- Exempt: Contribuinte isento de Inscrição Estadual.
- NonTaxPayer: Não Contribuinte de ICMS.
address (object): Endereço do Destinatário (enderDest). (Obrigatório) Objeto contendo os dados completos do endereço.
email (string): Email (email). (Obrigatório)
- Validações: O código do município (city.code) deve corresponder à UF (state).

2.3. Grupos de Locais de Entrega e Retirada

delivery (object): Identificação do Local de Entrega (entrega). Usado apenas quando o local de entrega é diferente do endereço do destinatário. Se for o mesmo, este grupo não deve ser preenchido.
- Validações: O CNPJ/CPF do local de entrega não pode ser igual ao do emitente.
withdrawal (object): Identificação do Local de Retirada (retirada). Usado apenas quando a mercadoria é retirada em local diferente do endereço do emitente.

2.4. Grupo de Itens (`items`)

Este é um array de objetos, onde cada objeto representa um produto ou serviço da nota. É a seção mais importante e complexa do documento fiscal.

2.4.1. Propriedades do Item

code (string): Código do Produto ou Serviço (cProd). (Obrigatório) Código interno do produto no sistema do emitente.
codeGTIN (string): GTIN (cEAN). Código de barras do produto, se houver.
description (string): Descrição do Produto ou Serviço (xProd). (Obrigatório)
- Validações: Não pode ser preenchido com termos genéricos como "DIVERSOS".
ncm (string): Código NCM (NCM). (Obrigatório) Nomenclatura Comum do Mercosul. Campo fundamental para a correta tributação.
- Validações: Deve ser um código NCM válido, existente na tabela oficial. Para alguns produtos, o NCM completo de 8 dígitos é obrigatório.
cest (string): Código CEST (CEST). Código Especificador da Substituição Tributária. Obrigatório para produtos listados em convênios de ICMS-ST.
- Validações: Obrigatório se o produto estiver sujeito à substituição tributária, conforme convênios ICMS.
cfop (integer): Código Fiscal de Operações e Prestações (CFOP). (Obrigatório se não enviado taxDetermination) Código numérico que define a natureza da operação do item (venda, remessa, devolução, etc.) e sua tributação.
- Validações: Deve ser um código válido. O primeiro dígito deve ser compatível com o tipo de operação (ex: 5 ou 6 para saídas, 1 ou 2 para entradas).
quantity (number): Quantidade Comercial (qCom). (Obrigatório)
unit (string): Unidade Comercial (uCom) (ex: "UN", "CX", "KG"). (Obrigatório)
unitAmount (number): Valor Unitário de Comercialização (vUnCom). (Obrigatório)
totalAmount (number): Valor Total Bruto do Produto (vProd). (Obrigatório) Resultado de quantity * unitAmount.
- Validações: O valor deve ser o resultado da multiplicação da quantidade pelo valor unitário, com uma pequena tolerância para arredondamento.
freightAmount, insuranceAmount, othersAmount (number): Valores de frete, seguro e outras despesas acessórias que são rateados e compõem o valor total do item.
totalIndicator (boolean): Indicador de Totalização (indTot). Indica se o valor do item (vProd) entra no cálculo do valor total da NF-e.
- Validações: Para NF-e de ajuste (purposeType = Adjustment), este campo deve ser false.
numberOrderBuy (string): Número do Pedido de Compra (xPed).
unitTax (string): Unidade Tributável (uTrib). (Obrigatório)

2.4.2. Grupo de Tributos do Item (`tax`)

Dentro de cada item, o objeto tax detalha todos os tributos incidentes sobre o produto ou serviço. Obrigatório somente se não for enviado o grupo taxDetermination.

totalTax (number): Valor Aproximado dos Tributos (vTotTrib). (Obrigatório) Valor estimado de tributos conforme Lei da Transparência.
Tributos do Regime Antigo:
- icms (object): Grupo do ICMS. (Obrigatório) Contém a tributação do ICMS, com campos como origin, cst, baseTax, rate e amount. A estrutura interna varia conforme o CST.
  - Validações: Apenas um dos grupos de tributação do ICMS (ICMS00, ICMS10, ICMS20, etc.) pode ser preenchido, de acordo com o CST informado.
- ipi (object): Grupo do IPI. Detalha a tributação do Imposto sobre Produtos Industrializados.
- pis (object): Grupo do PIS. (Obrigatório)
- cofins (object): Grupo do COFINS. (Obrigatório)
Tributos da Reforma Tributária (RTC):
- IS (object): Imposto Seletivo. Preenchido para produtos sujeitos a este imposto (ex: cigarros, bebidas açucaradas). Contém situationCode, basis, rate e amount.
  - Validações: O uso deste grupo é obrigatório se o cClassTribIS do item indicar incidência do Imposto Seletivo. O valor do imposto (amount) deve ser o resultado da base de cálculo (basis) pela alíquota (rate).
- IBSCBS (object): Grupo do IBS e CBS. Grupo central da RTC, obrigatório para operações no novo regime a partir de 05/01/2026.
  - situationCode (string): Código de Situação Tributária para IBS/CBS.
  - classCode (string): Código de Classificação Tributária, que define o regime específico do item (ex: tributação geral, isenção, alíquota reduzida).
    - Validações: O classCode deve ser um código válido da tabela oficial e compatível com o situationCode informado.
  - basis (number): Base de cálculo unificada.
  - calculationMode (enum): Modo de cálculo do imposto. Permite escolher entre o preenchimento manual (Manual, valor padrão) ou o cálculo automático via serviço oficial (OfficialService). Quando OfficialService é usado, apenas situationCode e classCode são necessários, e os demais campos de tributo são preenchidos pelo serviço.
  - state (object): Detalha o cálculo do IBS Estadual (rate, amount, deferment, reduction).
  - municipal (object): Detalha o cálculo do IBS Municipal.
  - cbs (object): Detalha o cálculo da CBS.
    - Validações: Os valores de amount em cada subgrupo devem ser calculados corretamente com base na basis e nas respectivas alíquotas e benefícios.
    - Validações (RTC): Para notas de débito ou crédito (finNFe = 5 ou 6), é vedado informar os grupos de tributos do regime antigo (ICMS, IPI, PIS, COFINS, etc.).
  - Subgrupos opcionais como monophase (tributação monofásica), operationalPresumedCredit (crédito presumido), governmentPurchase (compras governamentais), etc.
taxDetermination (object): Grupo para Determinação Automática de Impostos. Se preenchido, o sistema pode calcular automaticamente os tributos do grupo IBSCBS com base em informações como operationCode, issuerTaxProfile e buyerTaxProfile.

2.5. Grupo de Transporte (`transport`)

Contém as informações sobre o transporte da mercadoria.

freightModality (enum): Modalidade do Frete (modFrete). Define o responsável pelo frete (ex: ByIssuer - CIF, ByReceiver - FOB, Free - Sem frete).
- Validações: Se a modalidade for Free (sem frete), os grupos de transportador, veículo e volumes não devem ser preenchidos.
transportGroup (object): Dados do Transportador (transporta). Informações como name, federalTaxNumber, stateTaxNumber e address.
transportVehicle (object): Dados do Veículo (veicTransp). Placa (plate) e UF do veículo.
reboque (object): Dados do Reboque.
volume (object): Dados dos Volumes Transportados (vol). Informações como quantidade (volumeQuantity), espécie (species), peso líquido (netWeight) e peso bruto (grossWeight).

2.6. Grupo de Pagamento (`payment`)

Array de objetos que detalha as formas de pagamento.

paymentDetail (array): Detalhes do pagamento.
- method (enum): Forma de Pagamento (tPag) (ex: Cash, CreditCard, InstantPayment para PIX).
- amount (number): Valor do Pagamento (vPag).
  - Validações: A soma dos valores de todos os pagamentos deve ser igual ao valor total da nota.
- paymentType (enum): Indicador da Forma de Pagamento (indPag): InCash (à vista) ou Term (a prazo).
- card (object): Se o pagamento for com cartão, este grupo contém dados da transação, como a bandeira (flag), o CNPJ da credenciadora e o número de autorização.
  - Validações: Obrigatório se o método de pagamento for CreditCard ou DebitCard.
payBack (number): Valor do Troco (vTroco).

2.7. Grupo de Cobrança (`billing`)

Usado para detalhar a cobrança comercial da operação.

bill (object): Fatura (fat). Contém número (number), valor original (originalAmount), desconto (discountAmount) e valor líquido (netAmount).
duplicates (array): Duplicatas (dup). Array com as parcelas da fatura, cada uma com número (number), data de vencimento (expirationOn) e valor (amount).

2.8. Grupo de Totais (`totals`)

Resume os valores totais da nota fiscal. A maioria desses campos é calculada pelo sistema com base nos itens, mas é importante que o sistema de origem também os calcule para validação.

icms (object): Totais do ICMS (ICMSTot). Contém a somatória de bases de cálculo, valores de ICMS, ICMS-ST, valor total dos produtos, frete, seguro, desconto, e o valor total da nota (invoiceAmount) segundo o regime antigo.
- Validações: Cada campo deste grupo deve corresponder à somatória do campo respectivo de todos os itens da nota.
issqn (object): Totais do ISSQN (ISSQNtot). Somatórias relativas ao Imposto Sobre Serviços.
withheldTaxes (object): Retenções de Tributos (retTrib). Valores retidos de PIS, COFINS, CSLL, IRRF e Previdência Social.
isTotals (object): Totais do Imposto Seletivo (ISTot). Somatória do valor do Imposto Seletivo de todos os itens.
- Validações: O valor total (amount) deve ser a soma dos valores de IS.amount de todos os itens.
ibsCbsTotals (object): Totais de IBS e CBS (IBSCBSTot). Consolida os totais de base de cálculo, valores de IBS (estadual e municipal), CBS, diferimentos, devoluções, etc.
- Validações: Os valores neste grupo devem ser a somatória dos valores correspondentes do grupo IBSCBS de cada item.
totalInvoiceAmount (number): Valor Total da NF-e com RTC (vNFTot). Representa o valor total final da nota, considerando a soma dos produtos e todos os impostos, incluindo os novos (IBS, CBS, IS).
- Validações: Deve ser a soma do totals.icms.invoiceAmount com os totais de isTotals e ibsCbsTotals.

2.9. Grupo de Informações Adicionais (`additionalInformation`)

Campos de texto livre e referências para informações complementares.

fisco (string): Informações Adicionais de Interesse do Fisco (infAdFisco).
taxpayer (string): Informações Complementares de Interesse do Contribuinte (infCpl).
xmlAuthorized (array): Autorizados a Baixar o XML (autXML). Lista de CNPJs ou CPFs de terceiros (ex: contador) autorizados a acessar o XML do documento.
- Validações: Devem ser CNPJs ou CPFs válidos. Máximo de 10 autorizações.
taxDocumentsReference (array): Documentos Fiscais Referenciados (NFref). Usado para referenciar chaves de acesso de outras notas (ex: em uma devolução). Cada item pode conter um de três tipos:
- documentElectronicInvoice: NF-e/NFC-e referenciada (chave de acesso de 44 dígitos em accessKey).
- documentInvoiceReference: Nota fiscal modelo 1/1A referenciada (campos state, yearMonth, federalTaxNumber, model, series, number).
- taxCouponInformation: Cupom fiscal referenciado (campos modelDocumentFiscal, orderECF, orderCountOperation).
- Validações: A chave de acesso referenciada deve ser válida e existir na base de dados da SEFAZ.
advancePayment (array): Notas de Antecipação de Pagamento (gPagAntecipado). Usado para abater parcelas de antecipação conforme art. 10 § 4º. Cada item contém apenas accessKey.
taxpayerComments (array): Observações Fiscais (obsCont). Lista de pares field/text para observações livres do contribuinte.
referencedProcess (array): Processos Referenciados (procRef). Para informar números de processos judiciais ou administrativos que amparam a operação. Cada item contém:
- identifierConcessory (string): Identificador do ato concessório.
- identifierOrigin (integer): Indicador da origem do processo (1=SEFAZ, 2=Justiça Federal, 3=Justiça Estadual, 9=Outros).
- concessionActType (integer): Tipo do ato concessório.

2.10. Grupo do Emitente (`issuer`) — Resposta

Observação: Diferente da maioria dos grupos, issuer não é enviado na requisição de emissão. Ele é determinado automaticamente pelo cadastro da empresa (companyId na URL) e populado pela API na resposta. Este grupo é detalhado aqui para referência ao consumir os endpoints de consulta.

Identifica o emitente da NF-e (emit no XML).

name (string): Nome ou Razão Social (xNome).
federalTaxNumber (integer): CNPJ do emitente.
tradeName (string): Nome Fantasia (xFant).
regionalTaxNumber (integer): Inscrição Estadual (IE) na SEFAZ da UF do emitente.
regionalSTTaxNumber (integer): IE do Substituto Tributário (IEST) quando o emitente é substituto tributário.
municipalTaxNumber (string): Inscrição Municipal (IM/CCM).
companyRegistryNumber (integer): Número de Inscrição na Junta Comercial (nIRE).
address (AddressResource): Endereço do emitente (enderEmit).
taxRegime (enum TaxRegime): Código de Regime Tributário (CRT). Ver §11.3.1.
specialTaxRegime (enum SpecialTaxRegime): Regime especial de tributação (indRegTrib). Ver §11.3.2.
legalNature (enum LegalNature): Natureza jurídica da empresa. Ver §11.10.
economicActivities (array): Lista de CNAEs da empresa, cada item com type (Main/Secondary) e code (código numérico).
openningDate (string): Data de abertura da empresa (dIniAtiv).
stStateTaxNumber (string): IE do Substituto Tributário (IEST) — também exposta no payload de requisição via issuerTaxSubstitute quando relevante para a operação específica.

2.11. Grupo de Compras (`purchaseInformation`)

Detalha referências comerciais da operação. Aplicável principalmente a vendas para órgãos públicos.

commitmentNote (string): Nota de Empenho (xNEmp). Identificação do empenho quando se trata de compra pública. Mín. 1, máx. 22 caracteres.
purchaseOrder (string): Pedido (xPed). Identificação do pedido de compra. Mín. 1, máx. 60 caracteres.
contractNumber (string): Contrato (xCont). Identificação do contrato. Mín. 1, máx. 60 caracteres.

Diferença para additionalInformation.order / contract: Os campos em additionalInformation são genéricos de texto livre. O grupo purchaseInformation é estruturado e mapeado diretamente ao grupo compra do XML — preferível em compras governamentais.

2.12. Grupo de Exportação (`export`)

Aplicável apenas a operações com destination = InternationalOperation.

state (enum StateCode): Sigla da UF de embarque ou de transposição de fronteira.
office (string): Local de Embarque (xLocExporta). Descrição do local físico de saída do bem (ex: "Porto de Santos", "Aeroporto de Guarulhos").
local (string): Local de Despacho (xLocDespacho). Local de despacho aduaneiro.

2.13. Grupo do Intermediador da Transação (`transactionIntermediate`)

Aplicável quando a venda é feita por meio de marketplace, plataforma de delivery ou agenciador.

federalTaxNumber (integer): CNPJ do Intermediador (CNPJ). CNPJ da plataforma intermediadora.
identifier (string): Identificador no Intermediador (idCadIntTran). ID interno do vendedor/loja na plataforma intermediadora.

Quando preencher: Sempre que a transação foi originada/processada por um terceiro (Marketplace), mesmo que o pagamento tenha sido feito diretamente ao emitente. A SEFAZ usa este grupo para conciliação fiscal entre emitente e plataforma.

2.14. Grupo de Contingência (`contingencyOn` / `contingencyJustification`)

Quando a SEFAZ está indisponível (timeout, erro 5xx, status do serviço degradado), a NF-e pode ser emitida em modo contingência:

contingencyOn (string, ISO 8601): Data e hora de entrada em contingência (dhCont).
contingencyJustification (string): Justificativa textual da entrada em contingência (xJust). Mínimo 15 caracteres, máximo 1.000.

A nota é processada localmente e posteriormente sincronizada com a SEFAZ. O status da NF-e fica em IssuedContingency até a sincronização ser bem-sucedida.

Recomendação: Configure o emissor para gerenciar contingência automaticamente via cadastro da Inscrição Estadual em vez de preencher manualmente — ver §9.4.

2.15. Subgrupos Especiais de Item

Além dos campos básicos descritos em §2.4.1 e §2.4.2, cada item pode conter subgrupos específicos para tipos de produto/operação:

2.15.1. `vehicleDetail` — Veículos Novos

Aplicável quando o item é um veículo 0 km. Detalhamento completo em §6.22 (todos os campos J02–J26 do leiaute oficial).

"vehicleDetail": {
  "operationType": 1,
  "chassis": "9BWZZZ377VT004251",
  "colorCode": "001",
  "colorDescription": "PRETO",
  "enginePower": "150",
  "engineDisplacement": "1998",
  "netWeight": "1250.000",
  "grossWeight": "1500.000",
  "serialNumber": "123456789",
  "fuelType": "16",
  "engineNumber": "MOTOR123456789",
  "maximumTractionCapacity": "0.0000",
  "wheelBase": "2649",
  "modelYear": 2026,
  "manufactureYear": 2025,
  "paintType": "S",
  "vehicleType": "06",
  "vehicleSpecies": 1,
  "vinCondition": "N",
  "vehicleCondition": 1,
  "brandModelCode": "025104",
  "denatranColorCode": "11",
  "seatingCapacity": 5,
  "restrictionType": 0
}

operationType: Tipo da operação (0-Outros, 1-Venda concessionária, 2-Faturamento direto, 3-Venda direta a grandes consumidores).
chassis: Chassi/VIN do veículo (17 caracteres alfanuméricos).
colorCode / colorDescription: Código (montadora) e descrição da cor.
enginePower / engineDisplacement: Potência (CV) e cilindrada (CC).
netWeight / grossWeight: Pesos líquido (pesoL) e bruto (pesoB).
serialNumber: Número de série (nSerie).
fuelType: Tipo de combustível pela Tabela RENAVAM (ex: 16 Álcool/Gasolina flex).
engineNumber: Número do motor (nMotor).
maximumTractionCapacity / wheelBase: CMT em toneladas e distância entre eixos (mm).
modelYear / manufactureYear: Ano modelo e ano de fabricação.
paintType / vehicleType / vehicleSpecies: Tipo de pintura, tipo (RENAVAM) e espécie do veículo.
vinCondition: Condição do chassi (R-Remarcado, N-Normal).
vehicleCondition: Condição do veículo (1-Acabado, 2-Inacabado, 3-Semi-acabado).
brandModelCode / denatranColorCode: Código marca/modelo e código da cor DENATRAN.
seatingCapacity: Lotação máxima (passageiros + motorista).
restrictionType: Restrição (0-Não há, 1-Alienação Fiduciária, 2-Arrendamento, 3-Reserva de Domínio, 4-Penhor, 9-Outras).

2.15.2. `fuelDetail` — Combustíveis

Aplicável quando o item é um combustível sujeito a controle ANP.

"fuelDetail": {
  "codeANP": "210203001",
  "percentageNG": 50.0,
  "descriptionANP": "GLP",
  "percentageGLP": 40.0,
  "percentageNGn": 30.0,
  "percentageGNi": 20.0,
  "startingAmount": 100.0,
  "codif": "CODIF-123",
  "amountTemp": 10.0,
  "stateBuyer": "RJ",
  "cide": { "bc": 10.0, "rate": 5.0, "cideAmount": 0.5 },
  "pump": { "spoutNumber": 1, "number": 1, "tankNumber": 1, "beginningAmount": 1000.0, "endAmount": 1010.0, "percentageBio": 10.0 },
  "fuelOrigin": { "indImport": 1, "cUFOrig": 35, "pOrig": 10.0 }
}

codeANP: Código de produto da ANP (cProdANP).
descriptionANP: Descrição do produto conforme ANP (descANP).
percentageNG, percentageGLP, percentageNGn, percentageGNi: Percentuais de mistura para o produto GLP (cProdANP=210203001).
startingAmount: Valor de partida (vPart).
codif: Código de autorização do CODIF.
amountTemp: Quantidade faturada à temperatura ambiente (qTemp).
stateBuyer: Sigla da UF de consumo (UFCons).
cide: Grupo CIDE (Contribuição de Intervenção no Domínio Econômico) com bc (BC), rate (alíquota), cideAmount (valor).
pump: Dados da bomba de combustível para postos:
- spoutNumber/number/tankNumber: Identificação física (bico, bomba, tanque).
- beginningAmount/endAmount: Encerrante inicial e final do abastecimento.
- percentageBio: Percentual do índice de mistura do Biodiesel B100 no Óleo Diesel.
fuelOrigin: Origem do combustível:
- indImport: Indicador de importação.
- cUFOrig: Código da UF de origem.
- pOrig: Percentual originário para a UF.

Mútua exclusão: vehicleDetail, fuelDetail (e medicineDetail quando aplicável) são mutuamente exclusivos. Se mais de um for enviado, prevalece a ordem: medicamento > veículo > combustível.

2.15.3. `presumedCredit` — Crédito Presumido por Item (regime ICMS)

Crédito presumido específico do regime antigo, conforme exigência da UF (NT 2019.001).

"presumedCredit": {
  "code": "BENEF-001",   // Código do benefício na UF (cCredPresumido). Tamanho 8 ou 10
  "rate": 4.0,           // Percentual (pCredPresumido) — usar fração, ex: 0.04 = 4%
  "amount": 80.08        // Valor (vCredPresumido)
}

Diferente do operationalPresumedCredit do IBSCBS: este é específico de ICMS e usa códigos de benefício da UF. O operationalPresumedCredit é da Reforma Tributária (RTC).

2.15.4. `importDeclarations` — Declarações de Importação (DI)

Array de DIs vinculadas ao item. Cada DI contém:

code: Número do Documento de Importação (nDI).
registeredOn: Data de registro da DI/DSI/DA (dDI).
customsClearanceName: Local de desembaraço (xLocDesemb).
customsClearanceState (enum StateCode): UF do desembaraço (UFDesemb).
customsClearancedOn: Data do desembaraço (dDesemb).
additions: Array de adições com code (nº), manufacturer (cód. fabricante), amount (vDescDI), drawback (nº ato concessório).
exporter: Código do exportador (cExportador).
internationalTransport (enum InternationalTransportType): Via de transporte da DI. Ver §11.6.3.
intermediation (enum IntermediationType): Forma de intermediação. Ver §11.6.2.
acquirerFederalTaxNumber: CNPJ/CPF do adquirente/encomendante.
stateThird: UF do adquirente/encomendante.

2.15.5. `exportDetails` — Detalhamento de Exportação por Item

Vínculo do item a um Registro de Exportação (RE) ou DEC (Declaração de Exportação Comum).

drawback: Número do ato concessório (nDraw).
hintInformation:
- registryId: Número do RE (nRE).
- accessKey: Chave da NF-e recebida para exportação (chNFe).
- quantity: Quantidade efetivamente exportada (qExport).

2.15.6. `referencedDFe` — Documento Fiscal Eletrônico Referenciado

Referência item-a-item a um item específico de outro DF-e (uso típico: nota de devolução referenciando a NF-e original).

accessKey (string, 44 chars): Chave de acesso do DF-e referenciado.
itemNumber (integer 1–999): Número do item no DF-e original (nItem).

2.15.7. `taxDetermination` — Cálculo Automático de Impostos

Quando preenchido, substitui o preenchimento manual de tax e dispara o cálculo automático via Tax Engine interno:

operationCode (integer): Código interno para determinação da natureza de operação.
issuerTaxProfile (string): Perfil fiscal do vendedor (origem) — ex: industry, retail, wholesale.
buyerTaxProfile (string): Perfil fiscal do comprador (destino) — ex: final_consumer_non_icms_contributor, industry_icms_contributor.
origin (string): Origem da mercadoria (mesmo enum do tax.icms.origin).
acquisitionPurpose (string): Finalidade da aquisição.

Ordem de precedência:

Se taxDetermination preenchido → cálculo automático.

Caso contrário, tax.IBSCBS com calculationMode = OfficialService → cálculo automático apenas do IBS/CBS.

Caso contrário, todos os campos de tax devem ser preenchidos manualmente.

3. Apêndice A: Mapeamento de Grupos Principais

A tabela abaixo resume o mapeamento dos principais grupos do JSON da API para os grupos do XML da SEFAZ.

Grupo na API (JSON)	Grupo no XML da 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.IS`	`IS`	Grupo do Imposto Seletivo (RTC)
`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.isTotals`	`ISTot`	Totais do Imposto Seletivo (RTC)
`totals.ibsCbsTotals`	`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

4. Apêndice B: Estrutura Detalhada dos Novos Grupos da Reforma Tributária

4.1. `items.tax.IS`

"IS": {
  "situationCode": "101",
  "classificationCode": "IS0001",
  "basis": 2002.0,
  "rate": 5.0,
  "amount": 100.1
}

Finalidade: Declarar o Imposto Seletivo.
situationCode: Define a tributação do IS para o item.
classificationCode: Classifica o item em uma das categorias do Imposto Seletivo.
basis: Valor sobre o qual a alíquota (rate) será aplicada.
amount: Valor final do imposto (basis * rate / 100).

4.2. `items.tax.IBSCBS`

"IBSCBS": {
  "situationCode": "101",
  "classCode": "RT0001",
  "basis": 2002.0,
  "state": {
    "rate": 10.0,
    "deferment": { "rate": 1.0, "amount": 20.02 },
    "reduction": { "rateReduction": 0.5, "effectiveRate": 9.5 },
    "amount": 190.19
  },
  "municipal": {
    "rate": 5.0,
    "amount": 96.1
  },
  "cbs": {
    "rate": 12.0,
    "amount": 216.22
  },
  "ibsTotalAmount": 286.29
}

Finalidade: Declarar os novos tributos sobre o consumo, IBS e CBS.
situationCode e classCode: Chaves para determinar o regime de tributação do item.
basis: Base de cálculo comum para os tributos.
state e municipal: Detalham o IBS, que é um imposto dual. Contêm a alíquota nominal (rate), o valor final (amount) e podem conter subgrupos para benefícios como diferimento (deferment) ou redução de alíquota (reduction).
cbs: Detalha a CBS, que é um tributo federal único.
ibsTotalAmount: Soma dos valores de state.amount e municipal.amount.

4.3. `totals.isTotals` e `totals.ibsCbsTotals`

"totals": {
  // ... outros totais
  "isTotals": {
    "amount": 100.1
  },
  "ibsCbsTotals": {
    "basis": 2002.0,
    "ibs": {
      "state": { "defermentAmount": 20.02, "amount": 190.19 },
      "municipal": { "amount": 96.1 },
      "totalAmount": 286.29
    },
    "cbs": {
      "amount": 216.22
    }
  },
  "totalInvoiceAmount": 2675.04
}

Finalidade: Consolidar os valores totais dos novos tributos para toda a nota fiscal.
isTotals.amount: Soma do campo amount de todos os grupos IS dos itens.
ibsCbsTotals: Agrega as bases de cálculo e os valores de IBS e CBS de todos os itens, separando os totais por esfera (estadual, municipal, federal) e por tipo de benefício (diferimento, devolução).
totalInvoiceAmount: O novo valor total da nota, calculado como: totals.icms.invoiceAmount (valor antigo) + totals.isTotals.amount + totals.ibsCbsTotals.ibs.totalAmount + totals.ibsCbsTotals.cbs.amount.

4.4. Subgrupos de Benefícios Fiscais do IBS/CBS

Tanto state quanto municipal (IBS) e cbs (CBS) compartilham a mesma estrutura interna para representar benefícios fiscais que reduzem o tributo devido. Cada um pode conter, opcionalmente, três subgrupos:

4.4.1. `deferment` — Diferimento (`gDif`)

Representa diferimento tributário: o tributo é apurado mas seu pagamento é postergado para uma etapa posterior da cadeia.

"deferment": {
  "rate": 1.0,        // Percentual do diferimento (pDif)
  "amount": 20.02     // Valor diferido (vICMSDif)
}

rate: Percentual da alíquota que está sendo diferido.
amount: Valor monetário do diferimento, calculado como (basis * rate.diferida) / 100.
Quando aparece no XML: Apenas quando o cClassTrib indica diferimento (CST 510).

4.4.2. `reduction` — Redução de Alíquota (`gRed`)

Representa redução de alíquota (não da base de cálculo). A alíquota efetiva aplicada é menor que a nominal.

"reduction": {
  "rateReduction": 40.0,    // Percentual da redução (pRedAliq)
  "effectiveRate": 0.06     // Alíquota efetiva pós-redução (pAliqEfet)
}

rateReduction: Percentual da redução aplicada sobre a alíquota nominal (ex: 40 significa redução de 40%).
effectiveRate: Alíquota efetiva resultante após a redução (rate * (1 - rateReduction/100)).
Invariante crítico: O campo rate no nível superior (state.rate, municipal.rate, cbs.rate) deve ser sempre a alíquota nominal, nunca a efetiva. A alíquota efetiva fica exclusivamente em reduction.effectiveRate. Esta separação é garantida pela API.

4.4.3. `returnedAmount` — Devolução de Tributos (`gDevTrib`)

Representa devolução de tributos ao adquirente em casos como devolução de mercadoria ou ajuste contábil.

"returnedAmount": {
  "amount": 10.0    // Valor a devolver (vDevTrib)
}

4.5. Subgrupos Especiais do IBS/CBS

Além dos benefícios fiscais por jurisdição, o IBSCBS aceita subgrupos especiais para regimes tributários específicos.

4.5.1. `monophase` — Tributação Monofásica (`gMonofasicoIBSCBS`)

Aplicável a combustíveis e outros produtos sujeitos à tributação monofásica (alíquota ad rem por unidade tributável, art. 172-180 LC 214/2025).

"monophase": {
  "standart": {
    "quantityBasis": 10.0,
    "ibsAdRemRate": 15.0,
    "cbsAdRemRate": 25.0,
    "ibsAmount": 150.0,
    "cbsAmount": 250.0
  },
  "withholding": { /* tributação monofásica sujeita à retenção */ },
  "previouslyWithheld": { /* monofásica retida anteriormente */ },
  "deferment": { /* diferimento monofásico (biocombustíveis) */ },
  "ibsAmount": 140.0,    // Total IBS monofásico do item (vTotIBSMonoItem)
  "cbsAmount": 255.0     // Total CBS monofásico do item (vTotCBSMonoItem)
}

standart (gMonofasicoPadrao): Tributação monofásica aplicada na cadeia em uma única etapa.
- quantityBasis: Quantidade base tributada (qBCMono).
- ibsAdRemRate / cbsAdRemRate: Alíquota ad rem em R$ por unidade tributável.
- ibsAmount / cbsAmount: quantityBasis * adRemRate.
withholding (gMonofasicoRetido): Tributação monofásica em que o emitente é responsável pela retenção.
previouslyWithheld (gMonofasicoRetidoAnt): Tributação monofásica que foi retida em etapa anterior da cadeia (informativo, sem efeito no valor final).
deferment (gMonofasicoDif): Diferimento aplicável especificamente a biocombustíveis na monofásica.
ibsAmount / cbsAmount: Totais consolidados do item para o IBS e CBS monofásicos.

4.5.2. `operationalPresumedCredit` — Crédito Presumido Operacional (`gCredPresOper`)

Crédito presumido sobre operações específicas (produtor rural não contribuinte, reciclagem de PF, bens usados de PF para revenda, etc.).

"operationalPresumedCredit": {
  "basis": 1000.0,
  "classificationCode": "RuralProducerNonTaxpayer",
  "ibs": {
    "rate": 10.0,
    "amount": 100.0,
    "suspensiveConditionAmount": 10.0
  },
  "cbs": {
    "rate": 5.0,
    "amount": 50.0,
    "suspensiveConditionAmount": 5.0
  }
}

basis: Base de cálculo do crédito presumido (vBC).
classificationCode: Tipo do crédito presumido (ver enum PresumedCreditClassificationCode no Apêndice H).
ibs / cbs:
- rate: Percentual do crédito presumido (pCredPres).
- amount: Valor do crédito presumido (vCredPres).
- suspensiveConditionAmount: Parcela do crédito sujeita a condição suspensiva (vCredPresCondSus). Só se concretiza quando a condição for cumprida.

4.5.3. `creditTransfer` — Transferência de Crédito (`gTransfCred`)

Aplicável em fusão, cisão, incorporação ou transferência entre cooperativas e associados (CST 800).

"creditTransfer": {
  "ibsAmount": 50.0,    // IBS a transferir (vIBS)
  "cbsAmount": 30.0     // CBS a transferir (vCBS)
}

4.5.4. `creditReversal` — Estorno de Crédito (`gEstornoCred`)

Aplicável quando há vedação ou obrigatoriedade de estorno de crédito conforme o cClassTrib (campo ind_gEstornoCred da tabela).

"creditReversal": {
  "ibsReversalAmount": 2.0,    // IBS a estornar (vIBSEstCred)
  "cbsReversalAmount": 1.0     // CBS a estornar (vCBSEstCred)
}

4.5.5. `governmentPurchase` — Composição em Compras Governamentais (`gCompraGov`)

Detalha como IBS e CBS são compostos em vendas para órgãos da administração pública direta, autarquias e fundações (art. 472/370 LC 214/2025). Aplicável quando o grupo governmentPurchase (raiz) está preenchido.

"governmentPurchase": {
  "stateRate": 8.0,       "stateAmount": 160.16,
  "municipalRate": 4.0,   "municipalAmount": 80.08,
  "cbsRate": 10.0,        "cbsAmount": 200.2
}

Repete a estrutura rate/amount para as três jurisdições (UF, Município, CBS), mas considerando a redução pRedutor aplicada à compra governamental.

4.5.6. `regularTaxation` — Tributação Regular Hipotética

Quando há condição resolutória ou suspensiva (ex: alíquota zero condicionada a destinação específica), declara-se aqui qual seria a tributação caso a condição não se cumpra. Importante para apuração e fiscalização.

"regularTaxation": {
  "situationCode": "101",
  "classCode": "RT0001",
  "stateEffectiveRate": 10.0,    "amount": 200.2,
  "municipalEffectiveRate": 5.0, "municipalAmount": 100.1,
  "cbsEffectiveRate": 12.0,      "cbsAmount": 240.24
}

situationCode (CSTReg): CST que aplicaria se a condição resolutória/suspensiva caísse.
classCode (cClassTribReg): Classificação tributária regular.
Pares stateEffectiveRate/amount, municipalEffectiveRate/municipalAmount, cbsEffectiveRate/cbsAmount: Alíquota efetiva e valor que seriam apurados.

4.5.7. `zfmPresumedCredit` — Crédito Presumido ZFM (`gCredPresIBSZFM`)

Crédito presumido específico para fornecimentos a partir da Zona Franca de Manaus (art. 450 LC 214/2025).

"zfmPresumedCredit": {
  "classificationCode": "IntermediateGoods",   // tpCredPresIBSZFM
  "amount": 123.45                              // vCredPresIBSZFM
}

classificationCode: Determina o percentual aplicável (55%, 75%, 90,25%, 100% — ver enum IbsZfmPresumedCreditClassification no Apêndice H).
amount: Valor do crédito presumido. Obrigatório quando creditType = 02.

4.6. `donationIndicator` e `competenceAdjustment`

4.6.1. `donationIndicator` — Indicador de Doação (`indDoacao`)

Quando a operação é uma doação (ex: doação a entidade beneficente, transferência sem contraprestação), informe este campo no IBSCBS para que a apuração trate corretamente débitos/estornos. Valores: "0" (não doação) / "1" (doação). Campo de 1 caractere; informar apenas quando aplicável.

4.6.2. `competenceAdjustment` — Ajuste de Competência (`gAjusteCompet`)

Reabre uma competência fiscal anterior para incluir um ajuste de IBS/CBS:

"competenceAdjustment": {
  "assessmentPeriod": "2025-09",   // AAAA-MM (competApur)
  "ibsAmount": 5.0,                 // vIBS do ajuste
  "cbsAmount": 3.0                  // vCBS do ajuste
}

Aplicável tipicamente em notas com purposeType = Credit ou Debit.

5. Considerações Finais

A estrutura da API foi projetada para ser flexível e acomodar tanto o sistema tributário atual quanto o novo modelo da Reforma Tributária. Durante o período de transição, os grupos de tributos antigos (ICMS, PIS, COFINS) e novos (IS, IBSCBS) coexistirão.

É fundamental que os sistemas emissores consultem as tabelas oficiais (CST, cClassTrib, etc.) e sigam as regras de validação descritas no Manual do Contribuinte e nas Notas Técnicas para garantir a correta emissão e autorização dos documentos fiscais.

Para mais detalhes sobre regras de validação específicas, consulte a documentação da SEFAZ e as Notas Técnicas vigentes.

6. Apêndice C: Detalhamento dos Objetos de Recurso

Este apêndice detalha a estrutura dos principais objetos e sub-objetos referenciados no corpo da requisição da API.

6.1. AddressResource

Define a estrutura de um endereço, utilizada nos grupos buyer, delivery, withdrawal e transportGroup.

street (string): Logradouro do Endereço (xLgr). (Obrigatório)
number (string): Número do Endereço (nro). (Obrigatório)
additionalInformation (string): Complemento do Endereço (xCpl).
district (string): Bairro do Endereço (xBairro). (Obrigatório)
city (CityResource): Objeto contendo o código (code) e nome (name) do município. (Obrigatório)
state (string): Sigla da UF. (Obrigatório)
postalCode (string): Código de Endereçamento Postal (CEP).
country (string): Código ou nome do país. (Obrigatório)
phone (string): Telefone.

6.2. BuyerResource

Contém as informações cadastrais do destinatário da nota.

name (string): Nome ou Razão Social (xNome). (Obrigatório)
federalTaxNumber (integer): CNPJ ou CPF. (Obrigatório)
tradeName (string): Nome Fantasia (xFant).
stateTaxNumber (string): Inscrição Estadual (IE).
stateTaxNumberIndicator (enum): Indicador da IE do Destinatário (TaxPayer, Exempt, NonTaxPayer).
address (AddressResource): Objeto com os dados de endereço do destinatário. (Obrigatório)
email (string): E-mail do destinatário. (Obrigatório)
type (enum): Tipo de pessoa (NaturalPerson, LegalEntity).
taxRegime (enum): Regime de tributação.

6.3. DeliveryInformationResource

Define o local de entrega, se e somente se for diferente do endereço do destinatário.

federalTaxNumber (integer): CNPJ ou CPF do local de entrega.
name (string): Nome ou Razão Social.
stateTaxNumber (string): Inscrição Estadual.
address (AddressResource): Objeto com os dados completos do endereço de entrega.

6.4. WithdrawalInformationResource

Define o local de retirada, se e somente se for diferente do endereço do emitente.

federalTaxNumber (integer): CNPJ ou CPF do local de retirada.
name (string): Nome ou Razão Social.
address (AddressResource): Objeto com os dados completos do endereço de retirada.

6.5. GovernmentPurchaseResource

Detalha uma operação de compra por um órgão governamental. (gCompraGov)

entityType (enum): Tipo de ente governamental (Union, State, Municipality).
rateReduction (number): Percentual de redução de alíquota. (pRedutor)
operationType (enum): Tipo de operação com o governo (Supply, Payment, etc.). (tpOperGov)

6.6. TransportInformationResource

Agrupa todas as informações relacionadas ao transporte da mercadoria.

freightModality (enum): Modalidade do frete (ByIssuer, ByReceiver, etc.). (modFrete)
transportGroup (TransportGroupResource): Dados do transportador. (transporta)
transportVehicle (TransportVehicleResource): Dados do veículo principal. (veicTransp)
reboque (ReboqueResource): Dados do veículo reboque. (reboque)
volume (VolumeResource): Informações sobre os volumes transportados. (vol)
transpRate (TransportRateResource): Dados da retenção de ICMS do transporte. (retTransp)
sealNumber (string): Número dos lacres.

6.6.1. TransportGroupResource

name (string): Nome/Razão Social do transportador.
federalTaxNumber (integer): CNPJ/CPF do transportador.
stateTaxNumber (string): Inscrição Estadual do transportador.
address (AddressResource): Endereço completo do transportador.

6.6.2. TransportVehicleResource

plate (string): Placa do veículo. (placa)
state (string): UF de registro do veículo.
rntc (string): Registro Nacional de Transportadores Rodoviários de Carga.

6.6.3. ReboqueResource

plate (string): Placa do reboque.
state (string): UF de registro do reboque.
rntc (string): RNTRC do reboque.

6.6.4. VolumeResource

volumeQuantity (integer): Quantidade de volumes. (qVol)
species (string): Espécie dos volumes. (esp)
brand (string): Marca dos volumes. (marca)
netWeight (number): Peso líquido total (em Kg). (pesoL)
grossWeight (number): Peso bruto total (em Kg). (pesoB)

6.7. PaymentResource e PaymentDetailResource

Estrutura para detalhar as formas e os valores de pagamento da operação.

PaymentResource:
- paymentDetail (array[PaymentDetailResource]): Lista dos detalhes de pagamento.
- payBack (number): Valor do troco.
PaymentDetailResource:
- method (enum): Forma de pagamento (Cash, CreditCard, InstantPayment).
- amount (number): Valor do pagamento.
- paymentType (enum): Indicador da forma de pagamento (InCash, Term).
- card (CardResource): Detalhes da transação com cartão.

6.7.1. CardResource

federalTaxNumber (string): CNPJ da credenciadora do cartão.
flag (enum): Bandeira do cartão (ex: Visa, Mastercard). (tBand)
authorization (string): Número de autorização da operação com cartões, PIX, boletos e outros pagamentos eletrônicos. (cAut)
integrationPaymentType (enum): Tipo de integração (Integrated, NotIntegrated). (tpIntegra)

6.8. BillingResource

Contém os dados de cobrança comercial, como fatura e duplicatas.

bill (BillResource): Dados da fatura.
duplicates (array[DuplicateResource]): Lista de duplicatas (parcelas).

6.8.1. BillResource

number (string): Número da fatura. (nFat)
originalAmount (number): Valor original da fatura. (vOrig)
discountAmount (number): Valor do desconto. (vDesc)
netAmount (number): Valor líquido da fatura. (vLiq)

6.8.2. DuplicateResource

number (string): Número da duplicata. (nDup)
expirationOn (string): Data de vencimento. (dVenc)
amount (number): Valor da duplicata. (vDup)

6.9. AdditionalInformationResource

Agrupa informações complementares, como observações para o fisco, documentos referenciados e processos.

fisco (string): Informações para o Fisco.
taxpayer (string): Informações para o contribuinte.
xmlAuthorized (array[integer]): Lista de CNPJs/CPFs autorizados a baixar o XML.
taxDocumentsReference (array[TaxDocumentsReferenceResource]): Documentos fiscais referenciados.
referencedProcess (array[ReferencedProcessResource]): Processos judiciais/administrativos referenciados.

6.9.1. TaxDocumentsReferenceResource

documentElectronicInvoice (object): Contém a chave de acesso (accessKey) de uma NF-e/NFC-e referenciada.
documentInvoiceReference (object): Contém dados de uma nota fiscal modelo 1/1A referenciada.
taxCouponInformation (object): Contém dados de um cupom fiscal referenciado.

6.9.2. ReferencedProcessResource

identifierConcessory (string): Identificador do processo.
identifierOrigin (integer): Indicador da origem do processo (ex: SEFAZ, Justiça Federal).

6.10. InvoiceItemResource

Detalha um item da nota fiscal.

code (string): Código do produto.
description (string): Descrição do produto.
ncm (string): Código NCM.
cfop (integer): Código CFOP.
quantity (number): Quantidade.
unit (string): Unidade de medida.
unitAmount (number): Valor unitário.
totalAmount (number): Valor total bruto.
tax (InvoiceItemTaxResource): Objeto com todos os tributos do item.
vehicleDetail (VehicleDetailResource): Detalhes específicos para itens que representam veículos novos. Consulte a seção 6.22. VehicleDetailResource para o detalhamento completo de todos os campos.
fuelDetail (FuelResource): Detalhes se o item for um combustível.
importDeclarations (array[ImportDeclarationResource]): Detalhes de importação.
taxDetermination (TaxDeterminationResource): Grupo para cálculo automático de impostos.

6.11. InvoiceItemTaxResource

Agrupa todos os tributos incidentes sobre um item.

totalTax (number): Valor aproximado total de tributos (Lei da Transparência).
icms (IcmsTaxResource): Tributação do ICMS.
ipi (IPITaxResource): Tributação do IPI.
pis (PISTaxResource): Tributação do PIS.
cofins (CofinsTaxResource): Tributação do COFINS.
IS (ISTaxResource): Tributação do Imposto Seletivo.
IBSCBS (IBSCBSTaxResource): Tributação do IBS e CBS.

6.11.1. IcmsTaxResource

origin (string): Origem da mercadoria.
cst (string): Código de Situação Tributária do ICMS.
baseTax (number): Base de cálculo do ICMS.
rate (number): Alíquota do ICMS (%).
amount (number): Valor do ICMS.
...outros campos para ST, redução, diferimento, etc.

6.11.2. IPITaxResource

cst (string): Código de Situação Tributária do IPI.
base (number): Base de cálculo do IPI.
rate (number): Alíquota do IPI (%).
amount (number): Valor do IPI.

6.11.3. PISTaxResource e CofinsTaxResource

cst (string): Código de Situação Tributária do PIS/COFINS.
baseTax (number): Base de cálculo.
rate (number): Alíquota (%).
amount (number): Valor do tributo.

6.12. ISTaxResource

Detalha a tributação do Imposto Seletivo para um item.

situationCode (string): Código de Situação Tributária do IS.
classificationCode (string): Código de Classificação Tributária do IS.
basis (number): Base de cálculo.
rate (number): Alíquota (%).
amount (number): Valor do imposto.

6.13. IBSCBSTaxResource

Detalha a tributação do IBS e da CBS para um item, conforme a Reforma Tributária.

situationCode (string): Código de Situação Tributária do IBS/CBS.
classCode (string): Código de Classificação Tributária.
basis (number): Base de cálculo.
state (IBSStateTaxResource): Detalhes do IBS Estadual.
municipal (IBSMunicipalTaxResource): Detalhes do IBS Municipal.
cbs (CBSTaxResource): Detalhes da CBS.
monophase (MonophaseIBSCBSTaxResource): Detalhes para tributação monofásica.
operationalPresumedCredit (OperationalPresumedCreditResource): Detalhes de crédito presumido.

6.13.1. IBSStateTaxResource e IBSMunicipalTaxResource

rate (number): Alíquota do IBS (%).
amount (number): Valor do IBS.
deferment (object): Contém rate e amount do diferimento.
reduction (object): Contém rateReduction e effectiveRate da redução.

6.13.2. CBSTaxResource

rate (number): Alíquota da CBS (%).
amount (number): Valor da CBS.
deferment (object): Contém rate e amount do diferimento.
reduction (object): Contém rateReduction e effectiveRate da redução.

6.14. Total (Schema de Totais)

Agrupa os valores totais consolidados de toda a nota fiscal.

icms (ICMSTotal): Totais do ICMS.
issqn (ISSQNTotal): Totais do ISSQN.
withheldTaxes (TotalsWithholdings): Totais de tributos retidos.
isTotals (ISTotalsResource): Totais do Imposto Seletivo.
ibsCbsTotals (IBSCBSTotalsResource): Totais de IBS e CBS.
totalInvoiceAmount (number): Valor total final da NF-e.

6.14.1. ICMSTotal

baseTax (number): Somatório da base de cálculo do ICMS.
icmsAmount (number): Somatório do valor do ICMS.
stCalculationBasisAmount (number): Somatório da base de cálculo do ICMS-ST.
stAmount (number): Somatório do valor do ICMS-ST.
productAmount (number): Somatório do valor dos produtos.
invoiceAmount (number): Valor total da nota (regime antigo).

6.14.2. TotalsWithholdings

pisAmount (number): Valor retido de PIS.
cofinsAmount (number): Valor retido de COFINS.
...outros campos para CSLL, IRRF, etc.

6.15. ISTotalsResource

Consolida o valor total do Imposto Seletivo da nota.

amount (number): Soma do valor do Imposto Seletivo de todos os itens.

6.16. IBSCBSTotalsResource

basis (number): Somatório da base de cálculo do IBS/CBS.
ibs (IBSTotalsResource): Objeto com os totais do IBS.
cbs (CBSTotalsResource): Objeto com os totais da CBS.
monophase (MonophaseTotalsResource): Objeto com os totais da tributação monofásica.

6.17. IBSTotalsResource

Agrega os totais do IBS.

state (IBSStateTotalsResource): Totais do IBS estadual.
municipal (IBSMunicipalTotalsResource): Totais do IBS municipal.
totalAmount (number): Valor total do IBS.
presumedCreditAmount (number): Valor total do crédito presumido.

6.18. CBSTotalsResource

Agrega os totais da CBS.

defermentAmount (number): Valor total do diferimento.
returnedAmount (number): Valor total de devolução.
amount (number): Valor total da CBS.
presumedCreditAmount (number): Valor total do crédito presumido.

6.19. PurchaseInformationResource

Agrupa informações de compra.

commitmentNote (string): Nota de Empenho.
purchaseOrder (string): Pedido de compra.
contractNumber (string): Número do contrato.

6.20. ExportResource

Contém informações sobre a exportação de mercadorias.

state (string): Sigla da UF de embarque.
office (string): Local de embarque.
local (string): Local de despacho.

6.21. IntermediateResource

Contém informações do intermediador da transação (marketplace, plataforma de delivery, etc.).

federalTaxNumber (integer): CNPJ do intermediador.
identifier (string): Identificador cadastrado no intermediador.

6.22. VehicleDetailResource

Este grupo contém as informações específicas para itens que representam veículos novos na nota fiscal. Corresponde ao grupo veicProd (campos J01 a J26) do leiaute oficial da NF-e, conforme definido no XSD leiauteNFe_v4.00.xsd.

Quando utilizar: Este grupo deve ser preenchido exclusivamente quando o item da nota fiscal é um veículo novo (0 km). É obrigatório para operações de venda realizadas por concessionárias, montadoras e revendedores de veículos novos. Cada item da nota pode conter apenas um grupo de produto específico (vehicleDetail, fuelDetail ou medicineDetail). Se mais de um for preenchido, apenas o primeiro encontrado será considerado, seguindo a ordem de precedência: medicamento, veículo, combustível.

Campos:

operationType (integer): Tipo da Operação (tpOp — campo J02). Define o contexto comercial da venda do veículo. Este campo indica como a operação de venda está sendo realizada e influencia regras de faturamento e tributação.
- 0 = Outros (operações que não se enquadram nas demais categorias)
- 1 = Venda concessionária (venda realizada por uma concessionária autorizada)
- 2 = Faturamento direto para consumidor final (venda direta da montadora ao consumidor)
- 3 = Venda direta para grandes consumidores (ex: frotistas, governo, locadoras)
- Validações: Opcional no contrato da API. Quando informado, deve ser um dos valores acima (0, 1, 2 ou 3). A obrigatoriedade do preenchimento pode depender da regra de negócio aplicável à operação.
chassis (string): Chassi do Veículo — VIN (chassi — campo J03). O número de identificação do veículo (Vehicle Identification Number), gravado no chassi. É o identificador único e universal do veículo, utilizado para rastreamento, registro e documentação em todo o mundo.
- Validações: Obrigatório. Deve conter exatamente 17 caracteres alfanuméricos (letras maiúsculas de A a Z e dígitos de 0 a 9). Padrão: [A-Z0-9]{17}.
- Exemplo: 9BWZZZ377VT004251
colorCode (string): Código da Cor do Veículo (cCor — campo J04). Código interno utilizado pela montadora para identificar a cor do veículo. Cada fabricante possui sua própria tabela de códigos de cores.
- Validações: Obrigatório. Máximo de 4 caracteres.
- Exemplo: A1B2
colorDescription (string): Descrição da Cor (xCor — campo J05). Nome por extenso da cor do veículo, em linguagem compreensível. Deve corresponder ao código informado em colorCode.
- Validações: Obrigatório. Máximo de 40 caracteres.
- Exemplo: Prata Lunar Metálico
enginePower (string): Potência do Motor (pot — campo J06). Potência máxima do motor do veículo, expressa em cavalos-vapor (CV). Este valor consta no certificado de registro do veículo.
- Validações: Obrigatório. Máximo de 4 caracteres.
- Exemplo: 150 (equivale a 150 CV)
engineDisplacement (string): Cilindradas (cilin — campo J07). Capacidade volumétrica do motor, expressa em centímetros cúbicos (CC). Indica o volume total dos cilindros do motor.
- Validações: Obrigatório. Máximo de 4 caracteres.
- Exemplo: 1998 (equivale a 2.0 litros)
netWeight (string): Peso Líquido (pesoL — campo J08). Peso do veículo sem carga, passageiros ou acessórios opcionais, expresso em quilogramas.
- Validações: Obrigatório. Máximo de 9 caracteres.
- Exemplo: 1250
grossWeight (string): Peso Bruto (pesoB — campo J09). Peso total do veículo incluindo a capacidade máxima de carga permitida, expresso em quilogramas.
- Validações: Obrigatório. Máximo de 9 caracteres.
- Exemplo: 1650
serialNumber (string): Número de Série (nSerie — campo J10). Número de série do veículo atribuído pelo fabricante. Serve como identificador adicional de produção.
- Validações: Obrigatório. Máximo de 9 caracteres.
- Exemplo: ABC123456
fuelType (string): Tipo de Combustível (tpComb — campo J11). Código numérico que identifica o tipo de combustível utilizado pelo veículo, conforme a Tabela RENAVAM. Os códigos mais comuns são:
- 01 = Álcool
- 02 = Gasolina
- 03 = Diesel
- 08 = Elétrico
- 16 = Álcool/Gasolina (flex)
- 17 = Gasolina/Álcool/GNV (flex + GNV)
- 18 = Gasolina/Elétrico (híbrido)
- Validações: Obrigatório. Máximo de 2 caracteres. Deve corresponder a um código válido da Tabela RENAVAM.
engineNumber (string): Número do Motor (nMotor — campo J12). Número de identificação do motor do veículo, gravado no bloco do motor pelo fabricante.
- Validações: Obrigatório. Máximo de 21 caracteres.
- Exemplo: MOT123456789012
maximumTractionCapacity (string): Capacidade Máxima de Tração — CMT (CMT — campo J13). Peso máximo que o veículo pode tracionar, incluindo seu próprio peso e a carga do reboque, expresso em toneladas com até 4 casas decimais.
- Validações: Obrigatório. Máximo de 9 caracteres.
- Exemplo: 1.5000 (equivale a 1,5 toneladas)
wheelBase (string): Distância entre Eixos (dist — campo J14). Distância medida entre o centro do eixo dianteiro e o centro do eixo traseiro do veículo, expressa em milímetros.
- Validações: Obrigatório. Máximo de 4 caracteres.
- Exemplo: 2620 (equivale a 2.620 mm)
modelYear (integer): Ano Modelo de Fabricação (anoMod — campo J16). Ano do modelo do veículo, conforme definido pelo fabricante. O ano modelo pode ser diferente do ano de fabricação (ex: veículo fabricado em 2025 com ano modelo 2026).
- Validações: Obrigatório. Deve conter exatamente 4 dígitos.
- Exemplo: 2026
manufactureYear (integer): Ano de Fabricação (anoFab — campo J17). Ano em que o veículo foi efetivamente produzido na linha de montagem.
- Validações: Obrigatório. Deve conter exatamente 4 dígitos.
- Exemplo: 2025
paintType (string): Tipo de Pintura (tpPint — campo J18). Código que identifica o tipo de acabamento da pintura do veículo (ex: sólida, metálica, perolizada).
- Validações: Obrigatório. Exatamente 1 caractere.
- Exemplo: M (Metálica)
vehicleType (string): Tipo de Veículo (tpVeic — campo J19). Código numérico que classifica o tipo do veículo conforme a Tabela RENAVAM (ex: automóvel, caminhão, motocicleta). Os códigos mais comuns são:
- 02 = Ciclomotor
- 03 = Motoneta
- 04 = Motocicleta
- 05 = Triciclo
- 06 = Automóvel
- 13 = Camioneta
- 14 = Caminhão
- 17 = Micro-ônibus
- 22 = Caminhão-trator
- Validações: Obrigatório. Máximo de 2 caracteres. Deve corresponder a um código válido da Tabela RENAVAM.
vehicleSpecies (integer): Espécie de Veículo (espVeic — campo J20). Código numérico que classifica a finalidade de uso do veículo conforme a Tabela RENAVAM:
- 1 = Passageiro
- 2 = Carga
- 3 = Misto (passageiro e carga)
- 4 = Corrida
- 5 = Tração
- 6 = Especial
- Validações: Obrigatório. Deve ser um dígito válido conforme a tabela.
vinCondition (string): Condição do VIN — Chassi (VIN — campo J21). Indica se o número do chassi (VIN) do veículo foi remarcado ou se encontra em condição original de fábrica. A remarcação ocorre quando o chassi original foi danificado e precisou ser regravado pelo DETRAN.
- R = Remarcado (chassi regravado)
- N = Normal (chassi original de fábrica)
- Validações: Obrigatório. Deve ser R ou N.
vehicleCondition (integer): Condição do Veículo (condVeic — campo J22). Indica o estado de acabamento do veículo no momento da venda. Veículos inacabados ou semi-acabados geralmente são comercializados entre montadoras e encarroçadoras para finalização.
- 1 = Acabado (veículo pronto para uso, com todos os componentes)
- 2 = Inacabado (veículo sem algum componente essencial, necessitando acabamento)
- 3 = Semi-acabado (veículo parcialmente montado, como chassis-cabina)
- Validações: Obrigatório. Deve ser 1, 2 ou 3.
brandModelCode (string): Código Marca Modelo (cMod — campo J23). Código numérico que identifica a combinação de marca e modelo do veículo na Tabela RENAVAM. Cada veículo possui um código único que identifica, por exemplo, "Volkswagen Gol 1.0" ou "Toyota Corolla 2.0".
- Validações: Obrigatório. Máximo de 6 caracteres numéricos.
- Exemplo: 123456
denatranColorCode (string): Código da Cor DENATRAN (cCorDENATRAN — campo J24). Código padronizado de cores definido pelo DENATRAN (Departamento Nacional de Trânsito). Diferente do colorCode (que é do fabricante), este código é a classificação oficial de cores para registro e documentação veicular:
- 01 = Amarelo | 02 = Azul | 03 = Bege | 04 = Branca
- 05 = Cinza | 06 = Dourada | 07 = Grená | 08 = Laranja
- 09 = Marrom | 10 = Prata | 11 = Preta | 12 = Rosa
- 13 = Roxa | 14 = Verde | 15 = Vermelha | 16 = Fantasia
- Validações: Obrigatório. Máximo de 2 caracteres numéricos. Deve ser um dos códigos acima.
seatingCapacity (integer): Lotação — Capacidade de Passageiros (lota — campo J25). Quantidade máxima de passageiros que o veículo pode transportar sentados, incluindo o motorista. Este valor consta no certificado de registro do veículo.
- Validações: Obrigatório. Máximo de 3 dígitos.
- Exemplo: 5 (automóvel padrão com 5 lugares)
restrictionType (integer): Tipo de Restrição (tpRest — campo J26). Indica se existe alguma restrição legal ou financeira sobre o veículo que limita sua comercialização ou transferência de propriedade:
- 0 = Não há restrição (veículo livre para venda e transferência)
- 1 = Alienação Fiduciária (veículo dado como garantia em financiamento)
- 2 = Arrendamento Mercantil (veículo em contrato de leasing)
- 3 = Reserva de Domínio (vendedor mantém a propriedade até quitação total)
- 4 = Penhor de Veículos (veículo dado como garantia em empréstimo)
- 9 = Outras restrições
- Validações: Obrigatório. Deve ser um dos valores acima (0, 1, 2, 3, 4 ou 9).

Nota Importante: O grupo vehicleDetail é mutuamente exclusivo com fuelDetail (combustível) e medicineDetail (medicamento). Cada item da nota fiscal pode conter no máximo um desses grupos de produto específico. Se mais de um for preenchido por engano, a API seguirá a ordem de precedência: medicamento > veículo > combustível.

7. Apêndice D: Erros Comuns e Suas Soluções

Esta seção descreve as rejeições mais comuns durante o processo de emissão da NF-e/NFC-e e fornece orientações sobre como corrigi-las.

7.1. Rejeições Gerais

Rejeição 204: Duplicidade de NF-e

O que significa: Já existe uma nota fiscal com o mesmo número, série e CNPJ do emitente na base de dados da SEFAZ.
Causa Comum: Tentativa de reenviar uma nota que já foi autorizada ou está em processamento, ou erro no controle de numeração sequencial.
Como Corrigir: Verifique o status da nota fiscal original. Se ela já foi autorizada, não a reenvie. Se precisa 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 leiaute esperado pela API.
Causa Comum: Campos com tipos de dados incorretos (ex: enviar um texto onde se espera um número), nomes de propriedades errados, ou estrutura de objetos aninhados incorreta.
Como Corrigir: Revise o corpo da requisição e compare-o com a especificação OpenAPI e os exemplos fornecidos nesta documentação. Preste 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 a UF de destino.
Causa Comum: Erro de digitação, IE inexistente ou IE de uma UF diferente da informada no endereço do comprador.
Como Corrigir: 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 ou NonTaxPayer e não envie o campo stateTaxNumber.

Rejeição 610: Valor 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 bate com a soma dos valores dos itens e outros campos que compõem o total.
Causa Comum: Erro de cálculo na somatória de items.totalAmount mais frete, seguro, despesas acessórias, impostos, e subtraindo os descontos.
Como Corrigir: 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 purposeType = Devolution, mas não foi informada a chave de acesso da nota original que está sendo devolvida.
Causa Comum: Esquecer de preencher o grupo additionalInformation.taxDocumentsReference.
Como Corrigir: Adicione o grupo taxDocumentsReference dentro de additionalInformation, contendo um objeto documentElectronicInvoice com a accessKey da NF-e que originou a devolução.

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

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

O que significa: Para uma operação sob o novo regime, o grupo IBSCBS não foi informado em um ou mais itens.
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 Corrigir: 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.

Rejeição 1023: Classificação Tributária do 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 um código desatualizado.
Como Corrigir: Consulte a tabela cClassTrib mais recente, disponível no Portal Nacional da NF-e, e utilize um código válido que corresponda à tributação do item.

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

O que significa: A combinação entre o situationCode (CST) e o classCode (Classificação Tributária) não é permitida.
Causa Comum: Um classCode que representa uma isenção foi combinado com um situationCode de tributação integral, por exemplo.
Como Corrigir: Verifique a tabela cClassTrib. Ela 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 de cálculo, que geralmente é vProd - vDesc + vFrete + vSeg + vOutro + vII + vIPI.
Como Corrigir: Recalcule o campo basis para cada item, garantindo que ele reflita a soma correta dos valores que compõem a base de cálculo dos novos tributos.

Rejeição 1026: Alíquota do IBS da UF 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: Utilização de uma alíquota incorreta. Durante o período de transição, as alíquotas são fixas (ex: 0,1% para 2025/2026).
Como Corrigir: 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 1001: NF-e com finalidade de débito ou crédito somente para IBS/CBS

O que significa: Uma nota com finalidade de Débito (finNFe=6) ou Crédito (finNFe=5) continha grupos de tributos do regime antigo (ICMS, IPI, PIS, COFINS).
Causa Comum: Envio de uma nota de ajuste fiscal da RTC contendo, indevidamente, tributos do modelo antigo.
Como Corrigir: Remova completamente os grupos icms, ipi, pis, cofins e icmsDestination do objeto tax de todos os itens da nota. Notas de débito e crédito são exclusivas para ajustes de IBS e CBS.

Exemplo Incorreto:

{
  "purposeType": "Credit",
  "creditType": "valueReduction",
  // ... outros dados da nota
  "items": [
    {
      // ... dados do item
      "tax": {
        // INCORRETO: Grupos do regime antigo não são permitidos
        "icms": { "origin": "0", "cst": "90" },
        "pis": { "cst": "99" },
        "cofins": { "cst": "99" },
        // CORRETO: Apenas o grupo IBSCBS deve ser usado
        "IBSCBS": {
          "situationCode": "910",
          "classCode": "RT0001",
          "basis": 100.00,
          "cbs": { "amount": -12.00 } // Valor negativo para ajuste
        }
      }
    }
  ]
}

Exemplo Corrigido:

{
  "purposeType": "Credit",
  "creditType": "valueReduction",
  // ... outros dados da nota
  "items": [
    {
      // ... dados do item
      "tax": {
        // CORRETO: Apenas o grupo IBSCBS é informado
        "IBSCBS": {
          "situationCode": "910",
          "classCode": "RT0001",
          "basis": 100.00,
          "cbs": { "amount": -12.00 } // Valor negativo para ajuste
        }
      }
    }
  ]
}

9. Apêndice F: Boas Práticas para Integração

Para garantir uma integração mais eficiente, robusta e resiliente com a API de emissão de NF-e, recomendamos seguir as práticas listadas abaixo.

9.1. Controle de Numeração e Série

O controle da numeração sequencial (number) para cada série (serie) pode ser realizado tanto pelo sistema cliente quanto pelo nosso sistema. Independentemente de quem realiza o controle, é fundamental evitar a "Rejeição 204: Duplicidade de NF-e". Além disso, 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.
Alteração de Série: Sempre que for necessário alterar ou iniciar o uso de uma nova série fiscal, é um requisito mandatório que o cadastro da Inscrição Estadual do emitente seja previamente atualizado no sistema NFE.io para o uso desta nova série. Essa obrigação existe independentemente de qual sistema realiza o controle da numeração.

9.2. 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. Isso inclui:
- Validação de Dados Cadastrais e Endereço: Para garantir a validade dos dados cadastrais do emitente e do destinatário, recomendamos o uso de nossas APIs de consulta. Elas permitem verificar se CNPJs e CPFs são válidos, se a Inscrição Estadual está ativa e vinculada ao CNPJ correto, e também consultar endereços a partir do CEP. A utilização dessas APIs evita rejeições por dados cadastrais ou de endereço incorretos.
- Garantir que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM).

9.3. Tratamento de Erros e Rejeições

Logs Detalhados: Nosso sistema mantém um histórico completo e detalhado de todas as requisições (JSON enviado) e respostas (JSON recebido) por um longo período. Em caso de erros, esses logs são uma ferramenta poderosa para análise e depuração, facilitando a identificação da causa raiz do problema e agilizando o suporte técnico.
Mecanismo de Retentativa: 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. Isso evita que o cliente precise se preocupar em implementar essa lógica, pois gerenciamos as tentativas de reenvio automaticamente em caso de falhas temporárias.

9.4. Gerenciamento do Ciclo de Vida da NF-e

Consulta de Status (Webhooks): Após o envio de uma nota, o status inicial pode ser "Processando". Para obter o status final (como "Emitida" ou "Erro"), nosso sistema trabalha com o conceito de webhooks. Em vez de implementar uma rotina de consulta periódica, você deve configurar um endpoint no seu sistema para receber nossas notificações automáticas assim que o processamento for concluído. Isso torna a comunicação mais eficiente e em tempo real.
Armazenamento Local: Embora a responsabilidade legal pelo armazenamento seja do emitente, nosso sistema armazena todos os dados e o arquivo XML de cada NF-e autorizada pelo período mínimo de 5 anos. Você pode fazer o download do XML e do DANFE em PDF a qualquer momento através de nossa plataforma, garantindo a conformidade fiscal.
Esteja Preparado para a Contingência: Sistemas da SEFAZ podem ficar indisponíveis. Para simplificar sua integração, o modo de emissão em contingência pode ser configurado diretamente no cadastro da sua Inscrição Estadual em nossa plataforma. Com essa configuração, nosso sistema gerencia automaticamente a entrada e saída do modo de contingência quando necessário, permitindo que sua operação comercial continue sem interrupções. Caso prefira, você ainda pode gerenciar a contingência manualmente.

9.5. Performance e Eficiência

Mantenha Tabelas Auxiliares Atualizadas: Mantenha uma cópia local e atualizada das tabelas de referência publicadas pelo governo, como as de NCM, CEST, CFOP e, especialmente, as novas tabelas da Reforma Tributária (cClassTrib, cCredPres). Isso evita a necessidade de consultas externas a cada emissão.
Evite Dados Desnecessários: Envie apenas os campos e grupos necessários para a sua operação. Omitir grupos opcionais que não se aplicam (como delivery se a entrega for no endereço do comprador) torna o payload mais limpo e a validação mais rápida.

9.6. Segurança

Proteja suas Credenciais: 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.

8. Apêndice E: Cancelamento, Inutilização e Devolução

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

8.1. Cancelamento

O que é: É o 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 de um 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".

8.2. Inutilização de Numeração

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

8.3. Nota Fiscal de Devolução

O que é: É a 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 por devolução após a entrega. É a única forma de anular uma operação após a circulação do bem.
Regras Principais:
- É uma nota de entrada (operationType = Incoming) para o emitente original.
- Deve obrigatoriamente 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.

NFC-e (modelo 65)

Os mesmos mecanismos valem para a NFC-e, alterando apenas o recurso de endpoint (consumerinvoices no lugar de productinvoices):

Cancelamento: DELETE /v2/companies/{companyId}/consumerinvoices/{invoiceId}. Observe que, por ser uma operação presencial com consumidor final, o prazo legal de cancelamento da NFC-e costuma ser mais curto que o da NF-e (em diversas UFs, até 30 minutos após a autorização).
Inutilização de numeração: POST /v2/companies/{companyId}/consumerinvoices/disablement.

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

A tabela a seguir detalha os códigos de Situação Tributária (situationCode) e de Classificação Tributária (classCode) para o IBS e a CBS, conforme a Reforma Tributária. A combinação correta desses códigos é essencial para a validação da NF-e no novo regime.

SituationCode (CST)	Descrição do CST	ClassCode (cClassTrib)	Descrição do ClassCode
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.
000	Tributação integral	000003	Regime automotivo - projetos incentivados, observado o art. 311 da Lei Complementar nº 214, de 2025.
000	Tributação integral	000004	Regime automotivo - projetos incentivados, observado o art. 312 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, observado o art. 212 da Lei Complementar nº 214, de 2025.
011	Tributação com alíquotas uniformes reduzidas em 60%	011001	Planos de assistência funerária, observado o art. 236 da Lei Complementar nº 214, de 2025.
011	Tributação com alíquotas uniformes reduzidas em 60%	011002	Planos de assistência à saúde, observado o art. 237 da Lei Complementar nº 214, de 2025.
011	Tributação com alíquotas uniformes reduzidas em 60%	011003	Intermediação de planos de assistência à saúde, observado o art. 240 da Lei Complementar nº 214, de 2025.
011	Tributação com alíquotas uniformes	011004	Concursos e prognósticos, observado o art. 246 da Lei Complementar nº 214, de 2025.
011	Tributação com alíquotas uniformes reduzidas em 30%	011005	Planos de assistência à saúde de animais domésticos, observado o art. 243 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200001	Aquisições de máquinas, de aparelhos, de instrumentos, de equipamentos, de matérias-primas, de produtos intermediários e de materiais de embalagem realizadas entre empresas autorizadas a operar em zonas de processamento de exportação, observado o art. 103 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200002	Fornecimento ou importação de tratores, máquinas e implementos agrícolas, destinados a produtor rural não contribuinte, e de veículos de transporte de carga destinados a transportador autônomo de carga pessoa física não contribuinte, observado o art. 110 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200003	Vendas de produtos destinados à alimentação humana relacionados no Anexo I da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, que compõem a Cesta Básica Nacional de Alimentos, criada nos termos do art. 8º da Emenda Constitucional nº 132, de 20 de dezembro de 2023, observado o art. 125 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200004	Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo XII da Lei Complementar nº 214, de 2025, observado o art. 144 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200005	Venda de dispositivos médicos com a especificação das respectivas classificações da NCM/SH previstas no Anexo IV da Lei Complementar nº 214, de 2025, quando adquiridos por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 144 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200006	Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIII da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 144 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200007	Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 145 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200008	Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 145 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200009	Fornecimento dos medicamentos relacionados no Anexo XIV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 146 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200010	Fornecimento dos medicamentos registrados na Anvisa, quando adquiridos por órgãos da administração pública direta, autarquias, fundações públicas e entidades imunes, observado o art. 146 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200011	Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, quando adquiridas por órgãos da administração pública direta, autarquias e fundações públicas, observado o art. 146 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200012	Situação de emergência de saúde pública reconhecida pelo Poder Legislativo federal, estadual, distrital ou municipal competente, ato conjunto do Ministro da Fazenda e do Comitê Gestor do IBS poderá ser editado, a qualquer momento, para incluir dispositivos não listados no Anexo XIV da Lei Complementar nº 214, de 2025, limitada a vigência do benefício ao período e à localidade da emergência de saúde pública, observado o art. 146 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200013	Fornecimento de tampões higiênicos, absorventes higiênicos internos ou externos, descartáveis ou reutilizáveis, calcinhas absorventes e coletores menstruais, observado o art. 147 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200014	Fornecimento dos produtos hortícolas, frutas e ovos, relacionados no Anexo XV da Lei Complementar nº 214 , de 2025, com a especificação das respectivas classificações da NCM/SH e desde que não cozidos, observado o art. 148 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200015	Venda de automóveis de passageiros de fabricação nacional de, no mínimo, 4 (quatro) portas, inclusive a de acesso ao bagageiro, quando adquiridos por motoristas profissionais que exerçam, comprovadamente, em automóvel de sua propriedade, atividade de condutor autônomo de passageiros, na condição de titular de autorização, permissão ou concessão do poder público, e que destinem o automóvel à utilização na categoria de aluguel (táxi), ou por pessoas com deficiência física, visual, auditiva, deficiência mental severa ou profunda, transtorno do espectro autista, com prejuízos na comunicação social e em padrões restritos ou repetitivos de comportamento de nível moderado ou grave, nos termos da legislação relativa à matéria, observado o disposto no art. 149 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200016	Prestação de serviços de pesquisa e desenvolvimento por Instituição Científica, Tecnológica e de Inovação (ICT) sem fins lucrativos para a administração pública direta, autarquias e fundações públicas ou para o contribuinte sujeito ao regime regular do IBS e da CBS, observado o disposto no art. 156 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200017	Operações relacionadas ao FGTS, considerando aquelas necessárias à aplicação da Lei nº 8.036, de 1990, realizadas pelo Conselho Curador ou Secretaria Executiva do FGTS, observado o art. 212 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200018	Operações de resseguro e retrocessão ficam sujeitas à incidência à alíquota zero, inclusive quando os prêmios de resseguro e retrocessão forem cedidos ao exterior, observado o art. 223 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200019	Importador dos serviços financeiros seja contribuinte que realize as operações de que tratam os incisos I a V do caput do art. 182, será aplicada alíquota zero na importação, sem prejuízo da manutenção do direito de dedução dessas despesas da base de cálculo do IBS e da CBS, segundo, observado o art. 231 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200020	Operação praticada por sociedades cooperativas optantes por regime específico do IBS e CBS, quando o associado destinar bem ou serviço à cooperativa de que participa, e a cooperativa fornecer bem ou serviço ao associado sujeito ao regime regular do IBS e da CBS, observado o art. 271 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200021	Serviços de transporte público coletivo de passageiros ferroviário e hidroviário urbanos, semiurbanos e metropolitanos, observado o art. 285 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200022	Operação originada fora da Zona Franca de Manaus que destine bem material industrializado de origem nacional a contribuinte estabelecido na Zona Franca de Manaus que seja habilitado nos termos do art. 442 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 445 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200023	Operação realizada por indústria incentivada que destine bem material intermediário para outra indústria incentivada na Zona Franca de Manaus, desde que a entrega ou disponibilização dos bens ocorra dentro da referida área, observado o art. 448 da Lei Complementar nº 214, de 2025.
200	Alíquota zero	200024	Operação originada fora das Áreas de Livre Comércio que destine bem material industrializado de origem nacional a contribuinte estabelecido nas Áreas de Livre Comércio que seja habilitado nos termos do art. 456 da Lei Complementar nº 214, de 2025, e sujeito ao regime regular do IBS e da CBS ou optante pelo regime do Simples Nacional de que trata o art. 12 da Lei Complementar nº 123, de 2006, observado o art. 463 da Lei Complementar nº 214, de 2025.
200	Alíquota zero apenas CBS e reduzida em 60% para IBS	200025	Fornecimento dos serviços de educação relacionados ao Programa Universidade para Todos (Prouni), instituído pela Lei nº 11.096, de 13 de janeiro de 2005, observado o art. 308 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 80%	200026	Locação de imóveis localizados nas zonas reabilitadas, pelo prazo de 5 (cinco) anos, contado da data de expedição do habite-se, e relacionados a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 70%	200027	Operações de locação, cessão onerosa e arrendamento de bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200028	Fornecimento dos serviços de educação relacionados no Anexo II da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da Nomenclatura Brasileira de Serviços, Intangíveis e Outras Operações que Produzam Variações no Patrimônio (NBS), observado o art. 129 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200029	Fornecimento dos serviços de saúde humana relacionados no Anexo III da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, observado o art. 130 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200030	Venda dos dispositivos médicos relacionados no Anexo IV da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 131 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200031	Fornecimento dos dispositivos de acessibilidade próprios para pessoas com deficiência relacionados no Anexo V da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 132 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200032	Fornecimento dos medicamentos registrados na Anvisa ou produzidos por farmácias de manipulação, ressalvados os medicamentos sujeitos à alíquota zero de que trata o art. 141 da Lei Complementar nº 214, de 2025, observado o art. 133 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200033	Fornecimento das composições para nutrição enteral e parenteral, composições especiais e fórmulas nutricionais destinadas às pessoas com erros inatos do metabolismo relacionadas no Anexo VI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 133 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200034	Fornecimento dos alimentos destinados ao consumo humano relacionados no Anexo VII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 135 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200035	Fornecimento dos produtos de higiene pessoal e limpeza relacionados no Anexo VIII da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH, observado o art. 136 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200036	Fornecimento de produtos agropecuários, aquícolas, pesqueiros, florestais e extrativistas vegetais in natura, observado o art. 137 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200037	Fornecimento de serviços ambientais de conservação ou recuperação da vegetação nativa, mesmo que fornecidos sob a forma de manejo sustentável de sistemas agrícolas, agroflorestais e agrossilvopastoris, em conformidade com as definições e requisitos da legislação específica, observado o art. 137 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200038	Fornecimento dos insumos agropecuários e aquícolas relacionados no Anexo IX da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NCM/SH e da NBS, observado o art. 138 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200039	Fornecimento dos serviços e o licenciamento ou cessão dos direitos relacionados no Anexo X da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS, quando destinados às seguintes produções nacionais artísticas, culturais, de eventos, jornalísticas e audiovisuais: espetáculos teatrais, circenses e de dança, shows musicais, desfiles carnavalescos ou folclóricos, eventos acadêmicos e científicos, como congressos, conferências e simpósios, feiras de negócios, exposições, feiras e mostras culturais, artísticas e literárias; programas de auditório ou jornalísticos, filmes, documentários, séries, novelas, entrevistas e clipes musicais, observado o art. 139 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200040	Fornecimento dos seguintes serviços de comunicação institucional à administração pública direta, autarquias e fundações públicas: serviços direcionados ao planejamento, criação, programação e manutenção de páginas eletrônicas da administração pública, ao monitoramento e gestão de suas redes sociais e à otimização de páginas e canais digitais para mecanismos de buscas e produção de mensagens, infográficos, painéis interativos e conteúdo institucional, serviços de relações com a imprensa, que reúnem estratégias organizacionais para promover e reforçar a comunicação dos órgãos e das entidades contratantes com seus públicos de interesse, por meio da interação com profissionais da imprensa, e serviços de relações públicas, que compreendem o esforço de comunicação planejado, coeso e contínuo que tem por objetivo estabelecer adequada percepção da atuação e dos objetivos institucionais, a partir do estímulo à compreensão mútua e da manutenção de padrões de relacionamento e fluxos de informação entre os órgãos e as entidades contratantes e seus públicos de interesse, no País e no exterior, observado o art. 140 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200041	Operações relacionadas às seguintes atividades desportivas: fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, e gestão e exploração do desporto por associações e clubes esportivos filiados ao órgão estadual ou federal responsável pela coordenação dos desportos, inclusive por meio de venda de ingressos para eventos desportivos, fornecimento oneroso ou não de bens e serviços, inclusive ingressos, por meio de programas de sócio-torcedor, cessão dos direitos desportivos dos atletas e transferência de atletas para outra entidade desportiva ou seu retorno à atividade em outra entidade desportiva, observado o art. 141 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200042	Operações relacionadas ao fornecimento de serviço de educação desportiva, classificado no código 1.2205.12.00 da NBS, observado o art. 141 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200043	Fornecimento à administração pública direta, autarquias e fundações púbicas dos serviços e dos bens relativos à soberania e à segurança nacional, à segurança da informação e à segurança cibernética relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200044	Operações e prestações de serviços de segurança da informação e segurança cibernética desenvolvidos por sociedade que tenha sócio brasileiro com o mínimo de 20% (vinte por cento) do seu capital social, relacionados no Anexo XI da Lei Complementar nº 214, de 2025, com a especificação das respectivas classificações da NBS e da NCM/SH, observado o art. 142 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 60%	200045	Operações relacionadas a projetos de reabilitação urbana de zonas históricas e de áreas críticas de recuperação e reconversão urbanística dos Municípios ou do Distrito Federal, a serem delimitadas por lei municipal ou distrital, observado o art. 158 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 50%	200046	Operações com bens imóveis, observado o art. 261 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 40%	200047	Bares e Restaurantes, observado o art. 275 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 40%	200048	Hotelaria, Parques de Diversão e Parques Temáticos, observado o art. 281 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 40%	200049	Transporte coletivo de passageiros rodoviário, ferroviário e hidroviário intermunicipais e interestaduais, observado o art. 286 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 40%	200450	Serviços de transporte aéreo regional coletivo de passageiros ou de carga, observado o art. 287 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 40%	200051	Agências de Turismo, observado o art. 289 da Lei Complementar nº 214, de 2025.
200	Alíquota reduzida em 30%	200052	Prestação de serviços das seguintes profissões intelectuais de natureza científica, literária ou artística, submetidas à fiscalização por conselho profissional: administradores, advogados, arquitetos e urbanistas, assistentes sociais, bibliotecários, biólogos, contabilistas, economistas, economistas domésticos, profissionais de educação física, engenheiros e agrônomos, estatísticos, médicos veterinários e zootecnistas, museólogos, químicos, profissionais de relações públicas, técnicos industriais e técnicos agrícolas, observado o art. 127 da Lei Complementar nº 214, de 2025.
210	Alíquota reduzida em 50% com redutor de base de cálculo	210001	Redutor social aplicado uma única vez na alienação de bem imóvel residencial novo, observado o art. 259 da Lei Complementar nº 214, de 2025.
210	Alíquota reduzida em 50% com redutor de base de cálculo	210002	Redutor social aplicado uma única vez na alienação de lote residencial, observado o art. 259 da Lei Complementar nº 214, de 2025.
210	Alíquota reduzida em 70% com redutor de base de cálculo	210003	Redutor social em operações de locação, cessão onerosa e arrendamento de bens imóveis de uso residencial, observado o art. 260 da Lei Complementar nº 214, de 2025.
220	Alíquota fixa	220001	Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025.
220	Alíquota fixa	220002	Incorporação imobiliária submetida ao regime especial de tributação, observado o art. 485 da Lei Complementar nº 214, de 2025.
220	Alíquota fixa	220003	Alienação de imóvel decorrente de parcelamento do solo, observado o art. 486 da Lei Complementar nº 214, de 2025.
221	Alíquota fixa proporcional	221001	Locação, cessão onerosa ou arrendamento de bem imóvel com alíquota sobre a receita bruta, observado o art. 487 da Lei Complementar nº 214, de 2025.
400	Isenção	400001	Fornecimento de serviços de transporte público coletivo de passageiros rodoviário e metroviário de caráter urbano, semiurbano e metropolitano, sob regime de autorização, permissão ou concessão pública, observado o art. 157 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410001	Fornecimento de bonificações quando constem do respectivo documento fiscal e que não dependam de evento posterior, observado o art. 5º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410002	Transferências entre estabelecimentos pertencentes ao mesmo contribuinte, observado o art. 6º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410003	Doações, observado o art. 6º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410004	Exportações de bens e serviços, observado o art. 8º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410005	Fornecimentos realizados pela União, pelos Estados, pelo Distrito Federal e pelos Municípios, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410006	Fornecimentos realizados por entidades religiosas e templos de qualquer culto, inclusive suas organizações assistenciais e beneficentes, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410007	Fornecimentos realizados por partidos políticos, inclusive suas fundações, entidades sindicais dos trabalhadores e instituições de educação e de assistência social, sem fins lucrativos, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410008	Fornecimentos de livros, jornais, periódicos e do papel destinado a sua impressão, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410009	Fornecimentos de fonogramas e videofonogramas musicais produzidos no Brasil contendo obras musicais ou literomusicais de autores brasileiros e/ou obras em geral interpretadas por artistas brasileiros, bem como os suportes materiais ou arquivos digitais que os contenham, salvo na etapa de replicação industrial de mídias ópticas de leitura a laser, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410010	Fornecimentos de serviço de comunicação nas modalidades de radiodifusão sonora e de sons e imagens de recepção livre e gratuita, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410011	Fornecimentos de ouro, quando definido em lei como ativo financeiro ou instrumento cambial, observado o art. 9º da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410012	Fornecimento de condomínio edilício não optante pelo regime regular, observado o art. 26 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410013	Exportações de combustíveis, observado o art. 98 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410014	Fornecimento de produtor rural não contribuinte, observado o art. 164 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410015	Fornecimento por transportador autônomo não contribuinte, observado o art. 169 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410016	Fornecimento ou aquisição de resíduos sólidos, observado o art. 170 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410017	Aquisição de bem móvel com crédito presumido sob condição de revenda realizada, observado o art. 171 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410018	Operações relacionadas aos fundos garantidores e executores de políticas públicas, inclusive de habitação, previstos em lei, assim entendidas os serviços prestados ao fundo pelo seu agente operador e por entidade encarregada da sua administração, observado o art. 213 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410019	Exclusão da gorjeta na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025.
410	Imunidade e não incidência	410020	Exclusão do valor de intermediação na base de cálculo no fornecimento de alimentação, observado o art. 274 da Lei Complementar nº 214, de 2025.
510	Diferimento	510001	Operações, sujeitas a diferimento, com energia elétrica ou com direitos a ela relacionados, relativas à geração, comercialização, distribuição e transmissão, observado o art. 28 da Lei Complementar nº 214, de 2025.
510	Diferimento	510002	Operações, sujeitas a diferimento, com insumos agropecuários e aquícolas destinados a produtor rural contribuinte, observado o art. 138 da Lei Complementar nº 214, de 2025.
550	Suspensão	550001	Exportações de bens materiais, observado o art. 82 da Lei Complementar nº 214, de 2025.
550	Suspensão	550002	Regime de Trânsito, observado o art. 84 da Lei Complementar nº 214, de 2025.
550	Suspensão	550003	Regimes de Depósito, observado o art. 85 da Lei Complementar nº 214, de 2025.
550	Suspensão	550004	Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025.
550	Suspensão	550005	Regimes de Depósito, observado o art. 87 da Lei Complementar nº 214, de 2025.
550	Suspensão	550006	Regimes de Permanência Temporária, observado o art. 88 da Lei Complementar nº 214, de 2025.
550	Suspensão	550007	Regimes de Aperfeiçoamento, observado o art. 90 da Lei Complementar nº 214, de 2025.
550	Suspensão	550008	Importação de bens para o Regime de Repetro-Temporário, de que tratam o inciso I do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550009	GNL-Temporário, de que trata o inciso II do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550010	Repetro-Permanente, de que trata o inciso III do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550011	Repetro-Industrialização, de que trata o inciso IV do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550012	Repetro-Nacional, de que trata o inciso V do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550013	Repetro-Entreposto, de que trata o inciso VI do art. 93 da Lei Complementar nº 214, de 2025.
550	Suspensão	550014	Zona de Processamento de Exportação, observado os arts. 99, 100 e 102 da Lei Complementar nº 214, de 2025.
550	Suspensão	550015	Regime Tributário para Incentivo à Modernização e à Ampliação da Estrutura Portuária - Reporto, observado o art. 105 da Lei Complementar nº 214, de 2025.
550	Suspensão	550016	Regime Especial de Incentivos para o Desenvolvimento da Infraestrutura - Reidi, observado o art. 106 da Lei Complementar nº 214, de 2025.
550	Suspensão	550017	Regime Tributário para Incentivo à Atividade Econômica Naval – Renaval, observado o art. 107 da Lei Complementar nº 214, de 2025.
550	Suspensão	550018	Desoneração da aquisição de bens de capital, , observado o art. 109 da Lei Complementar nº 214, de 2025.
550	Suspensão	550019	Importação de bem material por indústria incentivada para utilização na Zona Franca de Manaus, observado o art. 443 da Lei Complementar nº 214, de 2025.
550	Suspensão	550020	Áreas de livre comércio, observado o art. 461 da Lei Complementar nº 214, de 2025.
620	Tributação monofásica	620001	Tributação monofásica sobre combustíveis, observados os art. 172 e art. 179 I da Lei Complementar nº 214, de 2025.
620	Tributação monofásica	620002	Tributação monofásica com responsabilidade pela retenção sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025.
620	Tributação monofásica	620003	Tributação monofásica com tributos retidos por responsabilidade sobre combustíveis, observado o art. 178 da Lei Complementar nº 214, de 2025.
620	Tributação monofásica	620004	Tributação monofásica sobre mistura de EAC com gasolina A em percentual superior ou inferior ao obrigatório, observado o art. 179 da Lei Complementar nº 214, de 2025.
620	Tributação monofásica	620005	Tributação monofásica sobre combustíveis cobrada anteriormente, observador o art. 180 da Lei Complementar nº 214, de 2025.
800	Transferência de crédito	800001	Fusão, cisão ou incorporação, observado o art. 55 da Lei Complementar nº 214, de 2025.
800	Transferência de crédito	800002	Transferência de crédito do associado, inclusive as cooperativas singulares, para cooperativa de que participa das operações antecedentes às operações em que fornece bens e serviços e os créditos presumidos, observado o art. 272 da Lei Complementar nº 214, de 2025.
810	Ajustes	810001	Crédito presumido sobre o valor apurado nos fornecimentos a partir da Zona Franca de Manaus, observado o art. 450 da Lei Complementar nº 214, de 2025.
820	Tributação em declaração de regime específico	820001	Documento com informações de fornecimento de serviços de planos de assinstência à saúde, mas com tributação realizada por outro meio, observado o art. 235 da Lei Complementar nº 214, de 2025.
820	Tributação em declaração de regime específico	820002	Documento com informações de fornecimento de serviços de planos de assinstência funerária, mas com tributação realizada por outro meio, observado o art. 236 da Lei Complementar nº 214, de 2025.
820	Tributação em declaração de regime específico	820003	Documento com informações de fornecimento de serviços de planos de assinstência à saúde de animais domésticos, mas com tributação realizada por outro meio, observado o art. 243 da Lei Complementar nº 214, de 2025.
820	Tributação em declaração de regime específico	820004	Documento com informações de prestação de serviços de consursos de prognósticos, mas com tributação realizada por outro meio, observado o art. 248 da Lei Complementar nº 214, de 2025.
820	Tributação em declaração de regime específico	820005	Documento com informações de alienação de bens imóveis, mas com tributação realizada por outro meio,, observado o art. 254 da Lei Complementar nº 214, de 2025.

11. Apêndice H: Referência Completa de Enumerações (Enums)

Este apêndice documenta todas as enumerações utilizadas pela API, com o mapeamento entre o valor recebido no JSON, o valor correspondente no XML da SEFAZ (quando aplicável) e a descrição do significado de cada valor.

11.1. Enums de Identificação da Operação

11.1.1. `OperationType` — Tipo de Operação (`tpNF`)

Identifica se a NF-e/NFC-e representa uma entrada ou saída de mercadoria do estabelecimento emitente.

Valor JSON	Valor SEFAZ	Descrição	Quando usar
`Outgoing`	`1`	Saída	Vendas, remessas, transferências de saída, exportações. Default.
`Incoming`	`0`	Entrada	Devoluções recebidas, retornos, NF-e complementar de entrada, NF-e de crédito.

Regra: Notas com purposeType = Devolution ou creditType informado devem ser obrigatoriamente Incoming.

11.1.2. `Destination` — Identificador de Local de Destino (`idDest`)

Indica onde a mercadoria é destinada para fins de tributação interestadual e cálculo do DIFAL/IBS-CBS.

Valor JSON	Valor SEFAZ	Descrição
`None`	—	Não definido (não use em produção).
`InternalOperation`	`1`	Operação interna — UF do destinatário igual à UF do emitente. Default.
`InterstateOperation`	`2`	Operação interestadual — UF do destinatário diferente da UF do emitente.
`InternationalOperation`	`3`	Operação com o exterior — destinatário em país diferente do Brasil.

Aliases legados: Internal_Operation, Interstate_Operation, International_Operation (com underline) são aceitos por compatibilidade, mas a forma sem underline é a preferida.

11.1.3. `PurposeType` — Finalidade da Emissão (`finNFe`)

Define a natureza fiscal da NF-e/NFC-e e governa quais grupos podem/devem ser preenchidos.

Valor JSON	Valor SEFAZ	Descrição	Restrições
`None`	`0`	Não definido	Não usar.
`Normal`	`1`	NF-e normal	Default. Operação fiscal padrão.
`Complement`	`2`	NF-e complementar	Deve referenciar uma NF-e original em `additionalInformation.taxDocumentsReference`.
`Adjustment`	`3`	NF-e de ajuste	Deve referenciar NF-e original. `totalIndicator` dos itens deve ser `false`.
`Devolution`	`4`	Devolução de mercadoria	Deve ser `operationType = Incoming` e referenciar a NF-e original.

RTC: A partir de 05/01/2026, os valores 5 (Crédito) e 6 (Débito) também são válidos via campos creditType e debitType (atualmente expostos como enums separados).

11.1.4. `DebitType` — Tipo de Nota de Débito (`tpNFDebito`)

Aplicável apenas quando purposeType = 6 (Débito). Detalha o motivo do débito segundo a Reforma Tributária.

Valor JSON	Valor SEFAZ	Descrição
`TransferCreditsToCooperatives`	`01`	Transferência de créditos para cooperativas
`CancelCreditsExemptImmuneSales`	`02`	Cancelamento de créditos por vendas isentas/imunes
`UnprocessedInvoicesDebits`	`03`	Débitos de faturas não processadas no cálculo
`FinesAndInterest`	`04`	Multa e juros
`TransferInheritanceCredit`	`05`	Transferência de crédito na sucessão
`AdvancePayment`	`06`	Pagamento antecipado
`InventoryLoss`	`07`	Perda de estoque
`SnDisqualification`	`08`	Desenquadramento do Simples Nacional

11.1.5. `CreditType` — Tipo de Nota de Crédito (`tpNFCredito`)

Aplicável apenas quando purposeType = 5 (Crédito).

Valor JSON	Valor SEFAZ	Descrição
`FinesAndInterest`	`01`	Multa e juros
`IbsPresumedCreditAppropriationZfm`	`02`	Apropriação de crédito presumido de IBS sobre saldo devedor na ZFM
`ReturnDeliveryRefusedOrNotFound`	`03`	Retorno por recusa na entrega ou não localização do destinatário
`ValueReduction`	`04`	Redução de valores
`TransferCreditSuccession`	`05`	Transferência de crédito na sucessão

NT 2025.002: O Ajuste SINIEF 8/26 (vigência 04/05/2026) introduziu o código 06 — Retorno por recusa parcial na entrega, que desmembra o antigo 03 (recusa total/não localização) e exige referenciamento dos itens recusados na NF-e original. Ainda não exposto como valor de enum nesta versão da API.

11.2. Enums do Consumidor / Comprador

11.2.1. `ConsumerType` — Indicador de Operação com Consumidor Final (`indFinal`)

Valor JSON	Valor SEFAZ	Descrição
`Normal`	`0`	Operação não destinada a consumidor final (revenda, industrialização, etc.). Default para CNPJ.
`FinalConsumer`	`1`	Operação destinada a consumidor final. Default para CPF/NIF.

Regra de inferência: Se omitido, o sistema usa o federalTaxNumber do buyer: CNPJ → Normal; CPF/NIF → FinalConsumer.

11.2.2. `ConsumerPresenceType` — Indicador de Presença (`indPres`)

Caracteriza o canal/modalidade da operação comercial.

Valor JSON	Valor SEFAZ	Descrição
`None`	`0`	Não se aplica (NF-e complementar ou ajuste).
`Presence`	`1`	Operação presencial (PDV físico).
`Internet`	`2`	Operação não presencial via Internet (e-commerce). Default.
`Telephone`	`3`	Operação não presencial via teleatendimento.
`Delivery`	`4`	NFC-e em operação com entrega a domicílio.
`OthersNonPresenceOperation`	`9`	Outros, operação não presencial.

NFC-e: Apenas Presence e Delivery são aceitos.

11.2.3. `PersonType` — Tipo da Pessoa

Valor JSON	Valor numérico	Descrição
`Undefined`	`0`	Indefinido.
`NaturalPerson`	`2`	Pessoa Física (PF).
`LegalEntity`	`4`	Pessoa Jurídica (PJ).
`Company`	`8`	(obsoleto, uso interno) Prestador de serviço.
`Customer`	`16`	(obsoleto, uso interno) Cliente.

Decimal flags: Este enum usa [Flags], mas na prática só são usados NaturalPerson e LegalEntity no payload externo.

11.2.4. `ReceiverStateTaxIndicator` — Indicador da IE do Destinatário (`indIEDest`)

Define a relação do destinatário com o ICMS — campo crítico para cálculo de DIFAL e validação da IE.

Valor JSON	Valor SEFAZ	Descrição	Comportamento da IE
`None`	—	Não definido	Não usar.
`TaxPayer`	`1`	Contribuinte ICMS	`stateTaxNumber` deve ser informado e válido.
`Exempt`	`2`	Contribuinte isento de inscrição	`stateTaxNumber` não deve ser informado.
`NonTaxPayer`	`9`	Não Contribuinte	`stateTaxNumber` opcional (pode ou não possuir IE).

11.3. Enums Tributários e de Regime

11.3.1. `TaxRegime` — Código de Regime Tributário (`CRT`)

Valor JSON	Valor SEFAZ	Descrição
`None`	—	Não definido.
`LucroReal`	`3`	Lucro Real.
`LucroPresumido`	`3`	Lucro Presumido (mesmo CRT que Lucro Real — categorizado como "Regime Normal").
`SimplesNacional`	`1`	Simples Nacional.
`SimplesNacionalExcessoSublimite`	`2`	Simples Nacional — excesso de sublimite de receita bruta.
`MicroempreendedorIndividual`	`4`	Microempreendedor Individual (MEI).
`Isento`	—	Isento.

11.3.2. `SpecialTaxRegime` — Regime Especial de Tributação (`indRegTrib`)

Valor JSON	Descrição
`Nenhum`	Nenhum
`MicroempresaMunicipal`	Microempresa Municipal
`Estimativa`	Estimativa
`SociedadeDeProfissionais`	Sociedade de Profissionais
`MicroempreendedorIndividual`	Microempreendedor Individual (MEI)
`MicroempresarioEmpresaPequenoPorte`	Microempresário e Empresa de Pequeno Porte (ME/EPP)
`Automatico`	Automático

11.3.3. `ExemptReason` — Motivo da Desoneração ICMS (`motDesICMS`)

Valor JSON	Valor SEFAZ	Descrição
`Agriculture`	`3`	Uso na agropecuária
`Others`	`9`	Outros
`DevelopmentEntities`	`12`	Órgão de fomento e desenvolvimento agropecuário

11.3.4. `DuductionIndicator` — Indicador de Dedução do ICMS Desonerado (`indDeducao`)

Valor JSON	Valor SEFAZ	Descrição
`NotDeduct`	`0`	O valor do ICMS desonerado não deduz do valor total da NF-e.
`Deduce`	`1`	O valor do ICMS desonerado deduz do valor total da NF-e.

11.4. Enums de IBS/CBS (Reforma Tributária)

11.4.1. `TaxCalculationMode` — Modo de Cálculo IBS/CBS

Define como os campos de IBS/CBS são preenchidos.

Valor JSON	Valor numérico	Descrição
`Manual`	`0`	Preenchimento manual de todos os campos de tributo. Default.
`OfficialService`	`1`	Cálculo automático via serviço oficial. Apenas `situationCode` e `classCode` são necessários; demais campos são ignorados na entrada e preenchidos pelo serviço de cálculo.

11.4.2. `IbsZfmPresumedCreditClassification` — Classificação do Crédito Presumido ZFM (`tpCredPresIBSZFM`)

Para cálculo do crédito presumido de IBS em fornecimentos da Zona Franca de Manaus (art. 450 LC 214/2025).

Valor JSON	Percentual	Descrição
`NoPresumedCredit`	0%	Sem crédito presumido.
`FinalConsumptionGoods`	55%	Bens de consumo final.
`CapitalGoods`	75%	Bens de capital.
`IntermediateGoods`	90,25%	Bens intermediários.
`ItAndOtherGoods`	100%	Bens de informática e outros definidos em legislação.

11.4.3. `PresumedCreditClassificationCode` — Crédito Presumido Operacional (`cCredPres`)

Classifica a operação que dá direito ao crédito presumido operacional.

Valor JSON	Valor SEFAZ	Descrição
`RuralProducerNonTaxpayer`	`01`	Produtor rural não contribuinte (art. 168 LC 214/2025)
`TacPfTransportServiceNonTaxpayer`	`02`	TAC PF não contribuinte do serviço de transporte (art. 169)
`RecyclingFromIndividual`	`03`	Reciclagem de pessoa física (art. 170)
`UsedMovableGoodsFromIndividualForResale`	`04`	Bens móveis usados de PF para revenda (art. 171)
`OptionalRegimeForCooperative`	—	Regime opcional para cooperativa

Tabela cCredPres: A tabela oficial (NT 2025.002) possui 13 códigos (01–13), incluindo regime automotivo (05–06) e Zona Franca de Manaus / Áreas de Livre Comércio (07–13). O valor OptionalRegimeForCooperative não corresponde a um código cCredPres direto e é tratado pelo regime específico das cooperativas.

11.4.4. `GovernmentPurchaseEntityType` — Tipo de Ente Governamental (`tpEnteGov`)

Valor JSON	Valor SEFAZ	Descrição
`Union`	`1`	União
`State`	`2`	Estado
`FederalDistrict`	`3`	Distrito Federal
`Municipality`	`4`	Município

11.4.5. `GovernmentPurchaseOperationType` — Tipo de Operação com Ente Governamental (`tpOperGov`)

Valor JSON	Valor SEFAZ	Descrição
`Supply`	`1`	Fornecimento
`Payment`	`2`	Recebimento do pagamento
`SupplyThenPay`	—	Fornecimento e pagamento simultâneo
`PayForPastSupply`	—	Pagamento por fornecimento passado
`SupplyAfterPay`	—	Fornecimento após pagamento
`PayNowSupplyLater`	—	Pagamento agora, fornecimento depois
`SupplyAndPayNow`	—	Fornecimento e pagamento agora

Campo tpOperGov: Na NT 2025.002 (inclusive v1.40), o campo da SEFAZ admite apenas 1 (Fornecimento) e 2 (Recebimento do pagamento). Os demais valores são abstrações da API NFe.io, resolvidas para 1 ou 2 conforme o fato gerador do IBS/CBS — os cenários combinados são tratados por regras de validação e pelo campo refDFeAnt, não por novos códigos.

11.5. Enums de Pagamento

11.5.1. `PaymentMethod` — Forma de Pagamento (`tPag`)

Lista completa das formas de pagamento aceitas pela SEFAZ.

Valor JSON	Valor SEFAZ	Descrição
`Cash`	`01`	Dinheiro
`Cheque`	`02`	Cheque
`CreditCard`	`03`	Cartão de Crédito
`DebitCard`	`04`	Cartão de Débito
`StoreCredict`	`05`	Crédito Loja
`FoodVouchers`	`10`	Vale Alimentação
`MealVouchers`	`11`	Vale Refeição
`GiftVouchers`	`12`	Vale Presente
`FuelVouchers`	`13`	Vale Combustível
`MercantileDuplicate`	`14`	Duplicata Mercantil
`BankBill`	`15`	Boleto Bancário
`BankDeposit`	`16`	Depósito Bancário
`InstantPayment`	`17`	Pagamento Instantâneo (PIX) — dinâmico
`WireTransfer`	`18`	Transferência bancária / Carteira Digital
`Cashback`	`19`	Programa de fidelidade / Cashback / Crédito Virtual
`StaticInstantPayment`	`20`	PIX Estático
`StoreCredit`	`21`	Crédito em Loja
`ElectronicPaymentNotInformed`	`22`	Pagamento Eletrônico Não Informado
`WithoutPayment`	`90`	Sem Pagamento (ex: remessa, bonificação)
`Others`	`99`	Outros

Validação: Quando method = CreditCard ou DebitCard, o grupo card é obrigatório.

11.5.2. `PaymentType` — Indicador da Forma de Pagamento (`indPag`)

Valor JSON	Valor SEFAZ	Descrição
`InCash`	`0`	Pagamento à vista
`Term`	`1`	Pagamento a prazo

11.5.3. `IntegrationPaymentType` — Tipo de Integração (`tpIntegra`)

Aplicável dentro do grupo card.

Valor JSON	Valor SEFAZ	Descrição
`Integrated`	`1`	Pagamento integrado com o sistema de automação da empresa (Ex.: TEF, Comércio Eletrônico).
`NotIntegrated`	`2`	Pagamento não integrado (Ex.: equipamento POS independente).

11.5.4. `FlagCard` — Bandeira do Cartão (`tBand`)

Valor JSON	Valor SEFAZ	Bandeira
`None`	`00`	Não definido
`Visa`	`01`	Visa
`Mastercard`	`02`	Mastercard
`AmericanExpress`	`03`	American Express
`Sorocred`	`04`	Sorocred
`DinersClub`	`05`	Diners Club
`Elo`	`06`	Elo
`Hipercard`	`07`	Hipercard
`Aura`	`08`	Aura
`Cabal`	`09`	Cabal
`Alelo`	`10`	Alelo
`BanesCard`	`11`	Banescard
`CalCard`	`12`	Calcard
`Credz`	`13`	Credz
`Discover`	`14`	Discover
`GoodCard`	`15`	Good Card
`GreenCard`	`16`	Green Card
`Hiper`	`17`	Hiper
`JCB`	`18`	JCB
`Mais`	`19`	Mais
`MaxVan`	`20`	Maxvan
`Policard`	`21`	Policard
`RedeCompras`	`22`	Rede Compras
`Sodexo`	`23`	Sodexo
`ValeCard`	`24`	ValeCard
`Verocheque`	`25`	Verocheque
`VR`	`26`	VR
`Ticket`	`27`	Ticket
`Other`	`99`	Outros

11.6. Enums de Transporte e Importação

11.6.1. `ShippingModality` — Modalidade do Frete (`modFrete`)

Valor JSON	Valor SEFAZ	Descrição
`ByIssuer`	`0`	Contratação do frete por conta do Remetente (CIF)
`ByReceiver`	`1`	Contratação do frete por conta do Destinatário (FOB)
`ByThirdParties`	`2`	Contratação do frete por conta de terceiros
`OwnBySender`	`3`	Transporte próprio por conta do remetente
`OwnByBuyer`	`4`	Transporte próprio por conta do destinatário
`Free`	`9`	Sem ocorrência de transporte. Default.

Validação: Se Free, os grupos transportGroup, transportVehicle, reboque e volume não devem ser preenchidos.

11.6.2. `IntermediationType` — Forma de Importação quanto a Intermediação (`tpIntermedio`)

Valor JSON	Valor SEFAZ	Descrição
`None`	`0`	Não definido
`ByOwn`	`1`	Importação por conta própria
`ImportOnBehalf`	`2`	Importação por conta e ordem de terceiro
`ByOrder`	`3`	Importação por encomenda

11.6.3. `InternationalTransportType` — Via de Transporte Internacional (`tpViaTransp`)

Informada na Declaração de Importação (DI).

Valor JSON	Valor SEFAZ	Descrição
`None`	`0`	Não definido
`Maritime`	`1`	Marítima
`River`	`2`	Fluvial
`Lake`	`3`	Lacustre
`Airline`	`4`	Aérea
`Postal`	`5`	Postal
`Railway`	`6`	Ferroviária
`Highway`	`7`	Rodoviária
`Network`	`8`	Conduto / Rede de transmissão
`Own`	`9`	Meios próprios
`Ficta`	`10`	Entrada / Saída ficta
`Courier`	`11`	Serviço de Courier
`Handcarry`	`12`	Em mãos

11.7. Enums de Impressão e Ambiente

11.7.1. `PrintType` — Formato de Impressão do DANFE (`tpImp`)

Valor JSON	Valor SEFAZ	Descrição
`None`	`0`	Sem geração de DANFE
`NFeNormalPortrait`	`1`	DANFE normal — Retrato
`NFeNormalLandscape`	`2`	DANFE normal — Paisagem
`NFeSimplified`	`3`	DANFE simplificado
`DANFE_NFC_E`	`4`	DANFE NFC-e
`DANFE_NFC_E_MSG_ELETRONICA`	`5`	DANFE NFC-e em mensagem eletrônica

11.7.2. `EnvironmentType` — Tipo de Ambiente (`tpAmb`)

Valor JSON	Valor SEFAZ	Descrição
`None`	—	Não definido
`Production`	`1`	Produção (validade fiscal)
`Test`	`2`	Homologação (sem validade fiscal)

11.7.3. `StateTaxProcessingAuthorizer`

Identifica o autorizador SEFAZ que processou (ou está processando) o documento.

Valor JSON	Descrição
`Normal`	Autorizador Normal (SEFAZ da UF do emitente ou autorizador alternativo)
`EPEC`	Autorizador de Evento Prévio de Emissão em Contingência

11.8. Enums de Status e Eventos

11.8.1. `InvoiceStatus` — Status da NF-e

Valor JSON	Valor numérico interno	Descrição
`None`	`0`	Estado inicial / não definido
`Created`	`1`	Criada (recebida pela API, ainda não enviada à SEFAZ)
`Processing`	`2`	Em processamento (envio em andamento)
`Issued`	`3`	Emitida e autorizada pela SEFAZ
`IssuedContingency`	`4`	Emitida em contingência
`Cancelled`	`5`	Cancelada
`Disabled`	`6`	Inutilizada (numeração)
`IssueDenied`	`-2`	Emissão denegada pela SEFAZ
`Error`	`-1`	Erro no processamento

11.8.2. `EconomicActivityType` — Tipo de Atividade Econômica

Valor JSON	Descrição
`Main`	Principal
`Secondary`	Secundária

11.9. Enums de Estados Brasileiros (`StateCode`)

Lista das siglas das UFs brasileiras + indicador de exterior (EX). Aplicável em campos como state (endereço), customsClearanceState, etc.

Sigla	Descrição
`NA`	Não Aplicável
`RO`, `AC`, `AM`, `RR`, `PA`, `AP`, `TO`	Região Norte
`MA`, `PI`, `CE`, `RN`, `PB`, `PE`, `AL`, `SE`, `BA`	Região Nordeste
`MG`, `ES`, `RJ`, `SP`	Região Sudeste
`PR`, `SC`, `RS`	Região Sul
`MS`, `MT`, `GO`, `DF`	Região Centro-Oeste
`EX`	Exterior

11.10. Enum de Natureza Jurídica (`LegalNature`)

Aplicável ao emitente (issuer.legalNature).

Valor JSON	Descrição
`EmpresaPublica`	Empresa Pública
`SociedadeEconomiaMista`	Sociedade de Economia Mista
`SociedadeAnonimaAberta`	Sociedade Anônima Aberta
`SociedadeAnonimaFechada`	Sociedade Anônima Fechada
`SociedadeEmpresariaLimitada`	Sociedade Empresária Limitada
`SociedadeEmpresariaEmNomeColetivo`	Sociedade Empresária em Nome Coletivo
`SociedadeEmpresariaEmComanditaSimples`	Sociedade Empresária em Comandita Simples
`SociedadeEmpresariaEmComanditaporAcoes`	Sociedade Empresária em Comandita por Ações
`SociedadeemContaParticipacao`	Sociedade em Conta de Participação
`Empresario`	Empresário Individual
`Cooperativa`	Cooperativa
`ConsorcioSociedades`	Consórcio de Sociedades
`GrupoSociedades`	Grupo de Sociedades
`EmpresaDomiciliadaExterior`	Empresa Domiciliada no Exterior
`ClubeFundoInvestimento`	Clube/Fundo de Investimento
`SociedadeSimplesPura`	Sociedade Simples Pura
`SociedadeSimplesLimitada`	Sociedade Simples Limitada
`SociedadeSimplesEmNomeColetivo`	Sociedade Simples em Nome Coletivo
`SociedadeSimplesEmComanditaSimples`	Sociedade Simples em Comandita Simples
`EmpresaBinacional`	Empresa Binacional
`ConsorcioEmpregadores`	Consórcio de Empregadores
`ConsorcioSimples`	Consórcio Simples
`EireliNaturezaEmpresaria`	EIRELI de Natureza Empresária
`EireliNaturezaSimples`	EIRELI de Natureza Simples
`ServicoNotarial`	Serviço Notarial e de Registro
`FundacaoPrivada`	Fundação Privada
`ServicoSocialAutonomo`	Serviço Social Autônomo
`CondominioEdilicio`	Condomínio Edilício
`ComissaoConciliacaoPrevia`	Comissão de Conciliação Prévia
`EntidadeMediacaoArbitragem`	Entidade de Mediação e Arbitragem
`PartidoPolitico`	Partido Político
`EntidadeSindical`	Entidade Sindical
`EstabelecimentoBrasilFundacaoAssociacaoEstrangeiras`	Estabelecimento no Brasil de Fundação ou Associação Estrangeiras
`FundacaoAssociacaoDomiciliadaExterior`	Fundação ou Associação Domiciliada no Exterior
`OrganizacaoReligiosa`	Organização Religiosa
`ComunidadeIndigena`	Comunidade Indígena
`FundoPrivado`	Fundo Privado
`AssociacaoPrivada`	Associação Privada

12. Apêndice I: Mapeamento Propriedade-a-Propriedade (JSON ↔ XML SEFAZ)

Esta seção complementa o Apêndice A (§3) descendo ao nível de cada propriedade individual. Para cada campo do JSON, indicamos o caminho completo, o tag XML correspondente no leiaute oficial (NT 2025.002), o tipo e observações de preenchimento.

Convenção: O caminho JSON usa notação por ponto (ex: buyer.address.state). O tag XML usa o nome exato do elemento no schema oficial. Quando um campo JSON encapsula múltiplos tags ou estruturas auxiliares, o "Tag XML" lista o tag principal.

12.1. Identificação da Nota (`ide`)

Estes campos ficam no nível raiz do JSON da requisição.

Caminho JSON	Tag XML	Tipo	Observações
`serie`	`serie`	int	Série do documento (0–999).
`number`	`nNF`	int	Número sequencial.
`operationOn`	`dhSaiEnt`	datetime	Data/hora de saída ou entrada. Não enviar para NFC-e.
`expectedDeliveryOn`	`dPrevEntrega`	date	Data prevista de entrega. Não aplicável a NFC-e.
`operationNature`	`natOp`	string	Descrição da operação.
`operationType`	`tpNF`	enum	`Outgoing=1`, `Incoming=0`. Ver §11.1.1.
`destination`	`idDest`	enum	Ver §11.1.2.
`consumptionCityCode`	`cMunFG`	int	Código IBGE do município.
`ibsConsumptionCityCode`	`cMunFGIBS`	int	Aplicável a operações presenciais fora do estabelecimento.
`printType`	`tpImp`	enum	Ver §11.7.1.
`purposeType`	`finNFe`	enum	Ver §11.1.3.
`debitType`	`tpNFDebito`	enum	Apenas para `purposeType=6`. Ver §11.1.4.
`creditType`	`tpNFCredito`	enum	Apenas para `purposeType=5`. Ver §11.1.5.
`consumerType`	`indFinal`	enum	Ver §11.2.1.
`presenceType`	`indPres`	enum	Ver §11.2.2.
`contingencyOn`	`dhCont`	datetime	Entrada em contingência.
`contingencyJustification`	`xJust`	string	Justificativa (mín. 15 chars).

12.2. Compras Governamentais (`gCompraGov`)

Caminho JSON	Tag XML	Tipo	Observações
`governmentPurchase.entityType`	`tpEnteGov`	enum	Ver §11.4.4.
`governmentPurchase.rateReduction`	`pRedutor`	decimal	Percentual de redução de alíquota (art. 472/370 LC 214/2025).
`governmentPurchase.operationType`	`tpOperGov`	enum	Ver §11.4.5.

12.3. Comprador / Destinatário (`dest`)

Caminho JSON	Tag XML	Tipo	Observações
`buyer.name`	`xNome`	string	Obrigatório.
`buyer.federalTaxNumber`	`CNPJ` ou `CPF`	int	Obrigatório. Ou `idEstrangeiro` para exterior.
`buyer.email`	`email`	string	Obrigatório.
`buyer.tradeName`	`xFant`	string	Nome fantasia.
`buyer.taxRegime`	`CRT`	enum	Ver §11.3.1.
`buyer.stateTaxNumber`	`IE`	string	Inscrição estadual.
`buyer.stateTaxNumberIndicator`	`indIEDest`	enum	Ver §11.2.4.
`buyer.type`	(lógico)	enum	Tipo da pessoa (NaturalPerson/LegalEntity).
`buyer.address.state`	`UF`	string	Sigla ISO 3166-2 (2 chars).
`buyer.address.city.code`	`cMun`	string	Código IBGE.
`buyer.address.city.name`	`xMun`	string	Nome do município.
`buyer.address.district`	`xBairro`	string	Bairro.
`buyer.address.additionalInformation`	`xCpl`	string	Complemento.
`buyer.address.street`	`xLgr`	string	Logradouro.
`buyer.address.number`	`nro`	string	"S/N" se sem número.
`buyer.address.postalCode`	`CEP`	string	CEP (somente dígitos).
`buyer.address.country`	`xPais`	string	ISO 3166-1 alfa-3. Default `BRA`.
`buyer.address.phone`	`fone`	string	Telefone (DDD + número).

12.4. Local de Entrega e Retirada

Caminho JSON	Tag XML	Tipo	Observações
`delivery.federalTaxNumber`	`CNPJ`/`CPF` (de `entrega`)	int	Apenas se diferente do `buyer`.
`delivery.address.*`	`entrega/...`	object	Mesma estrutura de `buyer.address`.
`withdrawal.federalTaxNumber`	`CNPJ`/`CPF` (de `retirada`)	int	Apenas se diferente do emitente.
`withdrawal.address.*`	`retirada/...`	object	Mesma estrutura de `buyer.address`.

12.5. Item — Identificação e Valores

Caminho JSON	Tag XML	Tipo	Observações
`items[].code`	`cProd`	string	Obrigatório.
`items[].codeGTIN`	`cEAN`	string	"SEM GTIN" se inexistente.
`items[].description`	`xProd`	string	Obrigatório.
`items[].ncm`	`NCM`	string	2 ou 8 dígitos.
`items[].nve[]`	`NVE`	string array	Nomenclatura de Valor Aduaneiro.
`items[].extipi`	`EXTIPI`	string	Exceção da TIPI.
`items[].cfop`	`CFOP`	int	Obrigatório se sem `taxDetermination`.
`items[].unit`	`uCom`	string	Unidade comercial.
`items[].quantity`	`qCom`	decimal	Quantidade comercial.
`items[].unitAmount`	`vUnCom`	decimal	Valor unitário de comercialização.
`items[].totalAmount`	`vProd`	decimal	`quantity * unitAmount`.
`items[].codeTaxGTIN`	`cEANTrib`	string	GTIN da unidade tributável; "SEM GTIN" se inexistente.
`items[].unitTax`	`uTrib`	string	Unidade tributável.
`items[].quantityTax`	`qTrib`	decimal	Quantidade tributável.
`items[].taxUnitAmount`	`vUnTrib`	decimal	Valor unitário de tributação.
`items[].freightAmount`	`vFrete`	decimal	Valor do frete rateado para o item.
`items[].insuranceAmount`	`vSeg`	decimal	Valor do seguro rateado para o item.
`items[].discountAmount`	`vDesc`	decimal	Valor do desconto do item.
`items[].othersAmount`	`vOutro`	decimal	Outras despesas acessórias do item.
`items[].totalIndicator`	`indTot`	bool	`0` ou `1`. Default `true`.
`items[].usedMovableAssetIndicator`	`indBemMovelUsado`	bool	Indicador de bem móvel usado (regime específico de IBS/CBS para revenda).
`items[].cest`	`CEST`	string	7 dígitos.
`items[].itemAmount`	`vItem`	decimal	Valor total do item (vProd + acréscimos − descontos).
`items[].numberOrderBuy`	`xPed`	string	Número do pedido de compra.
`items[].itemNumberOrderBuy`	`nItemPed`	int	Número do item no pedido de compra.
`items[].importControlSheetNumber`	`nFCI`	string	Ficha de Conteúdo de Importação.
`items[].benefit`	`cBenef`	string	Código de benefício fiscal na UF.
`items[].additionalInformation`	`infAdProd`	string	Informações adicionais do produto.

12.6. Item — ICMS (`tax.icms`)

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.icms.origin`	`orig`	string	Origem da mercadoria (`0`–`8`): nacional, estrangeira (importação direta ou mercado interno) etc.
`items[].tax.icms.cst`	`CST`	string	Código de Situação Tributária do ICMS (regime normal).
`items[].tax.icms.csosn`	`CSOSN`	string	Código de Situação da Operação no Simples Nacional (substitui o CST para `CRT=1`).
`items[].tax.icms.baseTaxModality`	`modBC`	string	Modalidade de determinação da BC do ICMS: `0`=Margem Valor Agregado (%); `1`=Pauta (valor); `2`=Preço Tabelado Máx. (valor); `3`=Valor da operação.
`items[].tax.icms.baseTax`	`vBC`	decimal	Valor da base de cálculo do ICMS.
`items[].tax.icms.rate`	`pICMS`	decimal	Alíquota do ICMS (%).
`items[].tax.icms.amount`	`vICMS`	decimal	Valor do ICMS.
`items[].tax.icms.baseTaxReduction`	`pRedBC`	decimal	Percentual de redução da base de cálculo.
`items[].tax.icms.baseTaxSTModality`	`modBCST`	string	Modalidade de determinação da BC do ICMS ST: `0`=Preço tabelado/máx. sugerido; `1`=Lista Negativa; `2`=Lista Positiva; `3`=Lista Neutra; `4`=Margem Valor Agregado (%); `5`=Pauta.
`items[].tax.icms.baseTaxSTReduction`	`pRedBCST`	decimal	Percentual de redução da BC do ICMS ST.
`items[].tax.icms.baseTaxST`	`vBCST`	decimal	Valor da BC do ICMS ST.
`items[].tax.icms.stRate`	`pICMSST`	decimal	Alíquota do ICMS ST (%).
`items[].tax.icms.stAmount`	`vICMSST`	decimal	Valor do ICMS ST.
`items[].tax.icms.stMarginAmount`	`pMVAST`	decimal	Percentual da margem de valor adicionado do ICMS ST.
`items[].tax.icms.stRetentionAmount`	`vICMSSTRet`	decimal	Valor do ICMS ST retido anteriormente.
`items[].tax.icms.baseSTRetentionAmount`	`vBCSTRet`	decimal	Valor da BC do ICMS ST retido anteriormente.
`items[].tax.icms.snCreditRate`	`pCredSN`	decimal	Alíquota aplicável de cálculo do crédito (Simples Nacional).
`items[].tax.icms.snCreditAmount`	`vCredICMSSN`	decimal	Valor do crédito de ICMS que pode ser aproveitado (Simples Nacional).
`items[].tax.icms.fcpRate`	`pFCP`	decimal	Percentual do Fundo de Combate à Pobreza (FCP).
`items[].tax.icms.fcpAmount`	`vFCP`	decimal	Valor do FCP.
`items[].tax.icms.fcpstRate`	`pFCPST`	decimal	Percentual do FCP retido por ST.
`items[].tax.icms.fcpstAmount`	`vFCPST`	decimal	Valor do FCP retido por ST.
`items[].tax.icms.fcpstRetRate`	`pFCPSTRet`	decimal	Percentual do FCP retido anteriormente por ST.
`items[].tax.icms.fcpstRetAmount`	`vFCPSTRet`	decimal	Valor do FCP retido anteriormente por ST.
`items[].tax.icms.baseTaxFCPSTAmount`	`vBCFCPST`	decimal	Valor da BC do FCP retido por ST.
`items[].tax.icms.exemptAmount`	`vICMSDeson`	decimal	Valor do ICMS desonerado.
`items[].tax.icms.exemptReason`	`motDesICMS`	enum	Motivo da desoneração do ICMS. Ver §11.3.3.
`items[].tax.icms.deductionIndicator`	`indDeducao`	enum	Indicador de dedução do ICMS desonerado do valor do item. Ver §11.3.4.
`items[].tax.icms.ufst`	`UFST`	string	UF para a qual é devido o ICMS ST.
`items[].tax.icms.percentualDeferment`	`pDif`	decimal	Percentual do diferimento do ICMS.
`items[].tax.icms.baseDeferred`	`vICMSDif`	decimal	Valor do ICMS diferido.
`items[].tax.icms.basisBenefitCode`	`cBenefRBC`	string	Código de benefício fiscal na UF aplicado ao item quando houver redução da BC.
`items[].tax.icms.stFinalConsumerRate`	`pST`	decimal	Alíquota suportada pelo consumidor final (ST com retenção).
`items[].tax.icms.effectiveBaseTaxReductionRate`	`pRedBCEfet`	decimal	Percentual de redução da BC efetiva.
`items[].tax.icms.effectiveBaseTaxAmount`	`vBCEfet`	decimal	Valor da BC efetiva.
`items[].tax.icms.effectiveRate`	`pICMSEFET`	decimal	Alíquota do ICMS efetiva (%).
`items[].tax.icms.effectiveAmount`	`vICMSEFET`	decimal	Valor do ICMS efetivo.

12.7. Item — IPI / II / PIS / COFINS

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.ipi.cst`	`CST` (em `IPI`)	string	Código de Situação Tributária do IPI.
`items[].tax.ipi.classificationCode`	`cEnq`	string	Código de enquadramento legal do IPI.
`items[].tax.ipi.classification`	`clEnq`	string	Classe de enquadramento do IPI (cigarros e bebidas).
`items[].tax.ipi.producerCNPJ`	`CNPJProd`	string	CNPJ do produtor da mercadoria, quando diferente do emitente.
`items[].tax.ipi.stampCode`	`cSelo`	string	Código do selo de controle do IPI.
`items[].tax.ipi.stampQuantity`	`qSelo`	decimal	Quantidade de selos de controle do IPI.
`items[].tax.ipi.base`	`vBC` (em `IPI`)	decimal	Base de cálculo do IPI (tributação por valor).
`items[].tax.ipi.rate`	`pIPI`	decimal	Alíquota do IPI (%).
`items[].tax.ipi.unitQuantity`	`qUnid`	decimal	Quantidade total na unidade padrão (tributação do IPI por unidade).
`items[].tax.ipi.unitAmount`	`vUnid`	decimal	Valor por unidade tributável (tributação do IPI por unidade).
`items[].tax.ipi.amount`	`vIPI`	decimal	Valor do IPI.
`items[].tax.ii.baseTax`	`vBC` (em `II`)	decimal	Base de cálculo do Imposto de Importação.
`items[].tax.ii.customsExpenditureAmount`	`vDespAdu`	decimal	Valor das despesas aduaneiras.
`items[].tax.ii.amount`	`vII`	decimal	Valor do Imposto de Importação.
`items[].tax.ii.iofAmount`	`vIOF`	decimal	Valor do IOF (Imposto sobre Operações Financeiras).
`items[].tax.pis.cst`	`CST` (em `PIS`)	string	Código de Situação Tributária do PIS.
`items[].tax.pis.baseTax`	`vBC` (em `PIS`)	decimal	Base de cálculo do PIS (tributação por percentual).
`items[].tax.pis.rate`	`pPIS`	decimal	Alíquota do PIS (%).
`items[].tax.pis.amount`	`vPIS`	decimal	Valor do PIS.
`items[].tax.pis.baseTaxProductQuantity`	`qBCProd`	decimal	Quantidade vendida (tributação do PIS por alíquota específica/unidade).
`items[].tax.pis.productRate`	`vAliqProd`	decimal	Alíquota do PIS em valor por unidade (R$).
`items[].tax.cofins.cst`	`CST` (em `COFINS`)	string	Código de Situação Tributária do COFINS.
`items[].tax.cofins.baseTax`	`vBC` (em `COFINS`)	decimal	Base de cálculo do COFINS (tributação por percentual).
`items[].tax.cofins.rate`	`pCOFINS`	decimal	Alíquota do COFINS (%).
`items[].tax.cofins.amount`	`vCOFINS`	decimal	Valor do COFINS.
`items[].tax.cofins.baseTaxProductQuantity`	`qBCProd`	decimal	Quantidade vendida (tributação do COFINS por alíquota específica/unidade).
`items[].tax.cofins.productRate`	`vAliqProd`	decimal	Alíquota do COFINS em valor por unidade (R$).

12.8. Item — ICMS Destino UF (`ICMSUFDest`)

Aplicável a operações interestaduais com consumidor final não contribuinte (DIFAL).

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.icmsDestination.vBCUFDest`	`vBCUFDest`	decimal	Valor da BC do ICMS na UF de destino.
`items[].tax.icmsDestination.pFCPUFDest`	`pFCPUFDest`	decimal	Percentual do FCP devido à UF de destino.
`items[].tax.icmsDestination.pICMSUFDest`	`pICMSUFDest`	decimal	Alíquota interna na UF de destino.
`items[].tax.icmsDestination.pICMSInter`	`pICMSInter`	decimal	Alíquota interestadual aplicável entre as UF de origem e destino.
`items[].tax.icmsDestination.pICMSInterPart`	`pICMSInterPart`	decimal	Percentual provisório de partilha do ICMS interestadual (atualmente 100% à UF de destino).
`items[].tax.icmsDestination.vFCPUFDest`	`vFCPUFDest`	decimal	Valor do FCP devido à UF de destino.
`items[].tax.icmsDestination.vICMSUFDest`	`vICMSUFDest`	decimal	Valor do ICMS de partilha devido à UF de destino.
`items[].tax.icmsDestination.vICMSUFRemet`	`vICMSUFRemet`	decimal	Valor do ICMS de partilha devido à UF do remetente.
`items[].tax.icmsDestination.vBCFCPUFDest`	`vBCFCPUFDest`	decimal	Valor da BC do FCP na UF de destino.

12.9. Item — Imposto Seletivo (`IS`)

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.IS.situationCode`	`CSTIS`	string	3 dígitos.
`items[].tax.IS.classificationCode`	`cClassTribIS`	string	6 dígitos.
`items[].tax.IS.basis`	`vBCIS`	decimal	13.2.
`items[].tax.IS.rate`	`pIS`	decimal	Até 4 casas.
`items[].tax.IS.unitRate`	`pISEspec`	decimal	Alíquota específica por unidade.
`items[].tax.IS.unit`	`uTrib`	string	Unidade tributável.
`items[].tax.IS.quantity`	`qTrib`	decimal	Quantidade tributável do Imposto Seletivo.
`items[].tax.IS.amount`	`vIS`	decimal	Valor do Imposto Seletivo.

12.10. Item — IBS/CBS (`IBSCBS`)

Raiz e jurisdições

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.IBSCBS.situationCode`	`CST` (em `IBSCBS`)	string	Código de Situação Tributária do IBS/CBS (3 dígitos). Ver §10.
`items[].tax.IBSCBS.classCode`	`cClassTrib`	string	Código de classificação tributária do IBS/CBS. Ver §10.
`items[].tax.IBSCBS.donationIndicator`	`indDoacao`	string	Indicador de doação a ente governamental. Ver §4.6.1.
`items[].tax.IBSCBS.basis`	`vBC` (em `IBSCBS`)	decimal	Base de cálculo do IBS/CBS.
`items[].tax.IBSCBS.state.rate`	`pIBSUF`	decimal	Alíquota do IBS da UF (%).
`items[].tax.IBSCBS.state.amount`	`vIBSUF`	decimal	Valor do IBS da UF.
`items[].tax.IBSCBS.municipal.rate`	`pIBSMun`	decimal	Alíquota do IBS do município (%).
`items[].tax.IBSCBS.municipal.amount`	`vIBSMun`	decimal	Valor do IBS do município.
`items[].tax.IBSCBS.cbs.rate`	`pCBS`	decimal	Alíquota da CBS (%).
`items[].tax.IBSCBS.cbs.amount`	`vCBS`	decimal	Valor da CBS.
`items[].tax.IBSCBS.ibsTotalAmount`	`vIBSTot`	decimal	Valor total do IBS (UF + município).

Subgrupos por jurisdição (`state`/`municipal`/`cbs`)

Caminho JSON	Tag XML	Tipo	Observações
`*.deferment.rate`	`pDif`	decimal	Percentual do diferimento aplicado à jurisdição. Ver §4.4.1.
`*.deferment.amount`	`vDif`	decimal	Valor do tributo diferido.
`*.reduction.rateReduction`	`pRedAliq`	decimal	Percentual de redução da alíquota. Ver §4.4.2.
`*.reduction.effectiveRate`	`pAliqEfet`	decimal	Alíquota efetiva após a redução.
`*.returnedAmount.amount`	`vDevTrib`	decimal	Valor do tributo devolvido ao contribuinte. Ver §4.4.3.

Subgrupos especiais (raiz `IBSCBS`)

Cada subgrupo é um objeto com múltiplos campos; consulte a seção de referência indicada para o detalhamento de cada propriedade.

Caminho JSON	Tag XML	Tipo	Observações
`items[].tax.IBSCBS.regularTaxation.*`	`gTribRegular`	object	Tributação regular hipotética (informativa). Ver §4.5.6.
`items[].tax.IBSCBS.governmentPurchase.*`	`gIBSCBS_CompraGov`	object	Composição em compras governamentais. Ver §4.5.5.
`items[].tax.IBSCBS.monophase.standart.*`	`gMonofasicoPadrao`	object	Tributação monofásica padrão. Ver §4.5.1.
`items[].tax.IBSCBS.monophase.withholding.*`	`gMonofasicoRetido`	object	Monofásico com retenção. Ver §4.5.1.
`items[].tax.IBSCBS.monophase.previouslyWithheld.*`	`gMonofasicoRetidoAnt`	object	Monofásico retido anteriormente. Ver §4.5.1.
`items[].tax.IBSCBS.monophase.deferment.*`	`gMonofasicoDif`	object	Monofásico com diferimento. Ver §4.5.1.
`items[].tax.IBSCBS.creditTransfer.*`	`gTransfCred`	object	Transferência de crédito. Ver §4.5.3.
`items[].tax.IBSCBS.operationalPresumedCredit.*`	`gCredPresOper`	object	Crédito presumido operacional. Ver §4.5.2.
`items[].tax.IBSCBS.creditReversal.*`	`gEstornoCred`	object	Estorno de crédito. Ver §4.5.4.
`items[].tax.IBSCBS.zfmPresumedCredit.*`	`gCredPresIBSZFM`	object	Crédito presumido da Zona Franca de Manaus. Ver §4.5.7.
`items[].competenceAdjustment.*`	`gAjusteCompet`	object	Ajuste de competência. Ver §4.6.2.

12.11. Totais (`total`)

Caminho JSON	Tag XML	Tipo	Observações
`totals.icms.baseTax`	`vBC`	decimal	Base de cálculo do ICMS (soma dos itens).
`totals.icms.icmsAmount`	`vICMS`	decimal	Valor total do ICMS.
`totals.icms.icmsExemptAmount`	`vICMSDeson`	decimal	Valor total do ICMS desonerado.
`totals.icms.stCalculationBasisAmount`	`vBCST`	decimal	Base de cálculo do ICMS ST.
`totals.icms.stAmount`	`vST`	decimal	Valor total do ICMS ST.
`totals.icms.productAmount`	`vProd`	decimal	Valor total dos produtos e serviços.
`totals.icms.freightAmount`	`vFrete`	decimal	Valor total do frete.
`totals.icms.insuranceAmount`	`vSeg`	decimal	Valor total do seguro.
`totals.icms.discountAmount`	`vDesc`	decimal	Valor total dos descontos.
`totals.icms.iiAmount`	`vII`	decimal	Valor total do Imposto de Importação.
`totals.icms.ipiAmount`	`vIPI`	decimal	Valor total do IPI.
`totals.icms.pisAmount`	`vPIS`	decimal	Valor total do PIS.
`totals.icms.cofinsAmount`	`vCOFINS`	decimal	Valor total do COFINS.
`totals.icms.othersAmount`	`vOutro`	decimal	Outras despesas acessórias.
`totals.icms.invoiceAmount`	`vNF`	decimal	Valor total da NF-e.
`totals.icms.fcpufDestinationAmount`	`vFCPUFDest`	decimal	Valor total do FCP devido à UF de destino.
`totals.icms.icmsufDestinationAmount`	`vICMSUFDest`	decimal	Valor total do ICMS de partilha para a UF de destino.
`totals.icms.icmsufSenderAmount`	`vICMSUFRemet`	decimal	Valor total do ICMS de partilha para a UF do remetente.
`totals.icms.federalTaxesAmount`	`vTotTrib`	decimal	Valor aproximado total de tributos (federais, estaduais e municipais).
`totals.icms.fcpAmount`	`vFCP`	decimal	Valor total do FCP.
`totals.icms.fcpstAmount`	`vFCPST`	decimal	Valor total do FCP retido por ST.
`totals.icms.fcpstRetAmount`	`vFCPSTRet`	decimal	Valor total do FCP retido anteriormente por ST.
`totals.icms.ipiDevolAmount`	`vIPIDevol`	decimal	Valor total do IPI devolvido.
`totals.issqn.baseRateISS`	`vBC` (em `ISSQNtot`)	decimal	Base de cálculo do ISSQN.
`totals.issqn.totalISS`	`vISS`	decimal	Valor total do ISSQN.
`totals.withheldTaxes.pisAmount`	`vRetPIS`	decimal	Valor do PIS retido por substituição.
`totals.withheldTaxes.cofinsAmount`	`vRetCOFINS`	decimal	Valor do COFINS retido por substituição.
`totals.withheldTaxes.csllAmount`	`vRetCSLL`	decimal	Valor da CSLL retida.
`totals.withheldTaxes.irrfBasis`	`vBCIRRF`	decimal	Base de cálculo do IRRF.
`totals.withheldTaxes.irrfAmount`	`vIRRF`	decimal	Valor do IRRF retido.
`totals.withheldTaxes.socialSecutiryBasis`	`vBCRetPrev`	decimal	Base de cálculo da retenção da Previdência Social.
`totals.withheldTaxes.socialSecutiryAmount`	`vRetPrev`	decimal	Valor da retenção da Previdência Social.
`totals.isTotals.amount`	`vIS` (em `ISTot`)	decimal	Valor total do Imposto Seletivo.
`totals.ibsCbsTotals.basis`	`vBCIBSCBS`	decimal	Base de cálculo total do IBS/CBS.
`totals.ibsCbsTotals.ibs.state.amount`	`vIBSUF` (em totais)	decimal	Valor total do IBS da UF.
`totals.ibsCbsTotals.ibs.municipal.amount`	`vIBSMun` (em totais)	decimal	Valor total do IBS do município.
`totals.ibsCbsTotals.ibs.totalAmount`	`vIBS` (em `IBSCBSTot`)	decimal	Valor total do IBS (UF + município).
`totals.ibsCbsTotals.cbs.amount`	`vCBS` (em totais)	decimal	Valor total da CBS.
`totals.totalInvoiceAmount`	`vNFTot`	decimal	Valor total da NF-e considerando IBS/CBS/IS.

12.12. Transporte (`transp`)

Caminho JSON	Tag XML	Tipo	Observações
`transport.freightModality`	`modFrete`	enum	Modalidade do frete. Ver §11.6.1.
`transport.transportGroup.name`	`xNome`	string	Razão social ou nome do transportador.
`transport.transportGroup.federalTaxNumber`	`CNPJ`/`CPF`	int	CNPJ ou CPF do transportador.
`transport.transportGroup.stateTaxNumber`	`IE`	string	Inscrição estadual do transportador.
`transport.transportGroup.address.*`	(subcampos `transporta`)	object	Endereço do transportador (`xEnder`, `xMun`, `UF`).
`transport.transportVehicle.plate`	`placa`	string	Placa do veículo de transporte.
`transport.transportVehicle.state`	`UF`	string	UF de registro do veículo.
`transport.transportVehicle.rntc`	`RNTC`	string	Registro Nacional de Transportador de Carga (ANTT).
`transport.reboque.plate`	`placa` (em `reboque`)	string	Placa do reboque.
`transport.reboque.uf`	`UF` (em `reboque`)	string	UF de registro do reboque.
`transport.reboque.rntc`	`RNTC` (em `reboque`)	string	RNTC do reboque.
`transport.reboque.wagon`	`vagao`	string	Identificação do vagão (transporte ferroviário).
`transport.reboque.ferry`	`balsa`	string	Identificação da balsa.
`transport.volume.volumeQuantity`	`qVol`	int	Quantidade de volumes transportados.
`transport.volume.species`	`esp`	string	Espécie dos volumes transportados.
`transport.volume.brand`	`marca`	string	Marca dos volumes transportados.
`transport.volume.volumeNumeration`	`nVol`	string	Numeração dos volumes transportados.
`transport.volume.netWeight`	`pesoL`	decimal	Peso líquido (kg).
`transport.volume.grossWeight`	`pesoB`	decimal	Peso bruto (kg).
`transport.sealNumber`	`nLacre`	string	Número dos lacres.
`transport.transpRate.serviceAmount`	`vServ`	decimal	Valor do serviço de transporte (retenção do ICMS do transporte).
`transport.transpRate.bcRetentionAmount`	`vBCRet`	decimal	Base de cálculo da retenção do ICMS do transporte.
`transport.transpRate.icmsRetentionRate`	`pICMSRet`	decimal	Alíquota da retenção do ICMS do transporte.
`transport.transpRate.icmsRetentionAmount`	`vICMSRet`	decimal	Valor do ICMS retido do transporte.
`transport.transpRate.cfop`	`CFOP` (em `retTransp`)	int	CFOP do serviço de transporte.
`transport.transpRate.cityGeneratorFactCode`	`cMunFG` (em `retTransp`)	int	Código IBGE do município de ocorrência do fato gerador do ICMS do transporte.

12.13. Pagamento (`pag`)

Caminho JSON	Tag XML	Tipo	Observações
`payment[].paymentDetail[].method`	`tPag`	enum	Forma de pagamento. Ver §11.5.1.
`payment[].paymentDetail[].methodDescription`	`xPag`	string	Descrição da forma de pagamento (obrigatória quando `tPag=99`/outros).
`payment[].paymentDetail[].paymentType`	`indPag`	enum	Indicador da forma de pagamento (à vista/a prazo). Ver §11.5.2.
`payment[].paymentDetail[].amount`	`vPag`	decimal	Valor do pagamento.
`payment[].paymentDetail[].paymentDate`	`dPag`	datetime	Data do pagamento.
`payment[].paymentDetail[].federalTaxNumberPag`	`CNPJPag`	string	CNPJ do estabelecimento beneficiário do pagamento.
`payment[].paymentDetail[].statePag`	`UFPag`	string	UF do beneficiário do pagamento.
`payment[].paymentDetail[].card.federalTaxNumber`	`CNPJ` (em `card`)	string	CNPJ da credenciadora de cartão de crédito/débito.
`payment[].paymentDetail[].card.flag`	`tBand`	enum	Bandeira do cartão. Ver §11.5.4.
`payment[].paymentDetail[].card.authorization`	`cAut`	string	Número de autorização da operação com cartão.
`payment[].paymentDetail[].card.integrationPaymentType`	`tpIntegra`	enum	Tipo de integração do pagamento com o sistema de automação. Ver §11.5.3.
`payment[].payBack`	`vTroco`	decimal	Valor do troco.

12.14. Cobrança (`cobr`)

Caminho JSON	Tag XML	Tipo	Observações
`billing.bill.number`	`nFat`	string	Número da fatura.
`billing.bill.originalAmount`	`vOrig`	decimal	Valor original da fatura.
`billing.bill.discountAmount`	`vDesc`	decimal	Valor do desconto da fatura.
`billing.bill.netAmount`	`vLiq`	decimal	Valor líquido da fatura.
`billing.duplicates[].number`	`nDup`	string	Número da duplicata/parcela.
`billing.duplicates[].expirationOn`	`dVenc`	datetime	Data de vencimento da duplicata.
`billing.duplicates[].amount`	`vDup`	decimal	Valor da duplicata.

12.15. Informações Adicionais (`infAdic`)

Caminho JSON	Tag XML	Tipo	Observações
`additionalInformation.fisco`	`infAdFisco`	string	Informações adicionais de interesse do Fisco.
`additionalInformation.taxpayer`	`infCpl`	string	Informações complementares de interesse do contribuinte.
`additionalInformation.xmlAuthorized[]`	`autXML/CNPJ`/`CPF`	int array	CNPJ/CPF autorizados a acessar o XML da NF-e.
`additionalInformation.taxDocumentsReference[].documentElectronicInvoice.accessKey`	`refNFe`	string	Chave de acesso da NF-e referenciada.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.federalTaxNumber`	`refNF/CNPJ`	string	CNPJ do emitente da NF (modelo 1/1A) referenciada.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.state`	`refNF/cUF`	int	Código da UF do emitente da NF referenciada.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.yearMonth`	`refNF/AAMM`	string	Ano e mês (AAMM) de emissão da NF referenciada.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.model`	`refNF/mod`	string	Modelo do documento fiscal referenciado.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.series`	`refNF/serie`	string	Série da NF referenciada.
`additionalInformation.taxDocumentsReference[].documentInvoiceReference.number`	`refNF/nNF`	string	Número da NF referenciada.
`additionalInformation.taxDocumentsReference[].taxCouponInformation.modelDocumentFiscal`	`refECF/mod`	string	Modelo do Cupom Fiscal (ECF) referenciado.
`additionalInformation.taxDocumentsReference[].taxCouponInformation.orderECF`	`refECF/nECF`	string	Número de ordem sequencial do ECF.
`additionalInformation.taxDocumentsReference[].taxCouponInformation.orderCountOperation`	`refECF/nCOO`	int	Número do Contador de Ordem de Operação (COO).
`additionalInformation.advancePayment[].accessKey`	`gPagAntecipado/refNFe`	string	Chave de acesso de NF-e de pagamento antecipado.
`additionalInformation.taxpayerComments[].field`	`obsCont/xCampo`	string	Identificação do campo livre do contribuinte.
`additionalInformation.taxpayerComments[].text`	`obsCont/xTexto`	string	Conteúdo do campo livre do contribuinte.
`additionalInformation.referencedProcess[].identifierConcessory`	`nProc`	string	Identificador do processo ou ato concessório.
`additionalInformation.referencedProcess[].identifierOrigin`	`indProc`	int	Origem do processo (SEFAZ, Justiça Federal/Estadual, Secex/RFB, outros).
`additionalInformation.referencedProcess[].concessionActType`	`tpAto`	int	Tipo de ato concessório.

12.16. Compra, Exportação e Intermediário

Caminho JSON	Tag XML	Tipo	Observações
`purchaseInformation.commitmentNote`	`xNEmp`	string	Nota de empenho (compras públicas).
`purchaseInformation.purchaseOrder`	`xPed` (em `compra`)	string	Número do pedido de compra.
`purchaseInformation.contractNumber`	`xCont`	string	Número do contrato.
`export.state`	`UFSaidaPais`	enum	UF de embarque ou de transposição de fronteira.
`export.office`	`xLocExporta`	string	Local de embarque ou de despacho da exportação.
`export.local`	`xLocDespacho`	string	Descrição do local de despacho.
`transactionIntermediate.federalTaxNumber`	`CNPJ` (em `infIntermed`)	int	CNPJ do intermediador da transação (ex.: marketplace).
`transactionIntermediate.identifier`	`idCadIntTran`	string	Identificador do intermediador no portal do marketplace.
`issuerTaxSubstitute.stStateTaxNumber`	`IEST`	string	Inscrição estadual do substituto tributário na UF de destino.

12.17. Item — Subgrupos Especiais (DI, Combustível, Veículo)

Caminho JSON	Tag XML	Tipo	Observações
`items[].importDeclarations[].code`	`nDI`	string	Número da Declaração de Importação (DI/DSI/DA).
`items[].importDeclarations[].registeredOn`	`dDI`	datetime	Data de registro da DI.
`items[].importDeclarations[].customsClearanceName`	`xLocDesemb`	string	Local de desembaraço aduaneiro.
`items[].importDeclarations[].customsClearanceState`	`UFDesemb`	enum	UF onde ocorreu o desembaraço aduaneiro.
`items[].importDeclarations[].customsClearancedOn`	`dDesemb`	datetime	Data do desembaraço aduaneiro.
`items[].importDeclarations[].afrmmAmount`	`vAFRMM`	decimal	Valor do AFRMM (Adicional ao Frete para Renovação da Marinha Mercante).
`items[].importDeclarations[].internationalTransport`	`tpViaTransp`	enum	Via de transporte internacional. Ver §11.6.3.
`items[].importDeclarations[].intermediation`	`tpIntermedio`	enum	Forma de importação quanto à intermediação. Ver §11.6.2.
`items[].importDeclarations[].acquirerFederalTaxNumber`	`CNPJ`/`CPF`	string	CNPJ/CPF do adquirente ou encomendante.
`items[].importDeclarations[].stateThird`	`UFTerceiro`	string	UF do adquirente ou encomendante.
`items[].importDeclarations[].exporter`	`cExportador`	string	Código do exportador (usado pelo importador nos seus controles).
`items[].importDeclarations[].additions[].code`	`nAdicao`	int	Número sequencial da adição.
`items[].importDeclarations[].additions[].manufacturer`	`cFabricante`	string	Código do fabricante estrangeiro (controle do importador).
`items[].importDeclarations[].additions[].amount`	`vDescDI`	decimal	Valor do desconto da adição.
`items[].importDeclarations[].additions[].drawback`	`nDraw`	int	Número do ato concessório de Drawback.
`items[].fuelDetail.codeANP`	`cProdANP`	string	Código do produto conforme tabela da ANP.
`items[].fuelDetail.descriptionANP`	`descANP`	string	Descrição do produto conforme a ANP.
`items[].fuelDetail.percentageNG`	`pMixGN`	decimal	Percentual de gás natural no produto GLP (mistura).
`items[].fuelDetail.percentageGLP`	`pGLP`	decimal	Percentual do GLP derivado do petróleo.
`items[].fuelDetail.percentageNGn`	`pGNn`	decimal	Percentual de gás natural nacional.
`items[].fuelDetail.percentageGNi`	`pGNi`	decimal	Percentual de gás natural importado.
`items[].fuelDetail.startingAmount`	`vPart`	decimal	Valor de partida (`pGLP` × valor de venda).
`items[].fuelDetail.codif`	`CODIF`	string	Código de autorização/registro no CODIF.
`items[].fuelDetail.amountTemp`	`qTemp`	decimal	Quantidade de combustível faturada à temperatura ambiente.
`items[].fuelDetail.stateBuyer`	`UFCons`	string	UF de consumo do combustível.
`items[].fuelDetail.cide.bc`	`qBCProd`	decimal	Base de cálculo da CIDE (quantidade comercializada).
`items[].fuelDetail.cide.rate`	`vAliqProd`	decimal	Alíquota da CIDE em valor por unidade (R$).
`items[].fuelDetail.cide.cideAmount`	`vCIDE`	decimal	Valor da CIDE.
`items[].fuelDetail.pump.spoutNumber`	`nBico`	int	Número do bico utilizado no abastecimento.
`items[].fuelDetail.pump.number`	`nBomba`	int	Número da bomba ao qual o bico está interligado.
`items[].fuelDetail.pump.tankNumber`	`nTanque`	int	Número do tanque ao qual o bico está interligado.
`items[].fuelDetail.pump.beginningAmount`	`vEncIni`	decimal	Valor do encerrante no início do abastecimento.
`items[].fuelDetail.pump.endAmount`	`vEncFin`	decimal	Valor do encerrante no final do abastecimento.
`items[].vehicleDetail.*`	`veicProd/*` (campos J02–J26)	object	Dados do veículo novo (chassi, cor, potência, etc.). Ver §6.22.

12.18. Resposta — Identificadores e Status

Os campos a seguir são preenchidos pelo servidor e retornados nos endpoints de consulta. Não devem ser enviados na requisição.

Caminho JSON	Tag XML	Tipo	Observações
`id`	(interno)	string	Identificador interno do recurso na NFe.io.
`status`	`cStat`	enum	Status da NF-e. Ver §11.8.1.
`authorization.receiptOn`	`dhRecbto`	datetime	Data/hora do processamento pela SEFAZ.
`authorization.accessKey`	`chNFe`	string	Chave de acesso da NF-e (44 dígitos).
`authorization.message`	`xMsg`	string	Mensagem complementar retornada pela SEFAZ.
`authorization.description`	`xMotivo`	string	Descrição do motivo do status (`cStat`).
`contingencyDetails.authorizer`	(interno)	enum	Autorizador utilizado em contingência.
`contingencyDetails.startedOn`	(interno)	datetime	Data/hora de início da contingência.
`contingencyDetails.reason`	(interno)	string	Justificativa da entrada em contingência.
`lastEvents.events[]`	(interno)	array	Lista de eventos vinculados (cancelamento, CC-e, etc.).

Notas finais:

Os caminhos com * indicam que o subgrupo possui múltiplos campos com mesma estrutura — consulte a documentação específica do subgrupo (referenciada em §4.5 e §11).

Tags XML entre parênteses do tipo (em X) indicam que o tag tem o mesmo nome em vários grupos; o sufixo desambigua o grupo pai.

Para a relação completa entre cClassTrib (codClassTrib) e CST do IBS/CBS, consulte o Apêndice G (§10).

1. Introdução
2. Estrutura Geral da Requisição
3. Apêndice A: Mapeamento de Grupos Principais
4. Apêndice B: Estrutura Detalhada dos Novos Grupos da Reforma Tributária
5. Considerações Finais
6. Apêndice C: Detalhamento dos Objetos de Recurso
7. Apêndice D: Erros Comuns e Suas Soluções
- 7.1. Rejeições Gerais
- 7.2. Rejeições da Reforma Tributária (RTC)
9. Apêndice F: Boas Práticas para Integração
8. Apêndice E: Cancelamento, Inutilização e Devolução
10. Apêndice G: Tabela de Referência - CST e Classificação Tributária (IBS/CBS)
11. Apêndice H: Referência Completa de Enumerações (Enums)
12. Apêndice I: Mapeamento Propriedade-a-Propriedade (JSON ↔ XML SEFAZ)

1. Introdução​

1.1. Objetivo​

1.2. Documentos de Referência​

1.3. Conceitos Gerais​

2. Estrutura Geral da Requisição​

2.1. Grupo de Identificação da Nota Fiscal​

2.2. Grupo do Comprador (buyer)​

2.3. Grupos de Locais de Entrega e Retirada​

2.4. Grupo de Itens (items)​

2.4.1. Propriedades do Item​

2.4.2. Grupo de Tributos do Item (tax)​

2.5. Grupo de Transporte (transport)​

2.6. Grupo de Pagamento (payment)​

2.7. Grupo de Cobrança (billing)​

2.8. Grupo de Totais (totals)​

2.9. Grupo de Informações Adicionais (additionalInformation)​

2.10. Grupo do Emitente (issuer) — Resposta​

2.11. Grupo de Compras (purchaseInformation)​

2.12. Grupo de Exportação (export)​

2.13. Grupo do Intermediador da Transação (transactionIntermediate)​

2.14. Grupo de Contingência (contingencyOn / contingencyJustification)​

2.15. Subgrupos Especiais de Item​

2.15.1. vehicleDetail — Veículos Novos​

2.15.2. fuelDetail — Combustíveis​

2.15.3. presumedCredit — Crédito Presumido por Item (regime ICMS)​

2.15.4. importDeclarations — Declarações de Importação (DI)​

2.15.5. exportDetails — Detalhamento de Exportação por Item​

2.15.6. referencedDFe — Documento Fiscal Eletrônico Referenciado​

2.15.7. taxDetermination — Cálculo Automático de Impostos​

3. Apêndice A: Mapeamento de Grupos Principais​

4. Apêndice B: Estrutura Detalhada dos Novos Grupos da Reforma Tributária​

4.1. items.tax.IS​

4.2. items.tax.IBSCBS​

4.3. totals.isTotals e totals.ibsCbsTotals​

4.4. Subgrupos de Benefícios Fiscais do IBS/CBS​

4.4.1. deferment — Diferimento (gDif)​

4.4.2. reduction — Redução de Alíquota (gRed)​

4.4.3. returnedAmount — Devolução de Tributos (gDevTrib)​

4.5. Subgrupos Especiais do IBS/CBS​

4.5.1. monophase — Tributação Monofásica (gMonofasicoIBSCBS)​

4.5.2. operationalPresumedCredit — Crédito Presumido Operacional (gCredPresOper)​

4.5.3. creditTransfer — Transferência de Crédito (gTransfCred)​

4.5.4. creditReversal — Estorno de Crédito (gEstornoCred)​

4.5.5. governmentPurchase — Composição em Compras Governamentais (gCompraGov)​

4.5.6. regularTaxation — Tributação Regular Hipotética​

4.5.7. zfmPresumedCredit — Crédito Presumido ZFM (gCredPresIBSZFM)​

4.6. donationIndicator e competenceAdjustment​

4.6.1. donationIndicator — Indicador de Doação (indDoacao)​

4.6.2. competenceAdjustment — Ajuste de Competência (gAjusteCompet)​

5. Considerações Finais​

6. Apêndice C: Detalhamento dos Objetos de Recurso​

6.1. AddressResource​

6.2. BuyerResource​

6.3. DeliveryInformationResource​

6.4. WithdrawalInformationResource​

6.5. GovernmentPurchaseResource​

6.6. TransportInformationResource​

6.6.1. TransportGroupResource​

6.6.2. TransportVehicleResource​

6.6.3. ReboqueResource​

6.6.4. VolumeResource​

6.7. PaymentResource e PaymentDetailResource​

6.7.1. CardResource​

6.8. BillingResource​

6.8.1. BillResource​

6.8.2. DuplicateResource​

6.9. AdditionalInformationResource​

6.9.1. TaxDocumentsReferenceResource​

6.9.2. ReferencedProcessResource​

6.10. InvoiceItemResource​

6.11. InvoiceItemTaxResource​

6.11.1. IcmsTaxResource​

6.11.2. IPITaxResource​

6.11.3. PISTaxResource e CofinsTaxResource​

6.12. ISTaxResource​

6.13. IBSCBSTaxResource​

6.13.1. IBSStateTaxResource e IBSMunicipalTaxResource​

6.13.2. CBSTaxResource​

6.14. Total (Schema de Totais)​

6.14.1. ICMSTotal​