Endpoints NF-e / NFC-e

Referência completa dos endpoints para emissão, cancelamento, carta de correção (CC-e), inutilização de numeração, consulta de status e download do DANFE e XML. Todos os endpoints usam o prefixo https://platform.notaas.com.br/api/v1 e requerem x-api-key.

Emissão

POST/nfe/emitir🔑 x-api-key

Enfileira uma NF-e ou NFC-e para emissão assíncrona via SEFAZ. Retorna 202 com invoiceId para polling.

Body (JSON)

Campo	Tipo	Req?	Descrição
modelo	number	não	55 para NF-e, 65 para NFC-e (padrão: 55). Para projetos de Produtor Rural Pessoa Física (CPF), apenas o modelo 55 é permitido.
serie	number	não	Série da nota fiscal. Para emitente CNPJ (procEmi=0): faixa 1 a 889 (padrão do projeto: 1). Para Produtor Rural Pessoa Física (CPF, procEmi=0): faixa obrigatória 920 a 969 conforme NT 2018.001 (padrão do projeto: 920). Quando omitido, utiliza a série padrão configurada no projeto.
naturezaOperacao	string	sim	Descrição da operação fiscal (ex: "Venda de mercadoria", "Venda de producao do estabelecimento")
dataEmissao	string	não	Data/hora de emissão (competência fiscal). Aceita "YYYY-MM-DD" ou ISO 8601 completo (ex: "2026-08-31T23:59:59-03:00"). Para "YYYY-MM-DD": data passada → fixada às 12:00:00 (horário de Brasília); data de hoje → usa o horário atual da transmissão em Brasília (nunca 12:00:00 se isso cair no futuro), garantindo que emissões no início do dia não sejam rejeitadas; data futura → também fixada às 12:00:00, sujeita à tolerância máxima de 5 minutos. Retroatividade de até 30 dias é permitida para NF-e mod. 55 (fechamento contábil); NFC-e mod. 65 tolera no máximo 5 min de atraso. Tolerância de 5 min no futuro para ambos os modelos. Alias técnico: dhEmi. Padrão: agora.
dataSaida (ou dhSaiEnt)	string	não	Data/hora de saída ou de entrada da mercadoria/produto (tag <dhSaiEnt> / campo B10 do MOC 7.0). Opcional e exclusivo para NF-e (modelo 55); proibido em NFC-e (modelo 65 — Regra B10-10 / Rejeição 705). Aceita "YYYY-MM-DD" ou ISO 8601 completo (ex: "2026-10-20T18:00:00-03:00"). Para "YYYY-MM-DD": usa 12:00:00 (horário de Brasília) em datas passadas/futuras ou min(agora, 12:00:00 BRT) quando a data é hoje; sempre que coincidir com o mesmo dia civil de dataEmissao (dhEmi) em Brasília e o instante base ficar anterior a dhEmi, é elevado para dhEmi. Regras SEFAZ validadas antes do enfileiramento: janela máxima de ±30 dias em relação à transmissão (Regras B10-20 / Rej. 504 e B10-30 / Rej. 505) e, para notas de saída (tipoOperacao=1), não pode ser anterior à data/hora de emissão (Regra B10-40 / Rej. 506). Quando informada, é impressa nos quadros de Data/Hora de Saída/Entrada do DANFE. Aliases aceitos: dataSaida, dhSaiEnt, dataSaidaEntrada, data_saida, data_saida_entrada, dh_sai_ent.
dest	object	sim	Dados do destinatário (obrigatório para NF-e mod. 55)
dest.cnpj / dest.cpf	string	não	CNPJ (14 posições: numérico tradicional \d{14} ou alfanumérico [0-9A-Z]{12}\d{2} conforme IN RFB nº 2.229/2024 e NT Conjunta 2025.001, com ou sem máscara SS.SSS.SSS/SSSS-DD) ou CPF (11 dígitos). Obrigatório para destinatários no Brasil. Não deve ser enviado se destinatário for no exterior.
dest.idEstrangeiro	string	não	Número do passaporte ou documento de identificação do comprador estrangeiro (1 a 20 caracteres alfanuméricos). Obrigatório para destinatário no exterior (idDest=3). Aliases aceitos: id_estrangeiro, passaporte, documentoEstrangeiro.
dest.nome	string	sim	Razão social / nome completo do destinatário (mínimo 2 caracteres, máx. 60)
dest.ie	string	não	Inscrição Estadual (se contribuinte; omitir se isento/não-contribuinte). Não deve ser enviado para destinatário no exterior.
dest.indicadorIE	number	não	1=Contribuinte, 2=Isento, 9=Não contribuinte. Auto-inferido de dest.ie quando omitido. Para destinatário no exterior (idDest=3), deve ser obrigatoriamente 9.
dest.email	string	não	E-mail do destinatário para envio do XML e DANFE
dest.endereco.logradouro	string	sim	Logradouro do destinatário
dest.endereco.numero	string	não	Número (padrão: "SN")
dest.endereco.complemento	string	não	Complemento
dest.endereco.bairro	string	sim	Bairro
dest.endereco.codigoMunicipio	number	não	Código IBGE do município (7 dígitos, ex: 4106902). Obrigatório para endereços no Brasil; no exterior (UF="EX"), preenchido automaticamente como 9999999.
dest.endereco.cidade	string	não	Nome do município (obrigatório no Brasil; no exterior fixado como "EXTERIOR").
dest.endereco.uf	string	sim	Sigla do estado (ex: "PR", "SP") ou "EX" para destinatário no exterior.
dest.endereco.cep	string	não	CEP (apenas dígitos no Brasil; opcional no exterior).
dest.endereco.pais	object \| string \| number	não	Dados do país do destinatário no exterior (obrigatório quando UF="EX" ou idDest=3). Pode ser enviado como objeto estruturado contendo codigo e nome, ou diretamente como atalho (código numérico BACEN ou nome do país).
dest.endereco.pais.codigo	number	não	Código numérico do país na tabela oficial do BACEN (ex: 2496 para EUA, 1600 para Reino Unido). Obrigatório no exterior (UF="EX"). Aliases aceitos na raiz de endereco: codigoPais, cPais, paisCodigo.
dest.endereco.pais.nome	string	não	Nome por extenso do país (ex: "ESTADOS UNIDOS", de 2 a 60 caracteres). Obrigatório no exterior (UF="EX"). Aliases aceitos na raiz de endereco: nomePais, xPais, paisNome.
items[]	array	sim	Array de itens/produtos da nota (mínimo 1)
items[].descricao	string	sim	Descrição do produto (alias: items[].xProd)
items[].codigo	string	não	Código interno do produto (padrão: "PRD001", alias: items[].cProd)
items[].ncm	string	sim	NCM — 8 dígitos (ex: "61091000")
items[].cfop	string	sim	CFOP — 4 dígitos (ex: "5102")
items[].quantidade	number	não	Quantidade comercial (padrão: 1, alias: items[].qCom)
items[].valorUnitario	number	não	Valor unitário em reais (padrão: valorTotal, alias: items[].vUnCom)
items[].valorTotal	number	sim	Valor total bruto do item em reais (deve ser > 0, alias: items[].vProd)
items[].unidade	string	não	Unidade comercial (padrão: "UN", alias: items[].uCom)
items[].ean	string	não	EAN/GTIN do produto (omitir para "SEM GTIN", alias: items[].cEAN)
items[].origem (ou orig)	number	não	Origem da mercadoria conforme Tabela A do ICMS (tag <orig> / campo N11 do MOC 7.0 — o valor recebido é convertido via Number(rawOrig) e aceito se resultar em inteiro de 0 a 8, como números 0..8 ou strings numéricas "0".."8"; quando omitido ou quando Number(rawOrig) não produzir inteiro no intervalo 0–8, assume fallback legado 0): 0 = Nacional (exceto códigos 3, 4, 5 e 8); 1 = Estrangeira — Importação direta (exceto código 6); 2 = Estrangeira — Adquirida no mercado interno (exceto código 7); 3 = Nacional, mercadoria ou bem com conteúdo de importação superior a 40% e inferior ou igual a 70%; 4 = Nacional, cuja produção tenha sido feita em conformidade com os processos produtivos básicos (PPB); 5 = Nacional, mercadoria ou bem com conteúdo de importação inferior ou igual a 40%; 6 = Estrangeira — Importação direta, sem similar nacional, constante em lista da CAMEX e gás natural; 7 = Estrangeira — Adquirida no mercado interno, sem similar nacional, constante em lista da CAMEX e gás natural; 8 = Nacional, mercadoria ou bem com conteúdo de importação superior a 70%. Aliases: items[].origem, items[].orig.
items[].cst	string	não	CST do ICMS para CRT 2 ou 3 (ex: "00", "20", "40", "41", "51", "60", "70", "90"). Contrato: omitir ou enviar vazio ("") usa o padrão do regime ("00"); valor informado deve ter até 2 dígitos numéricos — valor não numérico (ex: "abc") ou com dígitos além do tamanho retorna HTTP 400 e NÃO recebe default.
items[].csosn	string	não	CSOSN do ICMS para CRT 1 ou 4 / Simples Nacional e MEI (NF-e: "102", "300", "400", "900" \| NFC-e: "102", "300"). Exclusivo com cst. Contrato: omitir ou enviar vazio ("") usa o padrão do regime ("400" no SN, "102" no MEI); valor informado deve ter até 3 dígitos numéricos — valor não numérico ou com dígitos além do tamanho retorna HTTP 400 e NÃO recebe default.
items[].aliquotaIcms	number	não	Alíquota ICMS em % — obrigatório para CST 00, 10 e 20; opcional para CST 51 (quando omitida, assume default 12%) (alias: items[].pICMS)
items[].percentualReducaoBc	number	não	Percentual de redução da base de cálculo do ICMS (%). Obrigatório para CST 20 (> 0 e < 100); opcional para CST 51 (> 0 e < 100 quando percentualDiferimento / pDif for informado) e CST 70 (> 0 e < 100 quando informado; omitir para 0). Rejeitado para outros CSTs ou CSOSN do Simples Nacional. Aliases: items[].pRedBC, items[].predbc, items[].percentual_reducao_bc.
items[].percentualDiferimento (ou pDif)	number	não	Percentual do diferimento do ICMS (% — de 0 a 100, até 4 casas decimais). Exclusivo de CST 51 (Grupo N07 — Diferimento total ou parcial). Obrigatório em CST 51 sempre que percentualReducaoBc, cBenefRBC, valorIcmsOperacao ou valorIcmsDiferido forem informados. Se omitido em CST 51 (sem esses subcampos), a plataforma preserva o caminho legado de compatibilidade (<orig>, <CST>51</CST>, <modBC>3</modBC>, <vBC>, <pICMS>, <vICMS>). Aliases: items[].pDif, items[].pdif, items[].percentual_diferimento.
items[].valorIcmsOperacao (ou vICMSOp)	number	não	Valor do ICMS da operação como se não houvesse diferimento, em reais (>= 0). Exclusivo de CST 51 com percentualDiferimento informado. Opcional: calculado automaticamente pela plataforma como round2(vBC × pICMS / 100) e validado com tolerância máxima de ±R$ 0,01 (Regra SEFAZ N16a-10 / Rejeição 351). Aliases: items[].vICMSOp, items[].vicmsop, items[].valor_icms_operacao.
items[].valorIcmsDiferido (ou vICMSDif)	number	não	Valor da parcela do ICMS diferida, em reais (>= 0). Exclusivo de CST 51 com percentualDiferimento informado. Opcional: calculado automaticamente pela plataforma como round2(vICMSOp × pDif / 100) e validado com tolerância máxima de ±R$ 0,01 (Regra SEFAZ N16c-10 / Rejeição 352). O ICMS efetivamente devido no item é derivado como vICMS = round2(vICMSOp - vICMSDif) (Regra N17-10 / Rejeição 353) e somado em <ICMSTot><vICMS>. Aliases: items[].vICMSDif, items[].vicmsdif, items[].valor_icms_diferido.
items[].cBenefRBC	string	não	Código de Benefício Fiscal na UF aplicado à Redução de Base de Cálculo acumulada com Diferimento (exatamente 8 ou 10 caracteres sem espaços, ex: "SP123456"). Exclusivo de CST 51 quando percentualReducaoBc > 0 e percentualDiferimento forem informados. Aliases: items[].codigoBeneficioReducaoBc, items[].cbenefrbc.
items[].aliquotaIcmsUfDest	number	não	Override setorial da alíquota interna do ICMS na UF de destino (%, DIFAL). >= 0 e < 100. Quando omitido, a API usa a alíquota modal padrão da UF. Aliases: items[].pICMSUFDest, items[].aliqInternaDestino, items[].aliquotaInternaDestino.
items[].percentualFcpUfDest	number	não	Override do percentual de FCP da UF de destino (%, DIFAL). >= 0 e <= 100. Quando omitido, a API usa o FCP padrão da UF. Aliases: items[].pFCPUFDest, items[].fcpDestino, items[].percentualFcpDestino.
items[].aliquotaInterestadual	number	não	Override da alíquota interestadual (%, DIFAL) — ex: 4 (importados), 7 ou 12. >= 0 e < 100. Quando omitido, a API resolve automaticamente pela regra NA09-30 (origem × destino). Aliases: items[].pICMSInter, items[].aliqInterestadual.
items[].gerarDifal	boolean	não	Override UNIDIRECIONAL do grupo ICMSUFDest (DIFAL) no item: false suprime o grupo em item tributado (decisão do emitente — risco de rejeição 694); true é aceito apenas como no-op em item tributado e é REJEITADO (HTTP 400) em item isento/imune/não tributado/suspenso (NA01-20, Exceção 10). Ausente = a matriz por CST/CSOSN decide. Aceita strings "true"/"false". Aliases: items[].gerarIcmsUfDest, items[].difal (aliases com valores divergentes são rejeitados).
items[].codigoBeneficioFiscal	string	não	Código de Benefício Fiscal na UF (ex: "SP070130", "PR800000"). Exigido para UFs/CSTs com benefício fiscal (ex: CST 41 em SP). Aceita também alias SEFAZ items[].cBenef.
items[].cest	string	não	CEST — Código Especificador da Substituição Tributária (7 dígitos, ex: "0300700"; aceita máscara "03.007.00", sanitizada automaticamente). Opcional no contrato da API — a validação local é apenas de formato. A SEFAZ o exige em operações com ICMS-ST / Substituição Tributária conforme a regra fiscal aplicável (ex: CFOP 5405, CST 10/30/60/70/90, CSOSN 201/202/203/500/900 — em CST/CSOSN 90, quando vICMSST for diferente de zero); a ausência nesses casos causa Rejeição 806. Aceita também alias items[].CEST.
items[].valorFrete	number	não	Valor do frete específico deste item em reais (alias: items[].vFrete ou items[].frete)
items[].valorSeguro	number	não	Valor do seguro específico deste item em reais (alias: items[].vSeg ou items[].seguro)
items[].desconto	number	não	Desconto do item em reais (alias: items[].vDesc)
items[].outrasDespesas	number	não	Outras despesas acessórias do item em reais (alias: items[].vOutro)
items[].valorTributos (ou vTotTrib)	number	não	Valor aproximado total de tributos federais, estaduais e municipais do item em reais (>= 0, até 2 casas decimais — tag <vTotTrib> em <det><imposto>, campo M02 do MOC 7.0 / Lei 12.741/2012, XSD TDec_1302). Opcional: quando informado no item, é serializado em <det><imposto><vTotTrib> e somado automaticamente pela API no totalizador da nota (<total><ICMSTot><vTotTrib>, campo W16a), garantindo conformidade com a Regra SEFAZ W16a-10 (Rejeição 685). Não altera <vNF>, <vItem> nem a base de cálculo de IBS/CBS. Quando omitido, utiliza o fallback da tabela IBPT por NCM (0.00 se não tabelado). Aliases flat no item: items[].valorTributos, items[].vTotTrib, items[].vTrib, items[].valorTributosAproximados, items[].valor_tributos, items[].valor_tributos_aproximados, items[].v_tot_trib, items[].v_trib. Aliases aninhados em items[].impostos ou items[].imposto: valorTributos, vTotTrib, vTrib, valorTributosAproximados, valor_tributos, valor_tributos_aproximados, v_tot_trib, v_trib.
items[].cstPis	string	não	CST do PIS (2 dígitos). Valores aceitos: "01", "02" (PISAliq), "04", "05", "06", "07", "08", "09" (PISNT), "49", "99" (PISOutr). Se omitido: assume "01" para CRT 3 (Regime Normal) e "07" para CRT 1/2/4 (Simples Nacional / MEI). Aliases aceitos: items[].cst_pis, items[].cstPIS, items[].pisSituacaoTributaria, items[].pis.cst, items[].impostos.pis.cst.
items[].cstCofins	string	não	CST da COFINS (2 dígitos). Valores aceitos: "01", "02" (COFINSAliq), "04", "05", "06", "07", "08", "09" (COFINSNT), "49", "99" (COFINSOutr). Se omitido: assume "01" para CRT 3 (Regime Normal) e "07" para CRT 1/2/4 (Simples Nacional / MEI). Aliases aceitos: items[].cst_cofins, items[].cstCOFINS, items[].cofinsSituacaoTributaria, items[].cofins.cst, items[].impostos.cofins.cst.
items[].pedidoCompra (ou xPed)	string	não	Número do Pedido de Compra do cliente (campo xPed / I60 do MOC 7.0 — até 15 caracteres). Opcional. Utilizado para cruzamento B2B e operações de industrialização. Serializado dentro de <prod> e impresso no DANFE sob a descrição do item. Aliases aceitos: items[].pedidoCompra, items[].numeroPedido, items[].pedido, items[].pedido_compra, items[].numero_pedido, items[].xPed, items[].x_ped.
items[].itemPedido (ou nItemPed)	number	não	Número do item no Pedido de Compra (campo nItemPed / I61 do MOC 7.0 — inteiro de 1 a 6 dígitos, entre 1 e 999999). Opcional. Serializado dentro de <prod> e impresso no DANFE sob a descrição do item. Aliases aceitos: items[].itemPedido, items[].numeroItemPedido, items[].item_pedido, items[].numero_item_pedido, items[].nItemPed, items[].n_item_ped.
items[].aliquotaPis	number	não	Alíquota PIS do item (% — de 0 a 100). Quando omitida, assume a alíquota configurada no projeto ou o padrão do regime (0.65% para CRT 3, 0% para Simples Nacional / MEI). Aliases aceitos: items[].pPIS, items[].pisAliquota, items[].pis.pPIS, items[].impostos.pis.pPIS.
items[].aliquotaCofins	number	não	Alíquota COFINS do item (% — de 0 a 100). Quando omitida, assume a alíquota configurada no projeto ou o padrão do regime (3.00% para CRT 3, 0% para Simples Nacional / MEI). Aliases aceitos: items[].pCOFINS, items[].cofinsAliquota, items[].cofins.pCOFINS, items[].impostos.cofins.pCOFINS.
items[].pisBaseCalculo (ou vBCPis)	number	não	Base de cálculo explícita do PIS do item em reais (>= 0). Opcional: quando omitida, a plataforma utiliza valorTotal (vProd). Recomendado para empresas de Regime Normal (CRT 3) que abatem o ICMS destacado da base de cálculo de PIS/COFINS (Tema 69 do STF — vBC = vProd - vICMS). O valor do PIS (<vPIS>) é sempre calculado pela plataforma como round2(vBC × pPIS / 100) e deduzido automaticamente da base do IBS/CBS (Regra SEFAZ UB16-10). Aliases aceitos: items[].vBCPis, items[].baseCalculoPis, items[].pisBaseCalculo, items[].vbc_pis, items[].pis.vBC, items[].impostos.pis.vBC.
items[].cofinsBaseCalculo (ou vBCCofins)	number	não	Base de cálculo explícita da COFINS do item em reais (>= 0). Opcional: quando omitida, a plataforma utiliza valorTotal (vProd). Recomendado para empresas de Regime Normal (CRT 3) que abatem o ICMS destacado da base de cálculo de PIS/COFINS (Tema 69 do STF — vBC = vProd - vICMS). O valor da COFINS (<vCOFINS>) é sempre calculado pela plataforma como round2(vBC × pCOFINS / 100) e deduzido automaticamente da base do IBS/CBS (Regra SEFAZ UB16-10). Aliases aceitos: items[].vBCCofins, items[].baseCalculoCofins, items[].cofinsBaseCalculo, items[].vbc_cofins, items[].cofins.vBC, items[].impostos.cofins.vBC.
items[].ipi	object	não	Grupo IPI — Imposto sobre Produtos Industrializados (Grupo O — MOC 7.0, exclusivo de NF-e modelo 55; proibido em NFC-e modelo 65 — Rejeição 742). Quando omitido, o grupo <IPI> não é gerado no item. Também aceito em items[].IPI, items[].impostos.ipi, items[].impostos.IPI, items[].imposto.ipi ou items[].imposto.IPI; cada objeto usa os mesmos subcampos.
items[].ipi.cst	string	sim	CST do IPI (2 dígitos). Valores aceitos: "00", "49", "50", "99" (gera <IPITrib> — tributado por alíquota ou por unidade) e "01", "02", "03", "04", "05", "51", "52", "53", "54", "55" (gera <IPINT> — entrada/saída isenta, não-tributada, imune, com suspensão ou alíquota zero). Aliases dentro do objeto: CST, cstIpi, cst_ipi, CSTIPI, situacaoTributaria, ipiSituacaoTributaria, situacaoTributariaIpi. Aliases flat: items[].cstIpi, items[].cst_ipi, items[].CSTIPI, items[].ipiSituacaoTributaria, items[].situacaoTributariaIpi.
items[].ipi.codigoEnquadramento	string	não	Código de Enquadramento Legal do IPI (tag <cEnq> / O06 — 1 a 3 dígitos numéricos). Opcional: quando omitido, assume "999" automaticamente. Validado conforme a Regra SEFAZ O09-10 (Rejeição 388): para CST "02"/"52" (Isenta) exige faixa "301" a "399"; para CST "04"/"54" (Imune) exige faixa "001" a "099"; para CST "05"/"55" (Suspensão) exige faixa "101" a "199"; para CST "53" (Saída não-tributada) ou tributados ("00", "49", "50", "99") aceita "999". Aliases dentro do objeto: enquadramento, cEnq, codigoEnquadramentoIpi, enquadramentoIpi, codigo_enquadramento. Aliases flat: items[].codigoEnquadramentoIpi, items[].enquadramentoIpi, items[].codigoEnquadramento, items[].cEnq, items[].codigo_enquadramento_ipi, items[].enquadramento_ipi.
items[].ipi.baseCalculo	number	não	Base de cálculo do IPI do item em reais (>= 0, até 2 casas decimais — tag <vBC> / O10). Obrigatória quando o IPI for tributado por alíquota (cst: "00", "49", "50" ou "99"). Proibida para CST de IPI não tributado (<IPINT>). Aliases dentro do objeto: vBC, vBCIPI, baseCalculoIpi, ipiBaseCalculo, base_calculo. Aliases flat: items[].baseCalculoIpi, items[].ipiBaseCalculo, items[].vBCIPI, items[].base_calculo_ipi, items[].ipi_base_calculo. Os nomes items[].vBC e items[].baseCalculo são ambíguos com ICMS e não são aliases flat de IPI.
items[].ipi.aliquota	number	não	Alíquota do IPI do item (% — >= 0, até 4 casas decimais — tag <pIPI> / O13). Obrigatória quando o IPI for tributado por alíquota (cst: "00", "49", "50" ou "99"). Proibida para CST de IPI não tributado (<IPINT>). Aliases dentro do objeto: pIPI, aliquotaIpi, ipiAliquota. Aliases flat: items[].aliquotaIpi, items[].ipiAliquota, items[].pIPI, items[].aliquota_ipi, items[].ipi_aliquota.
items[].ipi.valor	number	não	Valor do IPI destacado no item em reais (>= 0, até 2 casas decimais — tag <vIPI> / O14). Opcional em IPI tributado (<IPITrib>): quando omitido, a plataforma calcula automaticamente como round2(baseCalculo × aliquota / 100) ou round2(quantidadeUnidade × valorUnidade); quando informado, é validado com tolerância de ±R$ 0,01. Totalizado automaticamente em <ICMSTot><vIPI> e somado ao valor total da nota (<vNF>, Regra W16-10). Aliases dentro do objeto: vIPI, valorIpi, ipiValor. Aliases flat: items[].valorIpi, items[].ipiValor, items[].vIPI, items[].valor_ipi, items[].ipi_valor.
items[].ipi.quantidadeUnidade	number	não	Quantidade total na unidade padrão para tributação do IPI (> 0, até 4 casas decimais — tag <qUnid> / O11, modalidade de cálculo por unidade em <IPITrib>, mutuamente exclusiva com baseCalculo + aliquota). Aliases dentro do objeto: qUnid, qUnidIpi, quantidadeUnidadeIpi, quantidade_unidade. Aliases flat: items[].quantidadeUnidadeIpi, items[].qUnidIpi, items[].quantidadeUnidade, items[].qUnid, items[].quantidade_unidade_ipi.
items[].ipi.valorUnidade	number	não	Valor do IPI por unidade tributável em reais (>= 0, até 4 casas decimais — tag <vUnid> / O12, modalidade de cálculo por unidade em <IPITrib>). Aliases dentro do objeto: vUnid, vUnidIpi, valorUnidadeIpi, valor_unidade. Aliases flat: items[].valorUnidadeIpi, items[].vUnidIpi, items[].valorUnidade, items[].vUnid, items[].valor_unidade_ipi.
items[].ipi.cnpjProdutor	string	não	CNPJ do produtor da mercadoria, quando diferente do emitente (tag <CNPJProd> / O03 — 14 posições: numérico \d{14} ou alfanumérico [0-9A-Z]{12}\d{2}). Opcional, destinado a exportação direta ou indireta. Aliases dentro do objeto: CNPJProd, cnpjProdutorIpi, cnpj_produtor. Aliases flat: items[].cnpjProdutorIpi, items[].cnpjProdutor, items[].CNPJProd, items[].cnpj_produtor_ipi.
items[].ipi.seloControle	string	não	Código do selo de controle IPI (tag <cSelo> / O04 — 1 a 60 caracteres). Opcional. Aliases dentro do objeto: codigoSelo, cSelo, seloControleIpi, codigoSeloIpi, selo_controle, codigo_selo. Aliases flat: items[].seloControleIpi, items[].codigoSeloIpi, items[].seloControle, items[].codigoSelo, items[].cSelo, items[].selo_controle_ipi, items[].codigo_selo_ipi.
items[].ipi.quantidadeSelo	string \| number	não	Quantidade de selo de controle IPI (tag <qSelo> / O05 — 1 a 12 dígitos numéricos). Opcional. Aliases dentro do objeto: qSelo, quantidadeSeloIpi, quantidade_selo. Aliases flat: items[].quantidadeSeloIpi, items[].quantidadeSelo, items[].qSelo, items[].quantidade_selo_ipi.
items[].ibscbs	object	não	Grupo IBS/CBS da NT 2025.002-RTC. Quando informado, a API calcula base e valores dos tributos; não envie valores monetários calculados.
items[].ibscbs.cst	string	sim	CST IBS/CBS com 3 dígitos. Alias: cstIbsCbs.
items[].ibscbs.cClassTrib	string	sim	Classificação tributária oficial com 6 dígitos, compatível com o CST e com o modelo. Não possui valor padrão. Alias: classificacaoTributaria.
items[].ibscbs.aliquotaIbsEstadual	number	não	Alíquota nominal do IBS estadual (%). Obrigatória para classificações tributadas. Alias: pIBSUF.
items[].ibscbs.aliquotaIbsMunicipal	number	não	Alíquota nominal do IBS municipal (%). Obrigatória para classificações tributadas. Alias: pIBSMun.
items[].ibscbs.aliquotaCbs	number	não	Alíquota nominal da CBS (%). Obrigatória para classificações tributadas. Alias: pCBS.
items[].ibscbs.diferimentoIbsEstadual	number	não	Percentual de diferimento do IBS estadual, quando exigido pela classificação. Alias: pDifIBSUF.
items[].ibscbs.diferimentoIbsMunicipal	number	não	Percentual de diferimento do IBS municipal, quando exigido pela classificação. Alias: pDifIBSMun.
items[].ibscbs.diferimentoCbs	number	não	Percentual de diferimento da CBS, quando exigido pela classificação. Alias: pDifCBS.
items[].baseCalculoIcms (ou vBC)	number	não	Base de cálculo explícita do ICMS do item. Opcional; para CSOSN 900, quando ausente, a plataforma calcula automaticamente como (valorTotal - desconto). Para outros CSTs, segue a base própria de cada grupo.
items[].baseCalculoIcmsSt (ou vBCST)	number	não	Base de cálculo do ICMS ST (Substituição Tributária) do item (>= 0). Obrigatória quando houver campos de ICMS ST informados. Suportada em NF-e (modelo 55) com CSOSN 900 e 201 no Simples Nacional, ou CST 10, 70 e 90 no Regime Normal. Totalizada automaticamente no cabeçalho em <ICMSTot><vBCST>. Aliases aceitos: vBCST, baseCalculoSt, vBcSt (ou no objeto icmsSt.baseCalculo).
items[].aliquotaIcmsSt (ou pICMSST)	number	não	Alíquota do ICMS ST do item (% — de 0 a 100). Opcional quando valorIcmsSt for informado (a plataforma deriva o percentual automaticamente). Aliases aceitos: pICMSST, aliquotaSt, pIcmsSt (ou no objeto icmsSt.aliquota).
items[].valorIcmsSt (ou vICMSST)	number	não	Valor do ICMS ST retido por substituição tributária (>= 0). Opcional quando aliquotaIcmsSt for informada (calculado automaticamente sobre a base). Totalizado no cabeçalho em <ICMSTot><vST> e somado ao valor total da nota (vNF, Regra W16-10 da SEFAZ). Aliases aceitos: vICMSST, valorSt, vIcmsSt (ou no objeto icmsSt.valor).
items[].modalidadeBcSt (ou modBCST)	number	não	Modalidade de determinação da base de cálculo do ICMS ST. Valores MOC 7.0: 0 a 5 para CSOSN 900/201 e CST 70/90; 0 a 6 exclusivamente para CST 10 (onde 6 = Valor da Operação, conf. NT 2019.001). Padrão da plataforma: 4 (Margem Valor Agregado / MVA). Aliases aceitos: modBCST, modBcSt (ou no objeto icmsSt.modalidadeBc).
items[].percentualMvaSt (ou pMVAST)	number	não	Percentual da Margem de Valor Agregado do ICMS ST (% — opcional, >= 0). Aliases aceitos: pMVAST, mvaSt, pMvaSt (ou no objeto icmsSt.percentualMva).
items[].percentualReducaoBcSt (ou pRedBCST)	number	não	Percentual de redução da base de cálculo do ICMS ST (% — opcional, >= 0 e < 100). Suportado em CST 10, 70, 90 e CSOSN 201 e 900. Aliases aceitos: pRedBCST, reducaoBcSt, pRedBcSt (ou no objeto icmsSt.percentualReducaoBc).
items[].icmsSt	object	não	Objeto agrupador alternativo para parâmetros de ICMS ST. Aceita os campos aninhados: baseCalculo, aliquota, valor, modalidadeBc, percentualMva e percentualReducaoBc.
items[].devolucaoTributos (ou impostoDevol)	object	não	Grupo Imposto Devolvido (Grupo UA — MOC 7.0, tags UA01 a UA04). Exclusivo de NF-e de devolução (finalidade: 4, modelo 55). Proibido em NFC-e (rejeição 390) e em notas com outra finalidade (rejeição 354). Aliases aceitos: items[].impostoDevol, items[].impostoDevolvido.
items[].devolucaoTributos.percentualDevolvido	number	sim	Percentual da mercadoria devolvida — 0 a 100.00. Deve ser informado junto com valorIpiDevolvido. Alias: pDevol.
items[].devolucaoTributos.valorIpiDevolvido	number	sim	Valor do IPI devolvido ao fornecedor, em reais (>= 0). Somado automaticamente ao total da nota (vNF), conforme a Regra W16-10 da SEFAZ. Aliases: vIPIDevol, ipiDevolvido.
items[].nfeReferenciada (ou dfeReferenciado)	object \| string	não	Documento fiscal referenciado neste item. A partir da NT 2025.002 (em vigor desde 05/10/2026), em devoluções (finalidade: 4, modelo 55) a SEFAZ exige que a chave original e o item sejam informados por item (<DFeReferenciado> dentro de <det>), evitando a Rejeição 321. Ao informar este campo, a plataforma gera a tag <DFeReferenciado> em <det> e suprime automaticamente o <NFref> no cabeçalho <ide> para devoluções (evitando a Rejeição 1010). Aliases aceitos: items[].dfeReferenciado, items[].refNFe e items[].chaveReferenciada.
items[].nfeReferenciada.chaveAcesso	string	sim	Chave de acesso de 44 posições da NF-e original que deu origem à mercadoria devolvida (aceita CNPJ numérico ou alfanumérico nas posições 7 a 20 conforme NT Conjunta 2025.001).
items[].nfeReferenciada.nItem	number	não	Número do item na NF-e original referenciada (1 a 990). Conforme a NT 2025.002, é serializado no elemento <DFeReferenciado><nItem>. Se omitido, a plataforma preenche automaticamente com o índice sequencial do item.
items[].combustivel	object	não	Grupo de combustíveis ANP (Grupo LA — MOC 7.0). Obrigatório em itens com CFOP de combustível (ex: 5656, 5661, 6656, 6661). A ausência gera cStat 660. Na NFC-e (modelo 65) a regra LA01-20 é facultativa no MOC (a critério da UF), mas a plataforma a aplica sempre como política restritiva. Aceita alias: items[].comb.
items[].combustivel.codigoAnp	string	sim	Código ANP do produto — exatamente 9 dígitos sem pontuação. Ex: "210203001" (GLP), "320102001" (Gasolina C Comum), "820101033" (Diesel B S10 Aditivado). Valores com pontos (ex: "320.102.001") ou espaços nas extremidades são rejeitados. Alias: cProdANP.
items[].combustivel.descricaoAnp	string	sim	Descrição oficial do produto na tabela ANP (2 a 95 caracteres). Ex: "GLP", "GASOLINA C COMUM". Alias: descANP.
items[].combustivel.ufConsumo	string	sim	Sigla da UF de consumo do combustível — obrigatório. Ex: "PR", "SP". Alias: UFCons.
items[].combustivel.percentualGlp	number	não	Percentual de GLP derivado de petróleo (0 a 100). Obrigatório somente para cProdANP = "210203001". A soma de percentualGlp + percentualGnn + percentualGni deve ser 100. Alias: pGLP.
items[].combustivel.percentualGnn	number	não	Percentual de gás natural nacional — GNn (0 a 100). Alias: pGNn.
items[].combustivel.percentualGni	number	não	Percentual de gás natural importado — GNi (0 a 100). Alias: pGNi.
items[].combustivel.valorPartida	number	não	Valor de partida por kg (GLP). Opcional — a regra LA03d-10 (cStat 856) foi revogada na NT 2023.001 v1.20. Alias: vPart.
items[].combustivel.percentualBiodiesel	number	não	Percentual de biodiesel misturado (> 0 e <= 100 quando informado). A API confronta o codigoAnp com a Tabela de Combustíveis Monofásicos (IT 2023.003): proibido quando a coluna pBio=0 ou o produto está fora da tabela (cStat 907); obrigatório quando pBio=1 (cStat 908, apenas NF-e mod.55, exceto consumidor final, devolução/complementar e CFOP 5922/6922). Alias: pBio.
items[].combustivel.codif	string	não	Código de Autorização e Registro — CODIF (máx. 21 dígitos). Alias: CODIF.
items[].combustivel.quantidadeTemperatura	number	não	Quantidade à temperatura ambiente. Alias: qTemp.
items[].combustivel.cide	object	não	Grupo CIDE — Contribuição de Intervenção no Domínio Econômico (LA11a). Opcional; quando informado, todos os campos são obrigatórios.
items[].combustivel.cide.qBCProd	number	sim	Quantidade de base de cálculo (litros). Alias: quantidadeBase.
items[].combustivel.cide.vAliqProd	number	sim	Alíquota da CIDE por unidade (R$ por litro). Alias: aliquota.
items[].combustivel.cide.vCIDE	number	sim	Valor da CIDE calculado. Alias: valorCide.
items[].combustivel.encerrante	object	não	Dados do encerrante da bomba de combustível (uso em postos).
items[].combustivel.encerrante.numeroBico	number	sim	Número do bico da bomba (1-999). Alias: nBico.
items[].combustivel.encerrante.numeroBomba	number	não	Número da bomba (1-999, opcional). Alias: nBomba.
items[].combustivel.encerrante.numeroTanque	number	sim	Número do tanque (1-999). Alias: nTanque.
items[].combustivel.encerrante.valorInicial	number	sim	Leitura do encerrante no início do abastecimento. Alias: vEncIni.
items[].combustivel.encerrante.valorFinal	number	sim	Leitura do encerrante no final do abastecimento (deve ser > valorInicial — cStat 380). Alias: vEncFin.
items[].combustivel.origemCombustivel	array	não	Grupo de origem do combustível (LA18 — NT 2023.001 v1.60, máx. 30 entradas). Obrigatório em NF-e mod.55 quando a Tabela de Combustíveis Monofásicos indica origComb=1 para o codigoAnp (cStat 909) ou quando percentualGnn/percentualGni > 0 (LA18-20); dispensado para consumidor final (indFinal=1), NFC-e, devolução (finalidade=4), complementar (finalidade=2) e CFOP 5922/6922. Proibido para produtos fora da tabela (cStat 747). Somatório de pOrig = 100 (±0.1%): por indImport para GLP (210203001/03/04/05), total geral para demais (cStat 958). Alias: origComb.
items[].combustivel.origemCombustivel[].indImport	number	sim	0 = Nacional, 1 = Importado.
items[].combustivel.origemCombustivel[].cUFOrig	number	sim	Código IBGE da UF de origem (ex: 41 = PR, 35 = SP). Alias: ufOrigem.
items[].combustivel.origemCombustivel[].pOrig	number	sim	Percentual originário desta UF (> 0 e <= 100). Alias: percentualOrigem.
items[].veiculoNovo	object	não	Grupo Detalhamento de Veículos Novos (Grupo JA — MOC 7.0). Exclusivo de NF-e (modelo 55); proibido em NFC-e (modelo 65, Regra J01-10 / Rejeição 736). Mutuamente exclusivo com o grupo combustivel no mesmo item. Todos os 24 subcampos são obrigatórios quando o grupo é informado. Aliases: items[].veicProd, items[].dadosVeiculo.
items[].veiculoNovo.tipoOperacao	number	sim	Tipo da operação: 1=Venda concessionária, 2=Faturamento direto para consumidor final, 3=Venda direta para grandes consumidores (frotista/governo), 0=Outros. Alias: tpOp.
items[].veiculoNovo.chassi	string	sim	Chassi do veículo (VIN) — exatamente 17 caracteres alfanuméricos maiúsculos, sem espaços. Alias: chassiVeiculo.
items[].veiculoNovo.codigoCor	string	sim	Código da cor conforme tabela do fabricante (1-4 caracteres). Alias: cCor.
items[].veiculoNovo.descricaoCor	string	sim	Descrição da cor (1-40 caracteres). Aliases: xCor, corVeiculo.
items[].veiculoNovo.potencia	string	sim	Potência do motor em CV (1-4 caracteres). Alias: pot.
items[].veiculoNovo.cilindrada	string	sim	Capacidade volumétrica (cilindradas) do motor em cm³ (1-4 caracteres). Alias: cilin.
items[].veiculoNovo.pesoLiquido	number	sim	Peso líquido em toneladas. Entre 0.0001 e 9999.9999 (limites inclusivos), em notação decimal padrão com no máximo 4 casas decimais (máx. 9 caracteres no XML — limite do XSD oficial, TString maxLength="9"). Não aceita notação científica (ex: "1e-5"), sinal explícito (ex: "+1") ou vírgula como separador decimal (ex: "1,5") — apenas dígitos e, opcionalmente, um ponto seguido de 1 a 4 dígitos. Valores fora do formato ou da faixa são rejeitados (HTTP 400), nunca arredondados ou truncados silenciosamente. Alias: pesoL.
items[].veiculoNovo.pesoBruto	number	sim	Peso bruto em toneladas. Entre 0.0001 e 9999.9999 (limites inclusivos), em notação decimal padrão com no máximo 4 casas decimais (máx. 9 caracteres no XML — limite do XSD oficial, TString maxLength="9"). Não aceita notação científica (ex: "1e-5"), sinal explícito (ex: "+1") ou vírgula como separador decimal (ex: "1,5") — apenas dígitos e, opcionalmente, um ponto seguido de 1 a 4 dígitos. Valores fora do formato ou da faixa são rejeitados (HTTP 400), nunca arredondados ou truncados silenciosamente. Alias: pesoB.
items[].veiculoNovo.numeroSerie	string	sim	Serial / número de série do veículo (1-9 caracteres). Alias: nSerie.
items[].veiculoNovo.tipoCombustivelVeiculo	string	sim	Tipo de combustível conforme tabela RENAVAM (1-2 caracteres, ex: "01"=Álcool, "02"=Gasolina, "03"=Diesel, "16"=Álcool/Gasolina). Distinto do grupo combustivel/ANP. Aliases: tpComb, tipoCombustivelRenavam.
items[].veiculoNovo.numeroMotor	string	sim	Número do motor (1-21 caracteres). Alias: nMotor.
items[].veiculoNovo.capacidadeMaximaTracao	number	sim	Capacidade Máxima de Tração (CMT) em toneladas. Entre 0.0001 e 9999.9999 (limites inclusivos), em notação decimal padrão com no máximo 4 casas decimais (máx. 9 caracteres no XML — limite do XSD oficial, TString maxLength="9"). Não aceita notação científica (ex: "1e-5"), sinal explícito (ex: "+1") ou vírgula como separador decimal (ex: "1,5") — apenas dígitos e, opcionalmente, um ponto seguido de 1 a 4 dígitos. Valores fora do formato ou da faixa são rejeitados (HTTP 400), nunca arredondados ou truncados silenciosamente. Aliases: CMT, cmt.
items[].veiculoNovo.distanciaEixos	string	sim	Distância entre eixos em metros (1-4 caracteres). Alias: dist.
items[].veiculoNovo.anoModelo	string	sim	Ano modelo de fabricação — exatamente 4 dígitos numéricos, entre 1900 e 2099. Alias: anoMod.
items[].veiculoNovo.anoFabricacao	string	sim	Ano de fabricação — exatamente 4 dígitos numéricos, entre 1900 e 2099. Alias: anoFab.
items[].veiculoNovo.tipoPintura	string	sim	Tipo de pintura do veículo (1 caractere, ex: "S"=Sólida, "M"=Metálica, "P"=Perolizada). Alias: tpPint.
items[].veiculoNovo.tipoVeiculo	string	sim	Tipo de veículo conforme tabela RENAVAM (1-2 dígitos numéricos, ex: "06"=Automóvel, "14"=Caminhão). Alias: tpVeic.
items[].veiculoNovo.especieVeiculo	string	sim	Espécie de veículo conforme tabela RENAVAM (1 dígito numérico, entre 1 e 6: 1=Passageiro, 2=Carga, 3=Misto, 4=Corrida, 5=Tração, 6=Especial). Alias: espVeic.
items[].veiculoNovo.situacaoChassi	string	sim	Condição do VIN: "N"=Normal, "R"=Remarcado. Aliases: VIN, chassiRemarcado.
items[].veiculoNovo.condicaoVeiculo	number	sim	Condição do veículo: 1=Acabado, 2=Inacabado, 3=Semiacabado. Alias: condVeic.
items[].veiculoNovo.codigoMarcaModelo	string	sim	Código Marca Modelo conforme tabela RENAVAM (1-6 dígitos numéricos). Aliases: cMod, codigoModeloRenavam.
items[].veiculoNovo.codigoCorDenatran	string	sim	Código da cor conforme tabela DENATRAN (1-2 dígitos numéricos, entre 1 e 16). Alias: cCorDENATRAN.
items[].veiculoNovo.lotacao	string	sim	Capacidade máxima de lotação/passageiros (1-3 dígitos numéricos, entre 1 e 999). Alias: lota.
items[].veiculoNovo.tipoRestricao	number	sim	Restrição do veículo: 0=Não há, 1=Alienação Fiduciária, 2=Arrendamento Mercantil, 3=Reserva de Domínio, 4=Penhor de Veículos, 9=Outras. Alias: tpRest.
items[].declaracaoImportacao (ou di)	array \| object	não	Grupo Declaração de Importação (Grupo I18 — MOC 7.0 / XSD PL_010e). Exclusivo de NF-e (modelo 55) em operações de entrada do exterior (tpNF: 0, idDest: 3, CFOPs iniciados por 3 como 3102). Proibido em NFC-e modelo 65. Aceita array ou objeto único (normalizado automaticamente).
items[].declaracaoImportacao[].numero	string	sim	Número do documento de importação (1 a 15 caracteres alfanuméricos). Suporta tanto a DI clássica (ex: "26/1234567-8" ou "2612345678") quanto o novo formato DUIMP (ex: "26BR0000000001"). Pontuação, barras e traços são normalizados automaticamente. Aliases: nDI, nDi, numeroDI.
items[].declaracaoImportacao[].tipoDocumento	string	não	Tipo do documento: "DI" ou "DUIMP". Opcional (nunca inferido). Quando informado como "DI", exige numeroAdicao nas adições conforme regras clássicas. Alias: tipo_documento.
items[].declaracaoImportacao[].dataRegistro	string	sim	Data de registro da DI/DUIMP no formato AAAA-MM-DD. Aliases: dDI, dDi, dataDI.
items[].declaracaoImportacao[].localDesembaraco	string	sim	Local onde ocorreu o desembaraço aduaneiro (1 a 60 caracteres, ex: "Porto de Itajaí", "Aeroporto de Viracopos"). Alias: xLocDesemb.
items[].declaracaoImportacao[].ufDesembaraco	string	sim	Sigla da UF onde ocorreu o desembaraço (UF brasileira válida, ex: "SC", "SP" — nunca "EX"). Alias: UFDesemb.
items[].declaracaoImportacao[].dataDesembaraco	string	sim	Data do desembaraço aduaneiro no formato AAAA-MM-DD. Não pode ser futura nem anterior a 5 anos (regras SEFAZ I23-10 / Rej. 376), e deve ser igual ou posterior à data de registro. Alias: dDesemb.
items[].declaracaoImportacao[].viaTransporte	number	sim	Via de transporte internacional (1 a 13 conforme tabela SEFAZ): 1=Marítima, 2=Fluvial, 3=Lacustre, 4=Aérea, 5=Postal, 6=Ferroviária, 7=Rodoviária, 8=Conduto, 9=Meios próprios, 10=Entrada/Saída ficta, 11=Courier, 12=Handcarry, 13=Ductoviária. Alias: tpViaTransp.
items[].declaracaoImportacao[].valorAfrmm	number	não	Valor da taxa AFRMM (Adicional ao Frete para Renovação da Marinha Mercante), em reais com até 2 casas decimais. Obrigatório quando a via de transporte for marítima (viaTransporte: 1), sendo 0.00 aceito para isenções/não incidências (regra SEFAZ I23b-10 / Rej. 330). Alias: vAFRMM.
items[].declaracaoImportacao[].formaIntermediacao	number	sim	Forma de importação quanto à intermediação: 1=Por conta própria, 2=Por conta e ordem, 3=Por encomenda. Alias: tpIntermedio.
items[].declaracaoImportacao[].cnpjAdquirente	string	não	CNPJ do adquirente ou encomendante (14 dígitos). Obrigatório se formaIntermediacao for 2 ou 3 (regras SEFAZ I23d-10 / Rej. 331 e 332). Mutuamente exclusivo com cpfAdquirente. Proibido se conta própria (1). Alias: CNPJ.
items[].declaracaoImportacao[].cpfAdquirente	string	não	CPF do adquirente ou encomendante (11 dígitos). Aceito em alternativa ao CNPJ para importação via pessoa física com intermediação. Proibido se conta própria (1). Alias: CPF.
items[].declaracaoImportacao[].ufTerceiro	string	não	Sigla da UF do terceiro adquirente/encomendante. Obrigatório se formaIntermediacao for 2 ou 3 (regra SEFAZ I23e-10 / Rej. 333). Proibido se conta própria (1). Alias: UFTerceiro.
items[].declaracaoImportacao[].codigoExportador	string	sim	Código do exportador estrangeiro no sistema aduaneiro (1 a 60 caracteres alfanuméricos). Alias: cExportador.
items[].declaracaoImportacao[].adicoes	array \| object	sim	Adições ou itens vinculados à DI/DUIMP (mínimo 1 adição por declaração). Aliases: adi, adicoes.
items[].declaracaoImportacao[].adicoes[].sequencialAdicao	number	sim	Número sequencial do item ou adição dentro da declaração (1 a 99999). Obrigatório. Aliases: nSeqAdic, sequencial.
items[].declaracaoImportacao[].adicoes[].numeroAdicao	number	não	Número da adição na DI clássica (1 a 999). Opcional no XSD e na DUIMP (a DUIMP não possui estrutura de adição numérica clássica, apenas itens sequenciais). Obrigatório apenas quando tipoDocumento="DI". Alias: nAdicao.
items[].declaracaoImportacao[].adicoes[].codigoFabricante	string	sim	Código do fabricante estrangeiro do produto (1 a 60 caracteres). Alias: cFabricante.
items[].declaracaoImportacao[].adicoes[].descontoDI	number	não	Valor do desconto comercial da adição/item na DI, em reais. Deve ser > 0 quando informado (omita ou deixe indefinido para zero). Alias: vDescDI.
items[].declaracaoImportacao[].adicoes[].numeroDrawback	string	não	Número do ato concessório de Drawback (1 a 20 alfanuméricos). Obrigatório para operações sob os CFOPs 3127 e 3211 (regra SEFAZ I29a-10 / Rej. 334). Aliases: nDraw, drawback.
items[].impostoImportacao (ou ii)	object	não	Grupo Imposto de Importação (Grupo P01 — MOC 7.0 / XSD PL_010e). Usado em itens de importação (CFOP 3xxx). O valor do II destacado é totalizado automaticamente em <ICMSTot><vII>, somado ao total da nota (vNF, Regra W16-10) e na base de cálculo de IBS/CBS. Aliases: impostoImportacao, ii, II.
items[].impostoImportacao.baseCalculo	number	sim	Base de cálculo do Imposto de Importação (valor aduaneiro CIF em reais, >= 0). Alias: vBC.
items[].impostoImportacao.despesasAduaneiras	number	sim	Valor das despesas aduaneiras (ex: Siscomex, armazenagem, capatazia, >= 0). Alias: vDespAdu.
items[].impostoImportacao.valor	number	sim	Valor apurado do Imposto de Importação em reais (>= 0). Totalizado no cabeçalho <vII> e somado em <vNF>. Alias: vII.
items[].impostoImportacao.valorIof	number	sim	Valor do IOF sobre a operação cambial de importação em reais (>= 0). Alias: vIOF.
pagamentos[]	array	sim	Formas de pagamento (mínimo 1)
pagamentos[].tipoPagamento	string	sim	Código SEFAZ: 01=Dinheiro, 03=Cartão de Crédito, 04=Cartão de Débito, 17=PIX, 99=Outros (alias: tPag)
pagamentos[].valor	number	sim	Valor pago nesta forma em reais (alias: vPag)
pagamentos[].descricaoPagamento	string	não	Descrição do meio de pagamento. Obrigatório quando tipoPagamento for "99" (Outros). Aceita também aliases: pagamentos[].descricao, pagamentos[].xPag.
pagamentos[].tipoIntegracao	number	não	1=Integrado (TEF), 2=Não integrado (POS)
pagamentos[].bandeira	string	não	Bandeira do cartão (2 dígitos)
pagamentos[].autorizacao	string	não	Código de autorização da transação
pagamentos[].cnpjPagamento	string	não	CNPJ da credenciadora de pagamento
valorFrete	number	não	Valor total do frete da nota em reais. Se informado na raiz da nota, é distribuído proporcionalmente entre os itens. Alias amigável para frete.
valorSeguro	number	não	Valor total do seguro da nota em reais. Se informado na raiz da nota, é distribuído proporcionalmente entre os itens. Alias amigável para seguro.
transporte.modalidadeFrete	number	não	Modalidade do frete: 0=Emitente, 1=Destinatário, 2=Terceiros, 9=Sem frete (padrão: 9, alias: modFrete)
presencaComprador	number	não	Indicador de presença do comprador (padrão: 1)
indicadorIntermediador	number	não	0=Sem intermediador (site/app próprio), 1=Via marketplace/plataforma de terceiros. A tag XML <indIntermed> é obrigatória na SEFAZ quando presencaComprador for 2, 3, 4 ou 9; no payload o campo é opcional pois a API aplica auto-default 0 (ou 1 se intermediador for informado).
intermediador (ou infIntermed)	object	não	Grupo YB — Informações do Intermediador da Transação (MOC 7.0 / NT 2020.006). Obrigatório quando indicadorIntermediador=1 (evita Rejeição 438); proibido quando indicadorIntermediador=0 (evita Rejeição 439).
intermediador.cnpj	string	não	CNPJ do intermediador da transação (marketplace, plataforma de delivery como iFood/Rappi, etc.) — 14 dígitos com DV válido (Campo YB02 / Rejeição 440).
intermediador.idCadIntTran (ou identificador)	string	não	Nome do usuário ou identificação do perfil do vendedor cadastrado no intermediador — 2 a 60 caracteres (Campo YB03).
tipoOperacao	number	não	0=Entrada, 1=Saída (padrão: 1)
finalidade	number	não	1=Normal, 2=Complementar, 3=Ajuste, 4=Devolução (padrão: 1)
consumidorFinal	number	não	0=Normal, 1=Consumidor final
tipoEmissao	number	não	1=Normal, 3=Contingência SVC-AN, 5=Contingência SVC-RS (padrão: 1)
destinoOperacao (ou idDest)	number	não	1=Operação interna (mesma UF), 2=Interestadual, 3=Exterior. Auto-inferido a partir de dest.endereco.uf ("EX" → 3), cPais (≠ 1058 → 3) ou dest.idEstrangeiro.
exportacao	object	não	Grupo ZA da SEFAZ. Obrigatório em saídas para o exterior (idDest: 3 e tipoOperacao: 1 / CFOP 7xxx).
exportacao.ufSaidaPais	string	sim	Sigla da UF onde a mercadoria sairá do território nacional (ex: "SP", "AM"). Deve ser uma UF brasileira válida, nunca "EX".
exportacao.localEmbarque	string	sim	Nome do porto, aeroporto ou ponto de fronteira onde ocorrerá o embarque (1 a 60 caracteres, ex: "Porto de Santos").
exportacao.localDespacho	string	não	Local onde ocorreu o despacho aduaneiro (1 a 60 caracteres, opcional).
nfesReferenciadas (ou refNFe)	string \| string[]	não	Chave(s) de 44 dígitos das NF-es referenciadas no cabeçalho da nota (grupo NFref do elemento ide). Em notas com finalidade normal, complementar ou de ajuste (finalidade: 1, 2 ou 3), é serializado no grupo <NFref> em <ide>. Em notas de devolução (finalidade: 4), a NT 2025.002 da SEFAZ exige o referenciamento por item (<DFeReferenciado> em <det>), devendo ser informado em items[].nfeReferenciada; caso seja informada uma chave de cabeçalho em devolução com item único, a plataforma faz o vínculo automático para o item.
refNFP (ou notasProdutorReferenciadas)	array \| object	não	Referenciamento de Nota Fiscal de Produtor Rural em papel/talão ou avulsa estadual no cabeçalho <ide><NFref><refNFP> (Grupo BA10 do MOC 7.0). Exclusivo de NF-e modelo 55 com finalidade normal, complementar ou de ajuste (finalidade: 1, 2 ou 3); proibido em NFC-e modelo 65 e em devoluções (finalidade: 4, onde a NT 2025.002 exige <DFeReferenciado> por item). Aliases aceitos na raiz: refNFP, nfpReferenciada, nfProdutorReferenciada, nfesProdutorReferenciadas, notasProdutorReferenciadas.
refNFP[].uf (ou cUF)	string \| number	sim	Sigla da UF (ex: "PR", "MT") ou código IBGE numérico da UF (ex: 41, 51) de emissão da Nota Fiscal de Produtor referenciada.
refNFP[].aamm	string	sim	Ano e mês de emissão da NF de Produtor no formato AAMM (4 dígitos, mês 01 a 12, não posterior ao mês/ano de emissão da NF-e nem anterior a 20 anos — Regra BA12-10 / Rejeição 322). Alias: AAMM.
refNFP[].cpf / refNFP[].cnpj	string	sim	CPF (11 dígitos) ou CNPJ (14 dígitos) do emitente da NF de Produtor referenciada (mutuamente exclusivos; informe exatamente um). Aceita também alias cpfCnpj.
refNFP[].ie	string	sim	Inscrição Estadual do produtor emitente da nota referenciada (2 a 14 dígitos numéricos ou literal "ISENTO" — Regra BA15-10 / Rejeição 551). Alias: IE.
refNFP[].mod (ou modelo)	string	não	Modelo do documento fiscal referenciado: "04" (Nota Fiscal de Produtor — padrão) ou "01" (Nota Fiscal modelo 1/1A).
refNFP[].serie	number \| string	não	Série do documento fiscal referenciado (inteiro de 0 a 999; padrão: 0 para série única). Serializado sem zeros à esquerda no XML.
refNFP[].nNF (ou numero)	number \| string	sim	Número do documento fiscal referenciado (inteiro de 1 a 999999999). Serializado sem zeros à esquerda no XML.
entrega (ou localEntrega / local_entrega)	object	não	Grupo G — Identificação do Local de Entrega (<entrega>, tipo TLocal no MOC 7.0 Anexo I / NT 2018.005). Informar quando o endereço de entrega da mercadoria for diferente do endereço do destinatário (<dest><enderDest>). Exclusivo de NF-e modelo 55 (rejeitado em NFC-e modelo 65). Obrigatório em NF-e normal de saída quando houver veículo novo com faturamento direto para consumidor final (items[].veiculoNovo.tipoOperacao = 2 — Regra SEFAZ C18-20 / Rejeição 478). O grupo <entrega> permanece no XML autorizado (nfeProc) logo após </dest> e é impresso no quadro "Informações do Local de Entrega" em todos os modelos de DANFE da Notaas. Chaves desconhecidas são rejeitadas fail-fast com HTTP 400. Aceita campos na raiz de entrega ou agrupados em entrega.endereco. Aliases na raiz: entrega, localEntrega, local_entrega.
entrega.cnpj / entrega.cpf	string	não	CNPJ (14 caracteres numéricos ou alfanuméricos NT 2025.001, Regra G02-10 / Rejeição 514) ou CPF (11 dígitos numéricos com DV válido, Regra G02a-10 / Rejeição 541) do local de entrega (mutuamente exclusivos). Obrigatório para UF nacional; quando uf="EX" sem documento brasileiro, gera <CNPJ></CNPJ> vazio conforme MOC 7.0 Campo G02 Obs. Aliases: CNPJ, CPF.
entrega.nome (ou xNome)	string	não	Razão Social ou Nome do recebedor no local de entrega (2 a 60 caracteres, opcional — Campo G02b). Aliases: xNome, razaoSocial, nomeRecebedor.
entrega.logradouro (ou xLgr)	string	sim	Logradouro do local de entrega (2 a 60 caracteres — Campo G03). Aceito na raiz de entrega ou em entrega.endereco. Aliases: xLgr, rua.
entrega.numero (ou nro)	string	sim	Número do endereço de entrega (1 a 60 caracteres, use "S/N" se sem número — Campo G04). Aceito na raiz ou em entrega.endereco. Alias: nro.
entrega.complemento (ou xCpl)	string	não	Complemento do endereço de entrega (1 a 60 caracteres, opcional — Campo G05). Aceito na raiz ou em entrega.endereco. Alias: xCpl.
entrega.bairro (ou xBairro)	string	sim	Bairro ou distrito do local de entrega (2 a 60 caracteres — Campo G06). Aceito na raiz ou em entrega.endereco. Alias: xBairro.
entrega.codigoMunicipio (ou cMun)	string	sim	Código IBGE de 7 dígitos do município de entrega (os 2 primeiros dígitos devem corresponder à UF — Regras G07-20 / Rej. 278 e G07-30 / Rej. 279). Para uf="EX" (exterior), assume ou exige "9999999" (Regra G07-10 / Rej. 515). Aliases: cMun, codMunicipio, ibge.
entrega.municipio (ou xMun)	string	sim	Nome do município de entrega (2 a 60 caracteres — Campo G08). Para uf="EX", assume ou exige "EXTERIOR". Aliases: xMun, cidade, nomeMunicipio.
entrega.uf (ou UF)	string	sim	Sigla da UF do local de entrega (2 letras de UF brasileira válida ou "EX" para exterior — Campo G09). Aliases: UF, estado.
entrega.cep (ou CEP)	string	não	CEP do local de entrega (8 dígitos numéricos, opcional — Campo G10; proibido quando uf="EX"). Alias: CEP.
entrega.codigoPais (ou cPais)	string	não	Código BACEN do país (1 a 4 dígitos, padrão "1058" para Brasil — Campo G11 / Regra G11-10 / Rej. 970). Obrigatório e diferente de 1058 quando uf="EX". Alias: cPais.
entrega.pais (ou xPais)	string	não	Nome do país (2 a 60 caracteres, padrão "BRASIL" para operação nacional — Campo G12). Obrigatório quando uf="EX". Aliases: xPais, nomePais.
entrega.telefone (ou fone)	string	não	Telefone de contato no local de entrega (6 a 14 dígitos numéricos, opcional — Campo G13). Aliases: fone, tel.
entrega.email	string	não	Endereço de e-mail do recebedor (1 a 60 caracteres, opcional — Campo G14). Alias: EMAIL.
entrega.ie (ou IE)	string	não	Inscrição Estadual do estabelecimento de entrega (2 a 14 dígitos numéricos, opcional — Campo G15 / Regra G15-10 / Rej. 971). Se omitida ou informada como "ISENTO", a tag opcional <IE> não é gerada. Proibida quando uf="EX". Aliases: IE, inscricaoEstadual.
infCpl (ou informacoesComplementares)	string	não	Informações complementares de interesse do contribuinte (texto livre, ex: dados de Funrural/Senar, número da guia ou dispositivo legal do diferimento). Aliases: informacoesComplementares, informacoes_complementares, observacoes.
infAdFisco (ou informacoesAdicionaisFisco)	string	não	Informações adicionais de interesse do Fisco (texto livre, serializado em <infAdic><infAdFisco>). Aliases: informacoesAdicionaisFisco, informacoes_adicionais_fisco.

↩️ Devolução de Mercadoria (`finalidade: 4`), Substituição Tributária (ICMS ST) & IPI Devolvido

Em notas de devolução de mercadoria (finalidade: 4), a NT 2025.002 da SEFAZ (em vigor desde 05/10/2026) exige que o documento fiscal de origem seja referenciado por item (<DFeReferenciado> dentro de cada <det>) com a chave de 44 dígitos e o número do item (nItem), evitando a Rejeição 321. O grupo <NFref> do cabeçalho <ide> é suprimido automaticamente em devoluções para evitar a Rejeição 1010.

Exemplo de Devolução de Compra com ICMS ST, IPI Devolvido e DFeReferenciado por Item (NT 2025.002):

{
  "modelo": 55,
  "finalidade": 4,
  "naturezaOperacao": "DEVOLUCAO DE COMPRA COM ICMS ST",
  "tipoOperacao": 1,
  "destinatario": {
    "cpfCnpj": "12345678000195",
    "razaoSocial": "Fornecedor Exemplo S.A.",
    "inscricaoEstadual": "123456789",
    "indicadorIe": 1,
    "endereco": {
      "logradouro": "Av. Industrial",
      "numero": "500",
      "bairro": "Distrito Industrial",
      "codigoMunicipio": "3550308",
      "municipio": "São Paulo",
      "uf": "SP",
      "cep": "01001000"
    }
  },
  "items": [
    {
      "codigo": "PRD001",
      "descricao": "Mercadoria Sujeita a Substituicao Tributaria",
      "ncm": "84713012",
      "cest": "0300700",
      "cfop": "5411",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 131.36,
      "valorTotal": 131.36,
      "csosn": "900",
      "baseCalculoIcms": 131.36,
      "aliquotaIcms": 19,
      "baseCalculoIcmsSt": 179.39,
      "aliquotaIcmsSt": 19,
      "valorIcmsSt": 9.13,
      "modalidadeBcSt": 4,
      "devolucaoTributos": {
        "percentualDevolvido": 100.00,
        "valorIpiDevolvido": 0
      },
      "nfeReferenciada": {
        "chaveAcesso": "35260736848840000156550090000000111223152566",
        "nItem": 1
      }
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "90", "valor": 0 }
  ]
}

• Destaque de ICMS ST em NF-e mod. 55 (CSOSN 900/201 ou CST 10/70/90): Ao informar baseCalculoIcmsSt e ao menos aliquotaIcmsSt ou valorIcmsSt (o outro é derivado automaticamente pela plataforma), o sistema gera as tags no item (<vBCST>, <pICMSST>, <vICMSST>) e totaliza no cabeçalho em <ICMSTot><vBCST> e <ICMSTot><vST>. Em NFC-e (modelo 65), o destaque de ST nesses grupos não é suportado.

• Soma Automática no Total da Nota (vNF): O valor de valorIcmsSt (vST) é somado automaticamente ao total da nota (vNF) pela plataforma (atendendo à Regra W16-10 da SEFAZ), eliminando a necessidade de lançá-lo incorretamente em "Outras Despesas" (vOutro).

• Exibição Correta no DANFE: Os campos "Base de Cálculo do ICMS ST" e "Valor do ICMS Substituição" são impressos no quadro de cálculo do imposto do DANFE com os valores destacados no XML.

• Código CEST (Regra N23-10 da SEFAZ): O preenchimento do código CEST de 7 dígitos no campo cest (ex: "0300700" ou com máscara "03.007.00") é exigido pela SEFAZ em operações com Substituição Tributária (obrigatório em CST 10, 70 e CSOSN 201; e em CST 90 e CSOSN 900 quando houver vICMSST > 0), evitando a Rejeição 806.

• Soma de IPI Devolvido (vIPIDevol): O valor informado em valorIpiDevolvido é automaticamente destacado em <ICMSTot><vIPIDevol> e somado ao total da nota (vNF), atendendo à Regra W16-10 da SEFAZ.

• Referenciamento por Item na Devolução (DFeReferenciado): Conforme a NT 2025.002 (em vigor desde 05/10/2026), a chave de 44 dígitos e o número do item (nItem) vão dentro de <det><DFeReferenciado> em cada item devolvido via items[].nfeReferenciada. A plataforma suprime automaticamente o grupo <NFref> do cabeçalho em devoluções para evitar a Rejeição 1010.

🌍 Exportação e Venda para Destinatário no Exterior (`idDest: 3`)

Para emissão de NF-e (modelo 55) com destino internacional (ex: exportação direta com CFOP 7102), a API Notaas simplifica e valida automaticamente as exigências estruturais da SEFAZ MOC 7.0:

Identificação do Destinatário: utilize dest.idEstrangeiro (passaporte ou ID fiscal no exterior, de 1 a 20 caracteres alfanuméricos). Não informe CPF nem CNPJ.
Inscrição Estadual e Indicador: dest.indicadorIE deve ser 9 (Não Contribuinte). Não informe dest.ie (qualquer IE é rejeitado pela SEFAZ, Rejeição 925).
Endereço Internacional: informe uf: "EX". A API preenche automaticamente codigoMunicipio: 9999999 e cidade: "EXTERIOR". O CEP torna-se opcional sem exigência de máscara brasileira.
País amigável: informe o código BACEN do país via codigoPais (ex: 2496 para EUA, 1600 para Reino Unido) ou envie o objeto amigável pais: { "codigo": 2496, "nome": "ESTADOS UNIDOS" }.
Grupo de Exportação (exportacao): obrigatório para saídas internacionais (tpNF: 1 / CFOPs 7xxx). Exige ufSaidaPais (UF brasileira de fronteira/porto, ex: "SP" ou "AM" — nunca "EX") e localEmbarque. O campo localDespacho é opcional.
Modelo Exclusivo: a emissão com exterior é suportada apenas em NF-e modelo 55 (NFC-e modelo 65 rejeita exterior com cStat 707).

Exemplo completo de payload para Venda/Exportação ao Exterior (modelo 55):

{
  "modelo": 55,
  "naturezaOperacao": "EXPORTACAO DIRETA",
  "tipoOperacao": 1,
  "destinoOperacao": 3,
  "dest": {
    "idEstrangeiro": "US987654321",
    "nome": "GLOBAL TRADE SOLUTIONS INC",
    "indicadorIE": 9,
    "email": "[email protected]",
    "endereco": {
      "logradouro": "5th Avenue",
      "numero": "742",
      "complemento": "Suite 100",
      "bairro": "Manhattan",
      "uf": "EX",
      "pais": {
        "codigo": 2496,
        "nome": "ESTADOS UNIDOS"
      }
    }
  },
  "items": [
    {
      "codigo": "EXP-001",
      "descricao": "Castanha do Brasil beneficiada a granel",
      "ncm": "08012100",
      "cfop": "7102",
      "unidade": "KG",
      "quantidade": 1000,
      "valorUnitario": 45.00,
      "valorTotal": 45000.00,
      "cst": "41"
    }
  ],
  "exportacao": {
    "ufSaidaPais": "SP",
    "localEmbarque": "Porto de Santos",
    "localDespacho": "Alfândega do Porto de Santos"
  },
  "pagamentos": [
    { "tipoPagamento": "01", "valor": 45000.00 }
  ]
}

🚢 NF-e de Entrada de Importação (`tpNF: 0`, CFOP 3xxx, DUIMP / DI, II e IPI)

Para emissão de NF-e de entrada de mercadorias importadas do exterior (ex: CFOP 3102, 3101, 3551), a API Notaas suporta nativamente o grupo de Declaração de Importação (<DI>, Grupo I18), Imposto de Importação (<II>, Grupo P01) e IPI na Importação (<IPI>, Grupo O):

Formato DUIMP e DI Numérica: O campo declaracaoImportacao[].numero (ou nDI) aceita até 15 caracteres alfanuméricos — atendendo tanto a DUIMP (ex: "26BR0000000001") quanto a DI clássica (ex: "26/1234567-8", pontuação normalizada automaticamente).
Adições e Itens da Declaração: A DUIMP é estruturada em itens sequenciais (não possui número de adição clássico). Na API Notaas, sequencialAdicao é obrigatório, enquanto numeroAdicao é opcional (dispensado na DUIMP e aceito na DI clássica).
Intermediação da Operação (formaIntermediacao):
- 1 (Conta Própria): Não deve informar CNPJ/CPF nem UF de terceiros.
- 2 (Conta e Ordem) ou 3 (Encomenda): Exige cnpjAdquirente (ou cpfAdquirente) e ufTerceiro (regras SEFAZ I23d-10 e I23e-10).
AFRMM em Transporte Marítimo: Quando a via de transporte for marítima (viaTransporte: 1), informe valorAfrmm (regra SEFAZ I23b-10). O valor 0.00 é aceito para situações de isenção ou não incidência.
Imposto de Importação (impostoImportacao) e IPI na Importação (ipi): Informe a base de cálculo (baseCalculo), despesas aduaneiras (despesasAduaneiras), valor do II (valor) e IOF (valorIof) em impostoImportacao, e opcionalmente o grupo ipi (ex: cst: "00" ou "49" com baseCalculo e aliquota, ou cst: "01".."05" para entradas sem destaque). Os valores de II e de IPI destacado são automaticamente somados ao total da nota (vNF), atendendo às Regras W11-10, W12-10 e W16-10 da SEFAZ, e totalizados em <ICMSTot><vII> e <ICMSTot><vIPI>.
Destinatário / Fornecedor Estrangeiro: Em notas de entrada de importação, o destinatário/remetente estrangeiro deve ter uf: "EX", indicadorIE: 9 e seu identificador internacional em dest.idEstrangeiro.

Exemplo completo de payload para Entrada de Importação com DUIMP (modelo 55):

{
  "modelo": 55,
  "naturezaOperacao": "COMPRA PARA INDUSTRIALIZACAO / IMPORTACAO",
  "tipoOperacao": 0,
  "destinoOperacao": 3,
  "consumidorFinal": 0,
  "destinatario": {
    "nome": "GLOBAL EXPORT CORP",
    "idEstrangeiro": "US88991122",
    "indicadorIE": 9,
    "endereco": {
      "logradouro": "Silicon Ave",
      "numero": "1000",
      "bairro": "Tech Park",
      "uf": "EX",
      "pais": {
        "codigo": 2496,
        "nome": "ESTADOS UNIDOS"
      }
    }
  },
  "items": [
    {
      "codigo": "IMP-001",
      "descricao": "Componente Eletrônico Integrado",
      "ncm": "85176277",
      "cfop": "3102",
      "unidade": "UN",
      "quantidade": 100,
      "valorUnitario": 100.00,
      "valorTotal": 10000.00,
      "cst": "00",
      "aliquotaIcms": 18,
      "baseCalculoIcms": 15432.10,
      "outrasDespesas": 1830.55,
      "declaracaoImportacao": [
        {
          "numero": "26BR0000000001",
          "tipoDocumento": "DUIMP",
          "dataRegistro": "2026-09-10",
          "localDesembaraco": "Porto de Itajaí",
          "ufDesembaraco": "SC",
          "dataDesembaraco": "2026-09-15",
          "viaTransporte": 1,
          "valorAfrmm": 250.00,
          "formaIntermediacao": 1,
          "codigoExportador": "EXP-USA-990",
          "adicoes": [
            {
              "sequencialAdicao": 1,
              "codigoFabricante": "FAB-CHIP-01"
            }
          ]
        }
      ],
      "impostoImportacao": {
        "baseCalculo": 10000.00,
        "despesasAduaneiras": 350.00,
        "valor": 1400.00,
        "valorIof": 0.00
      },
      "ipi": {
        "cst": "00",
        "codigoEnquadramento": "999",
        "baseCalculo": 11400.00,
        "aliquota": 5.00,
        "valor": 570.00
      }
    }
  ],
  "transporte": {
    "modalidadeFrete": 9
  },
  "pagamentos": [
    { "tipoPagamento": "01", "valor": 13800.55 }
  ]
}

🧭 DIFAL Interestadual — Alíquotas Setoriais por Item

Em operações interestaduais para consumidor final não contribuinte (idDest=2, indFinal=1, indIEDest=9), a API gera automaticamente o grupo <ICMSUFDest> (DIFAL) em cada item — a ausência desse grupo causa a rejeição 694. Por padrão, a API usa a alíquota modal da UF de destino e o FCP padrão. Quando o produto tem alíquota setorial diferente da modal (ex: cosméticos, autopeças, eletrônicos), informe os overrides diretamente no item:

aliquotaIcmsUfDest — alíquota interna setorial da UF de destino (%);
percentualFcpUfDest — percentual de FCP da UF de destino (%);
aliquotaInterestadual — alíquota interestadual (%), quando diferente da regra automática (ex: 4% para importados).

Exemplo — cosméticos (NCM 3305) de SP para consumidor final na BA (alíquota setorial 25% + 2% FCP):

{
  "modelo": 55,
  "naturezaOperacao": "Venda de mercadoria",
  "dest": {
    "cpf": "12345678909",
    "nome": "Consumidor Final BA",
    "endereco": {
      "logradouro": "Av. Oceânica",
      "numero": "100",
      "bairro": "Barra",
      "codigoMunicipio": 2927408,
      "cidade": "Salvador",
      "uf": "BA",
      "cep": "40140000"
    }
  },
  "items": [
    {
      "codigo": "COSM-001",
      "descricao": "Shampoo hidratante 300ml",
      "ncm": "33051000",
      "cfop": "6102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 45.90,
      "valorTotal": 91.80,
      "csosn": "102",
      "aliquotaIcmsUfDest": 25,
      "percentualFcpUfDest": 2
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "17", "valor": 91.80 }
  ]
}

• Overrides independentes: informe apenas o campo que difere do padrão — os demais continuam sendo calculados pela tabela da UF.

• Base dupla (CRT=3): no Regime Normal, a base do DIFAL (vBCUFDest) é calculada "por dentro" usando a alíquota informada no override.

• Validação fail-fast: valores fora de faixa (negativos, >= 100) ou não numéricos são rejeitados com HTTP 400 antes do envio à SEFAZ.

Exceção 10 da regra NA01-20 — itens SEM incidência de ICMS não carregam o grupo:

• NÃO geram <ICMSUFDest> (quando informados explicitamente no item): CST 40 (isenta), 41 (não tributada), 50 (suspensão) — e CSOSN 103 (isenção SN), 300 (imune), 400 (não tributada pelo SN). Nesses itens não há ICMS a partilhar e o grupo é suprimido automaticamente; os totais vICMSUFDest/vFCPUFDest do ICMSTot refletem apenas os itens tributados.

• Geram normalmente: CST 00, 10, 20, 51, 60, 70, 90 e CSOSN 101, 102, 201, 500, 900.

• CST/CSOSN omitido ou vazio usa o padrão do regime ("00" / "400" / MEI "102") e mantém o grupo — a supressão exige o código de desoneração explícito no item.

• Override por item: gerarDifal: false suprime o grupo em item tributado (ex: CST 60 / CSOSN 500, a critério do emitente — risco de rejeição 694). gerarDifal: true em item desonerado é rejeitado com HTTP 400: a Exceção 10 não é facultativa.

📦 PIS e COFINS — Classificação Tributária (CST 49, 04-09, 01/02) e Base de Cálculo (Tema 69 STF)

Por padrão, em emitentes de Regime Normal (CRT 3), itens sem CST de PIS/COFINS recebem CST 01 (<PISAliq> / <COFINSAliq>). Para operações desoneradas, monofásicas ou de outras saídas (ex: venda de ativo imobilizado com CFOP 5551/6551), envie os campos cstPis e cstCofins no item:

"49" ou "99": Gera o grupo <PISOutr> / <COFINSOutr>. Se aliquotaPis: 0 e aliquotaCofins: 0, a base de cálculo e o valor são emitidos como 0.00 (a menos que pisBaseCalculo / cofinsBaseCalculo seja informado explicitamente).
"04" a "09": Gera o grupo <PISNT> / <COFINSNT> (não tributado/isento/suspensão/alíquota zero).
"01" ou "02": Gera <PISAliq> / <COFINSAliq> (tributado por alíquota).
Exclusão do ICMS da Base de PIS/COFINS (Tema 69 STF / Lei 14.592/2023): informe pisBaseCalculo (ou vBCPis / impostos.pis.vBC) e cofinsBaseCalculo (ou vBCCofins / impostos.cofins.vBC) com o valor líquido após dedução do ICMS (vProd - vICMS). Quando omitidos, a plataforma usa valorTotal (vProd) como fallback. Os valores de <vPIS> e <vCOFINS> são calculados sobre a base informada e deduzidos automaticamente da base do IBS/CBS (Regra SEFAZ UB16-10).

Exemplo 1 — Exclusão do ICMS da base (Tema 69 STF):

{
  "codigo": "PRD-282",
  "descricao": "Produto Tributado Regime Normal",
  "ncm": "17049020",
  "cfop": "5102",
  "quantidade": 10,
  "valorUnitario": 79.00,
  "valorTotal": 790.00,
  "cst": "00",
  "aliquotaIcms": 12,
  "cstPis": "01",
  "aliquotaPis": 0.65,
  "pisBaseCalculo": 695.20,
  "cstCofins": "01",
  "aliquotaCofins": 3.00,
  "cofinsBaseCalculo": 695.20
}

Exemplo 2 — Venda de Imobilizado (CST 49, alíquota 0):

{
  "codigo": "IMOB-01",
  "descricao": "Mesa de Escritorio Usada",
  "ncm": "94031000",
  "cfop": "5551",
  "quantidade": 1,
  "valorTotal": 800.00,
  "cst": "41",
  "cstPis": "49",
  "cstCofins": "49",
  "aliquotaPis": 0,
  "aliquotaCofins": 0
}

🏭 IPI — Imposto sobre Produtos Industrializados (Grupo O — `IPINT` e `IPITrib`)

Suportado exclusivamente em NF-e modelo 55 (operações internas, interestaduais, importação CFOP 3xxx e exportação CFOP 7xxx; proibido em NFC-e modelo 65 — Regra O01-10 / Rejeição 742). Informe o objeto items[].ipi dentro do item (com cst, codigoEnquadramento, baseCalculo, aliquota, valor, quantidadeUnidade, valorUnidade):

IPI Não Tributado (<IPINT>): ipi.cst = "01", "02", "03", "04", "05" (entradas) ou "51", "52", "53", "54", "55" (saídas). Quando ipi.codigoEnquadramento (cEnq) é omitido, a API preenche "999" automaticamente.
IPI Tributado (<IPITrib>): ipi.cst = "00", "49", "50" ou "99". Informe ipi.baseCalculo + ipi.aliquota (ou ipi.quantidadeUnidade + ipi.valorUnidade); o ipi.valor é calculado automaticamente e somado em <ICMSTot><vIPI> e <vNF>.

Exemplo 1 — Payload completo com IPI Não-Tributado (CST 53, Enquadramento 999):

{
  "modelo": 55,
  "naturezaOperacao": "VENDA DE MERCADORIA",
  "dest": {
    "cnpj": "06307169000180",
    "nome": "EMPRESA DESTINATARIA LTDA",
    "ie": "254906578",
    "indicadorIE": 1,
    "endereco": {
      "logradouro": "ROD BR 101",
      "numero": "1000",
      "bairro": "CENTRO",
      "codigoMunicipio": 4208203,
      "cidade": "ITAJAI",
      "uf": "SC",
      "cep": "88301000"
    }
  },
  "items": [
    {
      "codigo": "1",
      "descricao": "BICA CORRIDA",
      "ncm": "25171000",
      "cfop": "5102",
      "unidade": "TON",
      "quantidade": 40.72,
      "valorUnitario": 50.00,
      "valorTotal": 2036.00,
      "cst": "00",
      "aliquotaIcms": 7,
      "ipi": {
        "cst": "53",
        "codigoEnquadramento": "999"
      },
      "cstPis": "01",
      "aliquotaPis": 0.65,
      "cstCofins": "01",
      "aliquotaCofins": 3.00
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "15", "valor": 2036.00 }
  ]
}

Exemplo 2 — Payload completo com IPI Tributado (CST 50, Alíquota 10%):

{
  "modelo": 55,
  "naturezaOperacao": "VENDA DE PRODUCAO DO ESTABELECIMENTO",
  "dest": {
    "cnpj": "12345678000195",
    "nome": "INDUSTRIA COMPRADORA LTDA",
    "ie": "123456789",
    "indicadorIE": 1,
    "endereco": {
      "logradouro": "AV INDUSTRIAL",
      "numero": "500",
      "bairro": "DISTRITO INDUSTRIAL",
      "codigoMunicipio": 4106902,
      "cidade": "CURITIBA",
      "uf": "PR",
      "cep": "80010100"
    }
  },
  "items": [
    {
      "codigo": "IND-01",
      "descricao": "Produto Industrializado",
      "ncm": "84713012",
      "cfop": "5101",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 1000.00,
      "valorTotal": 1000.00,
      "cst": "00",
      "aliquotaIcms": 12,
      "ipi": {
        "cst": "50",
        "codigoEnquadramento": "999",
        "baseCalculo": 1000.00,
        "aliquota": 10.00
      },
      "cstPis": "01",
      "aliquotaPis": 1.65,
      "cstCofins": "01",
      "aliquotaCofins": 7.60
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "15", "valor": 1100.00 }
  ]
}

🏛️ Funcionamento dos Cálculos Automáticos de IBS/CBS (NT 2025.002-RTC)

Reforma Tributária

O integrador precisa enviar apenas as alíquotas nominais, o CST (3 dígitos) e o código de classificação tributária cClassTrib (6 dígitos). A plataforma Notaas gerencia e calcula automaticamente todo o grupo fiscal e o XML SEFAZ.

1. Base de Cálculo (vBC — Regra UB16-10)

Calculada automaticamente conforme a Regra de Validação SEFAZ UB16-10 (NT 2025.002-RTC), deduzindo ICMS, PIS e COFINS destacados no item: vProd + vFrete + vSeg + vOutro + vII - vDesc - vICMS - vICMSUFDest - vFCP - vFCPUFDest - vPIS - vCOFINS. Não envie vBC manual no grupo ibscbs.

2. Redução de Alíquota (cClassTrib)

Conforme a tabela oficial v1.60 (LC 214/2025), a API aplica o percentual de redução (100%, 60%, 40% ou tributação integral) diretamente sobre a alíquota nominal.

3. Diferimento (CST 510)

Para NF-e (modelo 55) com CST 510, se informados percentuais de diferimento (diferimentoIbsEstadual, etc.), a API calcula o valor diferido e abate o tributo devido.

4. Totais e Transição (2026 vs 2027+)

Em 2025/2026, os valores de IBS/CBS são destacados no XML (IBSCBSTot), mas não somam no valor total do item (vItem) nem no total da nota. A virada para somar ao total ocorre automaticamente em 2027.

Exemplo de Payload com IBS/CBS:

"ibscbs": {
  "cst": "000",
  "cClassTrib": "000001",
  "aliquotaIbsEstadual": 0.1,
  "aliquotaIbsMunicipal": 0,
  "aliquotaCbs": 0.9
}

🚗 Redução de Base de Cálculo ICMS & Grupo de Veículos Novos (MOC 7.0)

MOC 7.0 / SEFAZ

📉 Redução de Base de Cálculo (`percentualReducaoBc`)

Aplicável a CST 20 (obrigatório), CST 51 (opcional quando combinado com diferimento percentualDiferimento / pDif, aceitando também cBenefRBC) e CST 70 (opcional). O percentual de redução deve ser maior que 0 e menor que 100. A base oficial é calculada automaticamente: (vProd - vDesc + vFrete + vSeg + vOutro) × (1 - pRedBC / 100). Se baseCalculoIcms explícito for informado, deve ser compatível com o valor oficial dentro de R$ 0,02 de tolerância.

🚘 Veículos Novos (`veiculoNovo` / `veicProd`)

Exclusivo para NF-e modelo 55 (Grupo JA do MOC 7.0). Em NFC-e (modelo 65), o grupo é terminantemente proibido pela Regra J01-10 (Rejeição SEFAZ 736). Mutuamente exclusivo com o grupo combustivel no mesmo item. Todos os 24 campos são obrigatórios quando o grupo é informado. Campos numéricos (pesoLiquido, pesoBruto, capacidadeMaximaTracao) exigem formato decimal estrito entre 0.0001 e 9999.9999 (máx. 4 casas decimais).

Exemplo de item com Veículo Novo e CST 20 (Redução de BC):

{
  "codigo": "VEIC-001",
  "descricao": "Automovel Sedan 1.0 Flex",
  "ncm": "87032210",
  "cfop": "5102",
  "unidade": "UN",
  "quantidade": 1,
  "valorUnitario": 95000.00,
  "valorTotal": 95000.00,
  "cst": "20",
  "percentualReducaoBc": 33.33,
  "aliquotaIcms": 12,
  "veiculoNovo": {
    "tipoOperacao": 1,
    "chassi": "9BWZZZ377VT004251",
    "codigoCor": "PR01",
    "descricaoCor": "Preto Ninja",
    "potencia": "116",
    "cilindrada": "999",
    "pesoLiquido": 1.1500,
    "pesoBruto": 1.5800,
    "numeroSerie": "SER123456",
    "tipoCombustivelVeiculo": "16",
    "numeroMotor": "MOT987654321",
    "capacidadeMaximaTracao": 2.1000,
    "distanciaEixos": "2560",
    "anoModelo": "2026",
    "anoFabricacao": "2026",
    "tipoPintura": "1",
    "tipoVeiculo": "06",
    "especieVeiculo": "1",
    "situacaoChassi": "N",
    "condicaoVeiculo": 1,
    "codigoMarcaModelo": "123456",
    "codigoCorDenatran": "01",
    "lotacao": "5",
    "tipoRestricao": 0
  }
}

🌾 Nota Fiscal de Produtor Rural Eletrônica (NFP-e — Modelo 55, CST 51 & refNFP)

NT 2018.001 / MOC 7.0

Para emitir NFP-e (NF-e modelo 55 de Produtor Rural), cadastre o projeto do produtor com CPF + Inscrição Estadual ativa + e-CPF A1 (ou CNPJ + e-CNPJ A1 para Produtor PJ). Em emissão própria de Pessoa Física (procEmi=0), a plataforma utiliza automaticamente a série 920 (faixa obrigatória 920–969) e monta a chave de 44 dígitos com o CPF nas posições 7 a 20 (000 + 11 dígitos do CPF).

1. Diferimento Total ou Parcial (`CST 51`)

Informe cst: "51" e percentualDiferimento (pDif de 0 a 100; aliquotaIcms é opcional e assume default 12%). A API calcula vICMSOp, vICMSDif e vICMS = round2(vICMSOp - vICMSDif), somando apenas o ICMS efetivo em <ICMSTot><vICMS>. Suporta redução de BC acumulada (percentualReducaoBc + cBenefRBC).

2. NF de Produtor Referenciada (`refNFP`)

Quando a NF-e referenciar nota em talão/papel ou avulsa estadual (modelos "04" ou "01", em notas com finalidade: 1, 2 ou 3), envie refNFP na raiz do payload com uf, aamm, cpf/cnpj, ie, mod, serie e nNF.

Exemplo completo — Venda de Produção Rural (Série 920, CST 51 Diferimento 100%, PIS/COFINS 06 e refNFP):

{
  "modelo": 55,
  "serie": 920,
  "naturezaOperacao": "VENDA DE PRODUCAO DO ESTABELECIMENTO",
  "tipoOperacao": 1,
  "finalidade": 1,
  "refNFP": [
    {
      "uf": "PR",
      "aamm": "2609",
      "cpf": "11144477735",
      "ie": "1234567890",
      "mod": "04",
      "serie": 0,
      "nNF": 145
    }
  ],
  "dest": {
    "cnpj": "12345678000195",
    "nome": "COOPERATIVA AGROINDUSTRIAL EXEMPLO",
    "ie": "1234567890",
    "indicadorIE": 1,
    "endereco": {
      "logradouro": "Rodovia BR-277",
      "numero": "KM 500",
      "bairro": "Zona Rural",
      "codigoMunicipio": 4104808,
      "cidade": "Cascavel",
      "uf": "PR",
      "cep": "85800000"
    }
  },
  "items": [
    {
      "codigo": "SOJA-GR",
      "descricao": "Soja em graos a granel - Safra 2025/2026",
      "ncm": "12019000",
      "cfop": "5101",
      "unidade": "KG",
      "quantidade": 10000,
      "valorUnitario": 2.15,
      "valorTotal": 21500.00,
      "cst": "51",
      "aliquotaIcms": 12,
      "percentualDiferimento": 100,
      "cstPis": "06",
      "cstCofins": "06"
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "15", "valor": 21500.00 }
  ],
  "infCpl": "ICMS diferido conforme Art. 31 do Anexo VIII do RICMS/PR. Funrural retido por sub-rogacao pela cooperativa adquirente."
}

Valores de `presencaComprador`

Valor	Significado	NF-e	NFC-e	Exige `indicadorIntermediador`?
0	Não se aplica (complementar/ajuste)	✅	❌	—
1	Operação presencial (padrão)	✅	✅	—
2	Não presencial, internet	✅	❌	✅ Sim
3	Não presencial, teleatendimento	✅	❌	✅ Sim
4	Entrega em domicílio (delivery)	❌	✅	✅ Sim
5	Presencial, fora do estabelecimento	✅	✅	—
9	Não presencial, outros	✅	❌	✅ Sim

🏪 Quando usar `indicadorIntermediador` e `intermediador`

Para operações não-presenciais ou delivery (presencaComprador: 2, 3, 4 ou 9, tanto em NF-e mod. 55 quanto em NFC-e mod. 65), a SEFAZ exige a tag <indIntermed> informando se a venda foi realizada diretamente (0) ou via marketplace/plataforma de terceiros (1). Se omitido, a API assume 0 automaticamente (ou 1 caso o objeto intermediador seja enviado). Quando indicadorIntermediador: 1, é obrigatório informar intermediador: { cnpj, idCadIntTran }.

Cenário	`presencaComprador`	`indicadorIntermediador`
Venda por WhatsApp, e-mail ou telefone direto	9	0
E-commerce no site próprio da empresa (NF-e)	2	0
NFC-e com entrega em domicílio (site/WhatsApp próprio)	4	0
Teleatendimento / call center da empresa	3	0
Venda pelo Mercado Livre, Shopee ou Amazon	2 ou 9	1 (+ intermediador)
Pedido pelo iFood ou Rappi (NFC-e delivery)	4	1 (+ intermediador)
Venda presencial (balcão, loja física)	1	omitido no XML

⚠️ Omitir <indIntermed> em operações com presencaComprador 2, 3, 4 ou 9 causa rejeição cStat 434 pela SEFAZ.

Tipos de Pagamento (`tipoPagamento`)

Código	Tipo	Grupo card
01	Dinheiro	—
02	Cheque	—
03	Cartão de Crédito	✅ Auto
04	Cartão de Débito	✅ Auto
05	Crédito Loja	—
10	Vale Alimentação	✅ Auto
11	Vale Refeição	✅ Auto
15	Boleto Bancário	✅ Auto
17	PIX	✅ Auto
18	Transferência	✅ Auto
90	Sem Pagamento	—
99	Outros	—

✅ Auto = sistema gera automaticamente o grupo card com tipoIntegracao=2 (não integrado) quando omitido.

Bandeiras de Cartão (`bandeira`)

Código	Bandeira
01	Visa
02	Mastercard
03	American Express
04	Sorocred
05	Diners Club
06	Elo
07	Hipercard
08	Aura
09	Cabal
99	Outros

Transporte (opcional)

Campo	Tipo	Req?	Descrição
transporte.modalidadeFrete	number	não	0=CIF (remetente), 1=FOB (destinatário), 2=Terceiros, 3=Próprio remetente, 4=Próprio destinatário, 9=Sem frete (padrão: 9)
transporte.transportadora.cnpj	string	não	CNPJ do transportador (14 posições: numérico \d{14} ou alfanumérico [0-9A-Z]{12}\d{2})
transporte.transportadora.cpf	string	não	CPF do transportador (11 dígitos). Alternativo ao CNPJ.
transporte.transportadora.nome	string	não	Nome ou razão social do transportador
transporte.transportadora.ie	string	não	Inscrição Estadual do transportador ou "ISENTO"
transporte.transportadora.endereco	string	não	Endereço completo do transportador
transporte.transportadora.cidade	string	não	Município do transportador
transporte.transportadora.uf	string	não	UF do transportador (2 letras)
transporte.veiculo.placa	string	não	Placa do veículo (formato Mercosul ou antigo)
transporte.veiculo.uf	string	não	UF de registro do veículo
transporte.veiculo.rntc	string	não	Registro Nacional de Transportadores Rodoviários de Carga (ANTT)
transporte.volumes[].quantidade	number	não	Quantidade de volumes transportados
transporte.volumes[].especie	string	não	Espécie do volume (ex: "CAIXA", "FARDO")
transporte.volumes[].marca	string	não	Marca dos volumes
transporte.volumes[].numeracao	string	não	Numeração dos volumes
transporte.volumes[].pesoLiquido	number	não	Peso líquido em kg (3 casas decimais)
transporte.volumes[].pesoBruto	number	não	Peso bruto em kg (3 casas decimais)

Cobrança (opcional — apenas NF-e mod. 55)

Campo	Tipo	Req?	Descrição
cobranca.fatura.numero	string	não	Número da fatura
cobranca.fatura.valorOriginal	number	não	Valor original da fatura em reais
cobranca.fatura.desconto	number	não	Desconto da fatura em reais
cobranca.fatura.valorLiquido	number	não	Valor líquido da fatura em reais
cobranca.parcelas[].numero	string	não	Número da parcela (ex: "001")
cobranca.parcelas[].vencimento	string	não	Data de vencimento (formato AAAA-MM-DD)
cobranca.parcelas[].valor	number	sim	Valor da parcela em reais

⛽ Exemplos de Payload — Combustíveis (Grupo LA)

MOC 7.0

Payloads completos prontos para uso nos cenários mais comuns de emissão com combustíveis. Substitua os dados de dest (CPF/CNPJ, IE, endereço) pelos dados reais do destinatário.

Exemplo 1 — Venda de GLP (Botijão P13, CFOP 5656):

{
  "modelo": 55,
  "naturezaOperacao": "Venda de combustivel",
  "dest": {
    "cpf": "12345678909",
    "nome": "Joao Consumidor",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "100",
      "bairro": "Centro",
      "codigoMunicipio": 4104808,
      "cidade": "Cascavel",
      "uf": "PR",
      "cep": "85800000"
    }
  },
  "items": [{
    "codigo": "GLP-P13",
    "descricao": "Gas Liquefeito de Petroleo P13",
    "ncm": "27111910",
    "cfop": "5656",
    "unidade": "KG",
    "quantidade": 13,
    "valorUnitario": 8.46,
    "valorTotal": 110.00,
    "csosn": "500",
    "combustivel": {
      "codigoAnp": "210203001",
      "descricaoAnp": "GLP",
      "percentualGlp": 100.00,
      "percentualGnn": 0.00,
      "percentualGni": 0.00,
      "ufConsumo": "PR"
    }
  }],
  "pagamentos": [{ "tipoPagamento": "01", "valor": 110.00 }]
}

Exemplo 2 — Venda de Diesel S10 em posto (CFOP 5656, com pBio e encerrante):

{
  "modelo": 55,
  "naturezaOperacao": "Venda de combustivel",
  "dest": {
    "cpf": "12345678909",
    "nome": "Maria Motorista",
    "endereco": {
      "logradouro": "Av Brasil",
      "numero": "500",
      "bairro": "Centro",
      "codigoMunicipio": 4106902,
      "cidade": "Curitiba",
      "uf": "PR",
      "cep": "80010100"
    }
  },
  "items": [{
    "codigo": "DIESEL-S10",
    "descricao": "Diesel S10 Aditivado",
    "ncm": "27101921",
    "cfop": "5656",
    "unidade": "LT",
    "quantidade": 40,
    "valorUnitario": 6.29,
    "valorTotal": 251.60,
    "csosn": "500",
    "combustivel": {
      "codigoAnp": "820101033",
      "descricaoAnp": "OLEO DIESEL B S10 - ADITIVADO",
      "percentualBiodiesel": 14.00,
      "ufConsumo": "PR",
      "origemCombustivel": [
        { "indImport": 0, "cUFOrig": 41, "pOrig": 100.00 }
      ],
      "encerrante": {
        "numeroBico": 3,
        "numeroBomba": 1,
        "numeroTanque": 2,
        "valorInicial": 124560.000,
        "valorFinal": 124600.000
      }
    }
  }],
  "pagamentos": [{ "tipoPagamento": "04", "valor": 251.60 }]
}

Exemplo 3 — Devolução de GLP (CFOP 5661, finalidade 4):

{
  "modelo": 55,
  "naturezaOperacao": "Devolucao de compra de combustivel",
  "finalidade": 4,
  "dest": {
    "cnpj": "12345678000195",
    "nome": "Distribuidora de Gas Ltda",
    "ie": "ISENTO",
    "endereco": {
      "logradouro": "Rod BR-277",
      "numero": "1500",
      "bairro": "Distrito Industrial",
      "codigoMunicipio": 4104808,
      "cidade": "Cascavel",
      "uf": "PR",
      "cep": "85800000"
    }
  },
  "items": [{
    "codigo": "GLP-P13",
    "descricao": "Devolucao - Gas Liquefeito de Petroleo P13",
    "ncm": "27111910",
    "cfop": "5661",
    "unidade": "KG",
    "quantidade": 13,
    "valorUnitario": 8.46,
    "valorTotal": 110.00,
    "csosn": "500",
    "nfeReferenciada": {
      "chaveAcesso": "41260812345678000195550010000001231123456788",
      "nItem": 1
    },
    "combustivel": {
      "codigoAnp": "210203001",
      "descricaoAnp": "GLP",
      "percentualGlp": 100.00,
      "percentualGnn": 0.00,
      "percentualGni": 0.00,
      "ufConsumo": "PR"
    }
  }],
  "pagamentos": [{ "tipoPagamento": "90", "valor": 0.00 }]
}

⚠️ Substitua chaveAcesso pela chave de 44 dígitos da NF-e original autorizada. O valor acima é ilustrativo (DV módulo 11 válido).

Campos Obrigatórios Mínimos

Todo item com CFOP de combustível precisa de pelo menos: codigoAnp (9 dígitos), descricaoAnp e ufConsumo. Para GLP (210203001), adicione os percentuais percentualGlp + percentualGnn + percentualGni = 100.

Validação Automática

A API valida todos os campos antes do enfileiramento: código ANP (9 dígitos), somas de percentuais (GLP=100, origComb=100±0.1%), pBio conforme tabela monofásica (IT 2023.003), e origComb conforme regras LA17/LA18. Erros retornam HTTP 400 com mensagem detalhada.

📍Local de Entrega Diferente do Destinatário (Grupo G — `<entrega>`)

Utilize o objeto entrega (ou localEntrega / local_entrega) sempre que a mercadoria for entregue em um endereço diferente do cadastro do destinatário (dest.endereco) — como centros de distribuição, filiais, obras ou armazéns gerais. O grupo é exclusivo de NF-e (modelo 55), permanece no XML autorizado (<nfeProc>) logo após </dest> e é impresso automaticamente no quadro "Informações do Local de Entrega" nos 3 modelos de DANFE da plataforma.

Exemplo no formato amigável (entrega + endereco):

{
  "entrega": {
    "cnpj": "12.345.678/0001-95",
    "nome": "CD Logística Sul Ltda",
    "ie": "254888999",
    "email": "[email protected]",
    "endereco": {
      "logradouro": "Rodovia BR 101 KM 205",
      "numero": "2500",
      "complemento": "Galpão B - Doca 4",
      "bairro": "Área Industrial",
      "codigoMunicipio": "4216602",
      "municipio": "São José",
      "uf": "SC",
      "cep": "88104000",
      "telefone": "4832419988"
    }
  }
}

Regras Validada Antes do Envio (HTTP 400)

CNPJ numérico ou alfanumérico (Regra G02-10 / cStat 514), CPF (G02a-10 / cStat 541), código IBGE de 7 dígitos compatível com a UF (G07-20/30 / cStat 278/279), uf="EX" no exterior (G07-10 / cStat 515 e G11-10 / cStat 970) e IE (G15-10 / cStat 971).

Obrigatoriedade em Veículos Novos (cStat 478)

Em NF-e normal de saída (finalidade: 1, tipoOperacao: 1) que contenha veículo novo com faturamento direto para consumidor final (items[].veiculoNovo.tipoOperacao: 2), a SEFAZ exige o preenchimento de entrega (Regra C18-20 / Rejeição 478).

{
  "modelo": 55,
  "naturezaOperacao": "Venda de mercadoria entregue em filial/obra",
  "tipoOperacao": 1,
  "finalidade": 1,
  "dest": {
    "cnpj": "86531779000197",
    "nome": "Construtora Matriz S.A.",
    "ie": "250220750",
    "indicadorIE": 1,
    "endereco": {
      "logradouro": "Av. Nicolau João de Souza",
      "numero": "1515",
      "complemento": "Sala 03",
      "bairro": "Palladini",
      "codigoMunicipio": 4211207,
      "cidade": "Morro da Fumaça",
      "uf": "SC",
      "cep": "88837000"
    }
  },
  "entrega": {
    "cnpj": "12345678000195",
    "nome": "Canteiro de Obras Filial Sul",
    "ie": "254888999",
    "email": "[email protected]",
    "endereco": {
      "logradouro": "Rodovia BR 101 KM 205",
      "numero": "2500",
      "complemento": "Galpão B - Doca 4",
      "bairro": "Área Industrial",
      "codigoMunicipio": "4216602",
      "municipio": "São José",
      "uf": "SC",
      "cep": "88104000",
      "telefone": "4832419988"
    }
  },
  "items": [
    {
      "codigo": "MAT-001",
      "descricao": "Estrutura metálica galvanizada",
      "ncm": "73089010",
      "cfop": "5102",
      "unidade": "UN",
      "quantidade": 2,
      "valorUnitario": 1500.00,
      "valorTotal": 3000.00,
      "cst": "00",
      "aliquotaIcms": 12
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "15", "valor": 3000.00 }
  ]
}

Cancelamento

POST/nfe/cancelar🔑 x-api-key

Solicita o cancelamento assíncrono de uma NF-e (modelo 55) ou NFC-e (modelo 65) autorizada junto à SEFAZ via webservice NFeRecepcaoEvento4 (tpEvento=110111).

ℹ️ Prazos de Cancelamento aplicados pela API (contados de dhRecbto)

NF-e (modelo 55): aplica o prazo ordinário nacional de 24h (1.440 min) previsto na Cláusula Décima Segunda do Ajuste SINIEF 07/05 (na redação vigente), com janelas técnicas estendidas nas UFs cujo Web Service (NFeRecepcaoEvento4) recepciona o evento 110111 diretamente sem exigir protocolo administrativo prévio:
- SP: até 480h (20 dias / 28.800 min) — Portaria SRE 80/2025, Art. 10, parágrafo único.
- PR e RS: até 168h (7 dias / 10.080 min).
- CE: até 720h (30 dias / 43.200 min).
- Demais UFs: política da API de 24h (1.440 min). Solicitações acima desse limite são bloqueadas preventivamente pela API com HTTP 422; eventuais procedimentos estaduais para cancelamento extemporâneo devem ser consultados diretamente na regulamentação de cada SEFAZ.
NFC-e (modelo 65): utiliza o limite configurado por UF em uf_nfe_config.nfce_cancel_prazo_min — na configuração vigente em produção, 30min para SP (definido no seed oficial) e SE (configuração observada no ambiente de produção), e 24h (1.440 min) nas demais UFs.
Homologação do Evento (cStat 135 e 155): quando a SEFAZ homologa o cancelamento dentro do prazo ordinário (cStat 135) ou fora do prazo ordinário (cStat 155 — Cancelamento homologado fora de prazo, MOC 7.0 §5.9.4), a plataforma trata ambos como sucesso, transiciona a nota para status="cancelled", persiste o protocolo (cancelProt) e o XML procEventoNFe, e dispara o webhook nfe.cancelled / nfce.cancelled. Se a SEFAZ rejeitar por prazo (cStat 501, Regra 2P12-14) ou retornar evento registrado sem vínculo com a NF-e (cStat 136), a nota é preservada como issued com diagnóstico em errorMessage.

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string (UUID)	sim	ID da nota fiscal autorizada (status="issued") a cancelar
motivo	string	sim	Justificativa do cancelamento (mínimo 15, máximo 255 caracteres — exigência SEFAZ). Quebras de linha e tabulações são sanitizadas automaticamente.

Respostas

Campo	Tipo	Req?	Descrição
202	Accepted	não	Cancelamento aceito e enfileirado para processamento assíncrono via RabbitMQ. Acompanhe via GET /nfe/invoices/{id}/status ou webhook nfe.cancelled / nfce.cancelled.
404	Not Found	não	Invoice não encontrada ou não pertence ao projeto autenticado pela x-api-key.
422	Unprocessable	não	Status diferente de "issued", prazo de cancelamento expirado na UF do emitente, certificado A1 ausente/expirado, ou chaveAcesso/nProt ausentes.

curl -s -X POST \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "uuid-da-nfe",
    "motivo": "Cancelamento solicitado por erro de digitacao nos dados comerciais do pedido"
  }' \
  "https://platform.notaas.com.br/api/v1/nfe/cancelar"

Carta de Correção (CC-e)

POST/nfe/invoices/{id}/correcao🔑 x-api-key

Envia uma Carta de Correção Eletrônica (CC-e) síncrona para sanar erros em campos específicos de uma NF-e autorizada. Não altera impostos, dados de emitente/destinatário ou data de saída.

URL Parameters

Campo	Tipo	Req?	Descrição
id	string	sim	ID da invoice autorizada na Notaas (formato UUID, ex: fbfa230b-9a08-45be-ae65-8c5f73152620). ATENÇÃO: Este é o Invoice ID interno da plataforma, não a chave de acesso de 44 dígitos da SEFAZ.

Body (JSON)

Campo	Tipo	Req?	Descrição
correcao	string	sim	Texto descrevendo as correções de forma detalhada (mínimo 15, máximo 1000 caracteres)

Respostas

Campo	Tipo	Req?	Descrição
200	OK	não	Carta de Correção registrada e vinculada com sucesso na SEFAZ
404	Not Found	não	Nota fiscal não encontrada ou não pertence ao projeto
422	Unprocessable	não	Texto inválido, nota com status diferente de issued, ou rejeição da SEFAZ

curl -s -X POST \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"correcao": "Alteracao do campo GTIN (cEAN e cEANTrib) dos itens da nota: Item 1 para 7898976161169."}' \
  "https://platform.notaas.com.br/api/v1/nfe/invoices/SUA_INVOICE_ID/correcao"

Inutilização de Numeração

POST/nfe/inutilizar🔑 x-api-key

Inutiliza síncronamente uma numeração ou faixa de numeração quebrada/pulada de NF-e (modelo 55) ou NFC-e (modelo 65) junto à SEFAZ via webservice NFeInutilizacao4 (MOC 7.0 §5.3).

ℹ️ Quando inutilizar vs. Reciclagem Automática

Na emissão normal da plataforma, rejeições determinísticas de validação (ex.: cStat 215, 225, 531, 778) reciclam o número automaticamente para a próxima emissão, sem gerar buracos. Utilize POST /nfe/inutilizar quando um número ou faixa tiver sido pulado por ajuste manual do contador da série no painel, migração de outro emissor, ou descarte definitivo de uma tentativa com falha.

A operação é 100% sincronizada sob lock transacional da série: remove os números do pool de reciclagem, avança ultimo_nf se necessário, grava o protocolo na tabela nfe_inutilizacao e, quando inutilizado um único número (nNFIni === nNFFin), cria ou atualiza o registro em nfe_invoices com status="inutilized" e XML oficial <procInutNFe versao="4.00"> disponível no painel e via GET /nfe/invoices/{invoiceId}/xml.

Body (JSON)

Campo	Tipo	Req?	Descrição
nNFIni (ou numero, numeroInicial, n_nf_ini)	number	sim	Número inicial da faixa a inutilizar (inteiro de 1 a 999999999). Para inutilizar um único número, envie apenas numero ou nNFIni.
nNFFin (ou numeroFinal, n_nf_fin)	number	não	Número final da faixa a inutilizar (inteiro >= nNFIni, Regra I03 / Rej. 224). Limite máximo de 10.000 números por requisição (Regra I04 / Rej. 201). Padrão: igual a nNFIni.
justificativa (ou motivo, xJust)	string	sim	Justificativa fiscal da inutilização (mínimo 15, máximo 255 caracteres — exigência SEFAZ). Quebras de linha e tabulações são higienizadas automaticamente conforme XSD TString.
modelo	number	não	55 para NF-e ou 65 para NFC-e (padrão: 55). O leiaute oficial inutNFe_v4.00 exige emitente com CNPJ de 14 posições (numérico \d{14} ou alfanumérico [0-9A-Z]{12}\d{2}).
serie	number	não	Série da numeração (0 a 999, exceto a faixa 910–969 exclusiva de emitente CPF — Regra I02a / Rej. 266). Quando omitida, utiliza a série padrão do projeto para o modelo informado.
ano	number	não	Ano da inutilização com 4 dígitos (2006..anoAtual) ou 2 dígitos (06..AA, Regras I02b/I02c — Rej. 453/454). Padrão: ano corrente no fuso de Brasília (America/Sao_Paulo).
tpAmb (ou ambiente)	number \| string	não	Ambiente SEFAZ: 1 ("producao") ou 2 ("homologacao"). Padrão: ambiente configurado no projeto (tp_amb).

Campos da Resposta (HTTP 200)

Campo	Tipo	Req?	Descrição
inutilized	boolean	não	true quando a inutilização foi homologada (cStat 102) ou confirmada de forma idempotente (cStat 563 / registro existente).
idempotent	boolean	não	true quando a faixa já constava inutilizada no banco ou na SEFAZ (cStat 563 com todos os parâmetros idênticos e nProt presente).
id / inutilizacaoId	string (UUID)	não	ID do registro na tabela nfe_inutilizacao.
invoiceId	string (UUID) \| null	não	ID do registro correspondente em nfe_invoices com status="inutilized" (preenchido quando nNFIni === nNFFin, permitindo consulta em /status e download do XML em /xml). null quando a inutilização abrange múltiplos números.
status	string	não	Sempre "inutilized" nas respostas 200.
idInut	string	não	Identificador oficial de 43 caracteres da tag <infInut Id="ID..."> conforme MOC 7.0 §5.3.1.
modelo / serie / tpAmb	number	não	Modelo (55 ou 65), série e ambiente (1=Produção, 2=Homologação) inutilizados.
nNFIni / numeroInicial	number	não	Número inicial inutilizado.
nNFFin / numeroFinal	number	não	Número final inutilizado.
cStat	number	não	Código de retorno da SEFAZ: 102 (Inutilização de número homologado) ou 563 (Já existe pedido de inutilização com a mesma faixa).
xMotivo	string	não	Mensagem oficial de retorno da SEFAZ.
nProt	string	não	Número do protocolo de homologação da inutilização na SEFAZ.
dhRecbto	string (ISO 8601)	não	Data e hora de homologação na SEFAZ.
xml / xmlProcInutNFe	string (XML)	não	XML fiscal completo de distribuição <procInutNFe versao="4.00" xmlns="http://www.portalfiscal.inf.br/nfe"> contendo <inutNFe> assinado + <retInutNFe> homologado.

Respostas HTTP

Campo	Tipo	Req?	Descrição
200	OK	não	Numeração inutilizada com sucesso (cStat 102) ou confirmada por idempotência (cStat 563 / registro existente).
409	Conflict	não	Inutilização desta faixa já está em andamento (in_progress) ou a faixa informada se sobrepõe parcialmente a outra faixa já inutilizada/pendente na série.
422	Unprocessable	não	Erro de validação local (justificativa < 15 chars, nNFIni > nNFFin, > 10.000 números, série inválida), número já utilizado por nota emitida/cancelada/em processamento/incerta na série (numbersInUse), ou rejeição determinística da SEFAZ.
502	Bad Gateway	não	Falha de comunicação ou status transitório da SEFAZ (cStat 108, 109, 999). Números com resultado incerto pós-conexão permanecem bloqueados preventivamente até a confirmação.

curl -s -X POST \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelo": 55,
    "serie": 1,
    "numero": 234,
    "justificativa": "Quebra de sequencia na numeracao por ajuste manual no painel"
  }' \
  "https://platform.notaas.com.br/api/v1/nfe/inutilizar"

Status & Polling

GET/nfe/invoices/{id}/status🔑 x-api-key

Retorna o status de uma NF-e/NFC-e. Use para polling após receber 202 do /nfe/emitir.

Resposta — Todos os status

Campo	Tipo	Req?	Descrição
invoiceId	string	não	ID da invoice
status	string	não	queued \| processing \| issued \| error \| cancelled \| inutilized
modelo	number	não	55 (NF-e) ou 65 (NFC-e)
tpAmb	number	não	1=Produção, 2=Homologação
createdAt	string (ISO 8601)	não	Quando a invoice foi criada
updatedAt	string (ISO 8601)	não	Última atualização

Campos adicionais — quando issued ou cancelled

Campo	Tipo	Req?	Descrição
numero / nNf	number	não	Número sequencial da nota fiscal (nNf é mantido como alias compatível)
serie	number	não	Série da nota
chaveAcesso	string	não	Chave de acesso de 44 posições (numérica ou alfanumérica nas posições 7 a 20 conforme NT Conjunta 2025.001, com cDV Módulo 11 ASCII - 48)
protocolo / nProt	string	não	Número de protocolo da autorização SEFAZ (nProt é mantido como alias)
codigoStatus / cStat	number	não	Código de status SEFAZ da autorização (100=autorizada, cStat é mantido como alias)
motivo / xMotivo	string	não	Descrição do status SEFAZ (xMotivo é mantido como alias)
dataRecebimento / dhRecbto	string (ISO 8601)	não	Data/hora de autorização na SEFAZ (dhRecbto é mantido como alias)
valorTotal / vNf	number	não	Valor total da nota em reais (vNf é mantido como alias compatível)
valorProdutos / vProd	number	não	Valor total dos produtos em reais (vProd é mantido como alias)
valorTributos / vTrib	number	não	Valor estimado total de tributos da nota em reais (soma dos items[].valorTributos / <ICMSTot><vTotTrib> — Lei 12.741/2012; vTrib é mantido como alias)
naturezaOperacao / natOp	string	não	Natureza da operação (natOp é mantido como alias)
destCpfCnpj	string \| null	não	CPF ou CNPJ do destinatário (null em NFC-e com consumidor não identificado)
destNome	string \| null	não	Nome/Razão Social do destinatário (null em NFC-e com consumidor não identificado)
destUf	string \| null	não	UF do destinatário (null se não informado)
qrCode	string \| null	não	Exclusivo modelo 65 (NFC-e): URL completa do QR Code com hash CSC para impressão térmica em PDV / leitores óticos. null em modelo 55 ou se ausente no XML.
urlChave	string \| null	não	Exclusivo modelo 65 (NFC-e): URL base de consulta pública por chave da SEFAZ estadual. null em modelo 55 ou se ausente no XML.
pdfUrl	string (URL)	não	URL para download do DANFE em PDF. Em modelo 55 gera o DANFE tradicional A4; em modelo 65 gera o cupom fiscal térmico contínuo de 80mm. Requer header x-api-key. Quando cancelada, inclui marca d'água "NOTA CANCELADA".
xmlUrl	string (URL)	não	URL para download do XML de emissão autorizado (nfeProc). Requer header x-api-key.

Campos exclusivos — quando cancelled

Campo	Tipo	Req?	Descrição
cancelledAt	string (ISO 8601)	não	Data/hora do registro do cancelamento na SEFAZ (dhRegEvento)
cancelProt	string	não	Protocolo de homologação do cancelamento na SEFAZ (cStat 135 ou 155)
cancelMotivo	string	não	Justificativa do cancelamento ou mensagem de retorno do evento SEFAZ
cancelXmlUrl	string (URL)	não	URL direta para download do XML do evento de cancelamento (procEventoNFe). Requer header x-api-key.

Campos adicionais — quando error

Campo	Tipo	Req?	Descrição
codigoStatus / cStat	number	não	Código de rejeição SEFAZ (ex: 225, 539, 694)
motivo / xMotivo	string	não	Descrição da rejeição SEFAZ
numero / nNf	number \| null	não	Número sequencial da nota reservado (se houver)
errorMessage	string	não	Mensagem de erro interna para diagnóstico (inclui chNFe e nRec extraídos quando cStat=539/204)
retryCount	number	não	Número de tentativas realizadas

Campos adicionais — quando inutilized

Campo	Tipo	Req?	Descrição
numero / nNf	number	não	Número inutilizado na série
serie	number	não	Série da numeração inutilizada
protocolo / nProt	string	não	Protocolo de homologação da inutilização na SEFAZ (cStat 102/563)
codigoStatus / cStat	number	não	Código de status SEFAZ da inutilização (102 ou 563)
motivo / xMotivo	string	não	Mensagem de retorno da SEFAZ (ex: "Inutilizacao de numero homologado")
dataRecebimento / dhRecbto	string (ISO 8601)	não	Data/hora da homologação da inutilização na SEFAZ
xmlUrl	string (URL)	não	URL para download do XML de inutilização homologado (procInutNFe v4.00). Requer header x-api-key.
message	string	não	"Número inutilizado junto à SEFAZ."

ℹ️ Nomes amigáveis (friendly) e retrocompatibilidade

Para facilitar a integração e unificar o contrato com o restante da plataforma, o endpoint disponibiliza propriedades em português (ex: numero, protocolo, codigoStatus, valorTotal, valorProdutos, valorTributos) lado a lado com os nomes técnicos legados da SEFAZ (nNf, nProt, cStat, vNf, vProd, etc.).

ℹ️ pdfUrl, xmlUrl, cancelXmlUrl e QR Code NFC-e

Essas URLs apontam para os endpoints /nfe/invoices/{id}/danfe e /nfe/invoices/{id}/xml. Ambas requerem o header x-api-key — diferente da NFS-e, os documentos NF-e/NFC-e são gerados sob demanda e não estão em CDN público. Para NFC-e (modelo 65), pdfUrl gera o cupom fiscal térmico de 80mm e o payload expõe qrCode e urlChave diretamente.

{
  "invoiceId": "uuid-da-nfe",
  "status": "issued",
  "modelo": 55,
  "tpAmb": 1,
  "numero": 42,
  "protocolo": "141260000012345",
  "codigoStatus": 100,
  "motivo": "Autorizado o uso da NF-e",
  "dataRecebimento": "2026-05-11T12:00:02-03:00",
  "valorTotal": 99.80,
  "valorProdutos": 99.80,
  "valorTributos": 0,
  "naturezaOperacao": "Venda de mercadoria",
  "nNf": 42,
  "serie": 1,
  "chaveAcesso": "41260512345678000195550010000000421234567890",
  "nProt": "141260000012345",
  "cStat": 100,
  "xMotivo": "Autorizado o uso da NF-e",
  "dhRecbto": "2026-05-11T12:00:02-03:00",
  "vNf": 99.80,
  "vProd": 99.80,
  "vTrib": 0,
  "destCpfCnpj": "12345678000195",
  "destNome": "Empresa Compradora Ltda",
  "destUf": "PR",
  "natOp": "Venda de mercadoria",
  "pdfUrl": "https://platform.notaas.com.br/api/v1/nfe/invoices/uuid-da-nfe/danfe",
  "xmlUrl": "https://platform.notaas.com.br/api/v1/nfe/invoices/uuid-da-nfe/xml",
  "createdAt": "2026-05-11T12:00:00.000Z",
  "updatedAt": "2026-05-11T12:00:05.000Z"
}

Documentos

Após a emissão (status=issued), os endpoints abaixo permitem baixar o DANFE (PDF) e os XMLs fiscais (emissão e cancelamento). Os campos pdfUrl, xmlUrl e cancelXmlUrl na resposta do GET /status apontam diretamente para esses documentos.

GET/nfe/invoices/{id}/danfe🔑 x-api-key

Gera e retorna o DANFE (Documento Auxiliar da Nota Fiscal Eletrônica) em PDF. O formato varia conforme o modelo: NF-e (mod.55) gera A4, NFC-e (mod.65) gera cupom 80mm com QR Code.

⚠️ O que é o DANFE?

O DANFE é a representação gráfica simplificada da nota fiscal. Não é o documento fiscal (o documento fiscal é o XML). O DANFE serve para acompanhar a mercadoria em trânsito e facilitar a consulta da NF-e no portal da SEFAZ.

🎨 Modelos de DANFE (NF-e mod.55)

Projetos no plano Pro ou superior podem customizar o layout do DANFE A4 via Org API ou Dashboard:

Padrão: Layout MOC 7.0 clássico (sem logo).
Retrato com Logo: Layout vertical otimizado com logo do emitente no topo.
Paisagem com Logo: Layout horizontal com canhoto na lateral esquerda e logo.

Acesse a documentação da Org API para saber como configurar o logo e o modelo.

Comportamento por status

Campo	Tipo	Req?	Descrição
issued	200 · PDF	não	DANFE normal. NF-e: A4 retrato. NFC-e: cupom térmico 80mm com QR Code.
cancelled	200 · PDF	não	DANFE com marca d'água "NOTA CANCELADA" sobreposta.
inutilized	200 · PDF	não	DANFE com marca d'água "NÚMERO INUTILIZADO".

Headers da resposta

Campo	Tipo	Req?	Descrição
Content-Type	application/pdf	não	Sempre retorna PDF binário
Content-Disposition	inline	não	Filename no formato danfe-{nNF}-{serie}.pdf (ex: danfe-000000042-001.pdf)
Cache-Control	no-store	não	Não cacheado — o status pode mudar (issued → cancelled) e o watermark deve refletir em tempo real

Erros

Campo	Tipo	Req?	Descrição
422	Unprocessable	não	Nota ainda não emitida (status queued, processing ou error). Faça polling no /status até issued.
404	Not Found	não	Nota não encontrada ou não pertence ao projeto (mesma API key)
429	Too Many Requests	não	Rate limit excedido. Header Retry-After indica quando tentar novamente.
500	Internal Error	não	Falha na geração do PDF (raro). Tente novamente.

# Download do DANFE (PDF)
# O response é o binário PDF — salve com -o ou redirecione

curl -s \
  -H "x-api-key: SUA_API_KEY" \
  "https://platform.notaas.com.br/api/v1/nfe/invoices/{invoiceId}/danfe" \
  -o danfe.pdf

# Ou use a pdfUrl retornada no GET /status:
curl -s \
  -H "x-api-key: SUA_API_KEY" \
  "$(jq -r '.pdfUrl' status.json)" \
  -o danfe.pdf

GET/nfe/invoices/{id}/xml🔑 x-api-key

Retorna o XML fiscal oficial da NF-e/NFC-e. Suporta o download do XML de autorização de emissão (nfeProc para status issued/cancelled), do XML de inutilização homologada (procInutNFe para status inutilized) e do XML de distribuição do evento de cancelamento (procEventoNFe com type=cancel).

Query Parameters

Campo	Tipo	Req?	Descrição
type	string	não	Tipo do XML a baixar: "emission" (padrão) para o nfeProc autorizado (status issued/cancelled) ou procInutNFe homologado (status inutilized); "cancel" para o procEventoNFe do cancelamento homologado.

Comportamento

Campo	Tipo	Req?	Descrição
type=emission (status issued ou cancelled)	200 · application/xml	não	Retorna o XML nfeProc (v4.00) completo (NFe assinada + protNFe de autorização). Filename: nfe-{nNF}-{serie}.xml (ou nfce-{nNF}-{serie}.xml).
type=emission (status inutilized)	200 · application/xml	não	Retorna o XML procInutNFe (v4.00) completo (inutNFe assinado + retInutNFe homologado com cStat 102/563). Filename: nfe-{nNF}-{serie}.xml.
type=cancel (status cancelled)	200 · application/xml	não	Retorna o XML procEventoNFe (v1.00) completo (evento assinado + retEvento homologado SEFAZ com cStat 135/155). Filename: nfe-cancel-{nNF}-{serie}.xml.

Erros

Campo	Tipo	Req?	Descrição
400	Bad Request	não	Parâmetro type inválido (valores permitidos: "emission" ou "cancel")
409	Conflict	não	Status da invoice não permite download (ex.: queued, processing ou error), ou requisição de type=cancel para nota que não está cancelled
404	Not Found	não	Nota não encontrada, ou XML de cancelamento não disponível para esta nota
500	Internal Error	não	XML autorizado temporariamente indisponível

# Download do XML autorizado de emissão (padrão)
curl -s \
  -H "x-api-key: SUA_API_KEY" \
  "https://platform.notaas.com.br/api/v1/nfe/invoices/{invoiceId}/xml" \
  -o nfe.xml

# Ou explicitando type=emission:
curl -s \
  -H "x-api-key: SUA_API_KEY" \
  "https://platform.notaas.com.br/api/v1/nfe/invoices/{invoiceId}/xml?type=emission" \
  -o nfe.xml

Endpoints NF-e / NFC-e

Emissão

↩️ Devolução de Mercadoria (finalidade: 4), Substituição Tributária (ICMS ST) & IPI Devolvido

🌍 Exportação e Venda para Destinatário no Exterior (idDest: 3)

🚢 NF-e de Entrada de Importação (tpNF: 0, CFOP 3xxx, DUIMP / DI, II e IPI)

🧭 DIFAL Interestadual — Alíquotas Setoriais por Item

📦 PIS e COFINS — Classificação Tributária (CST 49, 04-09, 01/02) e Base de Cálculo (Tema 69 STF)

🏭 IPI — Imposto sobre Produtos Industrializados (Grupo O — IPINT e IPITrib)

🏛️ Funcionamento dos Cálculos Automáticos de IBS/CBS (NT 2025.002-RTC)

1. Base de Cálculo (vBC — Regra UB16-10)

2. Redução de Alíquota (cClassTrib)

3. Diferimento (CST 510)

4. Totais e Transição (2026 vs 2027+)

Exemplo de Payload com IBS/CBS:

🚗 Redução de Base de Cálculo ICMS & Grupo de Veículos Novos (MOC 7.0)

📉 Redução de Base de Cálculo (percentualReducaoBc)

🚘 Veículos Novos (veiculoNovo / veicProd)

Exemplo de item com Veículo Novo e CST 20 (Redução de BC):

🌾 Nota Fiscal de Produtor Rural Eletrônica (NFP-e — Modelo 55, CST 51 & refNFP)

1. Diferimento Total ou Parcial (CST 51)

2. NF de Produtor Referenciada (refNFP)

Exemplo completo — Venda de Produção Rural (Série 920, CST 51 Diferimento 100%, PIS/COFINS 06 e refNFP):

Valores de presencaComprador

🏪 Quando usar indicadorIntermediador e intermediador

Tipos de Pagamento (tipoPagamento)

Bandeiras de Cartão (bandeira)

⛽ Exemplos de Payload — Combustíveis (Grupo LA)

Exemplo 1 — Venda de GLP (Botijão P13, CFOP 5656):

Exemplo 2 — Venda de Diesel S10 em posto (CFOP 5656, com pBio e encerrante):

Exemplo 3 — Devolução de GLP (CFOP 5661, finalidade 4):

Campos Obrigatórios Mínimos

Validação Automática

📍Local de Entrega Diferente do Destinatário (Grupo G — <entrega>)

Regras Validada Antes do Envio (HTTP 400)

Obrigatoriedade em Veículos Novos (cStat 478)

Cancelamento

Carta de Correção (CC-e)

Inutilização de Numeração

Status & Polling

Documentos

↩️ Devolução de Mercadoria (`finalidade: 4`), Substituição Tributária (ICMS ST) & IPI Devolvido

🌍 Exportação e Venda para Destinatário no Exterior (`idDest: 3`)

🚢 NF-e de Entrada de Importação (`tpNF: 0`, CFOP 3xxx, DUIMP / DI, II e IPI)

🏭 IPI — Imposto sobre Produtos Industrializados (Grupo O — `IPINT` e `IPITrib`)

📉 Redução de Base de Cálculo (`percentualReducaoBc`)

🚘 Veículos Novos (`veiculoNovo` / `veicProd`)

1. Diferimento Total ou Parcial (`CST 51`)

2. NF de Produtor Referenciada (`refNFP`)

Valores de `presencaComprador`

🏪 Quando usar `indicadorIntermediador` e `intermediador`

Tipos de Pagamento (`tipoPagamento`)

Bandeiras de Cartão (`bandeira`)

📍Local de Entrega Diferente do Destinatário (Grupo G — `<entrega>`)