Endpoints NF-e / NFC-e

Referência completa dos endpoints para emissão, cancelamento, consulta de status e download do DANFE. 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)
naturezaOperacao	string	sim	Descrição da operação fiscal (ex: "Venda de mercadoria")
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.
dest	object	sim	Dados do destinatário (obrigatório para NF-e mod. 55)
dest.cnpj / dest.cpf	string	não	CNPJ (14 dígitos) ou CPF (11 dígitos), apenas números. 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[].cst	string	não	CST do ICMS para CRT 2 ou 3 (ex: "00", "40", "41", "60"). 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, 20 (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 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[].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[].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[].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[].aliquotaPis	number	não	Alíquota PIS do item (%)
items[].aliquotaCofins	number	não	Alíquota COFINS do item (%)
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[].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	object	não	Documento fiscal original referenciado neste item. Alias de conveniência: a chave informada aqui é promovida ao grupo NFref do cabeçalho <ide> (única forma de referenciamento suportada pelo leiaute NF-e 4.00 — não há grupo de referência por item). Em devoluções (finalidade: 4) é obrigatório informar a chave da NF-e original — neste campo, ou em refNFe/nfesReferenciadas na raiz — exceto quando todos os itens têm CFOP 1201, 1202, 1410, 1411, 5921 ou 6921. Aliases aceitos: items[].dfeReferenciado, items[].refNFe e items[].chaveReferenciada.
items[].nfeReferenciada.chaveAcesso	string	sim	Chave de acesso de 44 dígitos da NF-e original que deu origem à mercadoria devolvida.
items[].nfeReferenciada.nItem	number	não	Número do item na NF-e original. Aceito por compatibilidade retroativa, mas deliberadamente ignorado: o leiaute NF-e 4.00 não suporta correlação item↔documento (a NT 2025.002, que a definiria, foi prorrogada pela SEFAZ para 05/10/2026). O valor nunca é serializado no XML.
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.
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, 1=Via marketplace. Obrigatório quando presencaComprador for 2, 3, 4 ou 9.
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). É o mecanismo recomendado para devoluções (finalidade: 4). As três fontes de cabeçalho (refNFe, nfesReferenciadas, nfeReferenciada na raiz) e items[].nfeReferenciada são unidas e deduplicadas — nenhuma chave válida é descartada por outra fonte também estar presente. Máximo de 999 chaves distintas (maxOccurs do schema oficial).
infCpl	string	não	Informações complementares da nota (texto livre)

↩️ Notas de Devolução (`finalidade: 4`), Referenciamento & Imposto Devolvido

Em notas de devolução de mercadoria (finalidade: 4), a NF-e original deve ser referenciada no cabeçalho da nota — via refNFe/nfesReferenciadas na raiz ou items[].nfeReferenciada (todas alimentam o mesmo grupo <NFref> do elemento <ide>), evitando a rejeição 321. Caso haja devolução de tributos (ex: IPI para fornecedor por não-contribuinte ou Simples Nacional), utilize o grupo devolucaoTributos (ou impostoDevol).

Exemplo completo de payload para Devolução (modelo 55):

{
  "modelo": 55,
  "finalidade": 4,
  "naturezaOperacao": "Devolução de Mercadoria",
  "tipoOperacao": 1,
  "refNFe": "35260736848840000156550090000000111223152566",
  "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": "Produto em Devolução",
      "ncm": "84713012",
      "cfop": "5202",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 100.00,
      "valorTotal": 100.00,
      "csosn": "900",
      "aliquotaIcms": 18,
      "devolucaoTributos": {
        "percentualDevolvido": 100.00,
        "valorIpiDevolvido": 12.50
      }
    }
  ],
  "pagamentos": [
    { "tipoPagamento": "90", "valor": 0 }
  ]
}

• 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.

• Destaque em Simples Nacional / MEI (CSOSN 900): A base de cálculo e o ICMS informados no item são totalizados em <ICMSTot><vBC> e <vICMS>, eliminando a rejeição cStat 531.

• Referenciamento no Cabeçalho (NFref): A chave de 44 dígitos da NF-e original vai no grupo <NFref> do elemento <ide> — informe refNFe na raiz (recomendado) ou items[].nfeReferenciada (alias compatível; o campo nItem é aceito, mas ignorado, pois o leiaute NF-e 4.00 não amarra referência por item).

🌍 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 }
  ]
}

🧭 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)

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.
"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).

Exemplo — Venda de Imobilizado com CST 49 e alíquota zero:

{
  "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
}

🏛️ 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)

Calculada automaticamente conforme fórmula SEFAZ: vProd + vFrete + vSeg + vOutro - vDesc. Não envie vBC manual no payload.

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 exclusivamente a CST 20 (obrigatório) 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
  }
}

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)	❌	✅	— (NFC-e)
5	Presencial, fora do estabelecimento	✅	✅	—
9	Não presencial, outros	✅	❌	✅ Sim

🏪 Quando usar `indicadorIntermediador`

Para operações não-presenciais (presencaComprador: 2, 3 ou 9), a SEFAZ exige que você informe se a venda foi realizada diretamente ou via marketplace. Se omitido, a API assume 0 automaticamente (sem intermediador).

Cenário	`presencaComprador`	`indicadorIntermediador`
Venda por WhatsApp, e-mail ou telefone direto	9	0
E-commerce no site próprio da empresa	2	0
Teleatendimento / call center da empresa	3	0
Venda pelo Mercado Livre, Shopee ou Amazon	9	1
Pedido pelo iFood ou Rappi	9	1
Venda presencial (balcão, loja física)	1	omitir

⚠️ Omitir indicadorIntermediador em operações não-presenciais 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 dígitos)
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.

{
  "modelo": 55,
  "naturezaOperacao": "Remessa para conserto",
  "tipoOperacao": 1,
  "finalidade": 1,
  "nfesReferenciadas": ["35250112345678000195550010000012341123456789"],
  "dest": {
    "cnpj": "98765432000199",
    "nome": "Laboratório Óptico Ltda",
    "ie": "123456789",
    "indicadorIE": 1,
    "endereco": {
      "logradouro": "Rua das Lentes",
      "numero": "200",
      "bairro": "Centro",
      "codigoMunicipio": 3550308,
      "cidade": "São Paulo",
      "uf": "SP",
      "cep": "01010100"
    }
  },
  "items": [
    {
      "descricao": "Lente multifocal para conserto",
      "ncm": "90015000",
      "cfop": "5915",
      "quantidade": 2,
      "valorUnitario": 150.00,
      "valorTotal": 300.00,
      "cst": "50",
      "aliquotaIcms": 0
    }
  ],
  "transporte": {
    "modalidadeFrete": 1
  },
  "pagamentos": [
    { "tipoPagamento": "90", "valor": 0 }
  ],
  "infCpl": "Remessa para conserto. ICMS suspenso conforme art. 327 do RICMS/SP. NF-e de venda original ref. na chave."
}

Cancelamento

POST/nfe/cancelar🔑 x-api-key

Solicita o cancelamento assíncrono de uma NF-e ou NFC-e autorizada. Prazo: 24h para NF-e, variável por UF para NFC-e.

Body (JSON)

Campo	Tipo	Req?	Descrição
invoiceId	string	sim	ID da nota a cancelar
motivo	string	sim	Motivo do cancelamento (mínimo 15, máximo 255 caracteres — exigência SEFAZ)

Respostas

Campo	Tipo	Req?	Descrição
202	Accepted	não	Cancelamento aceito e enfileirado para processamento assíncrono
404	Not Found	não	Invoice não encontrada ou não pertence ao projeto
422	Unprocessable	não	Status ≠ issued, prazo expirado, ou chave de acesso ausente

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"

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 dígitos
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 de tributos em reais (IBPT / vTotTrib, 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 136)
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
retryCount	number	não	Número de tentativas realizadas

ℹ️ 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 tanto do XML de autorização de emissão (nfeProc) quanto do XML de distribuição do evento de cancelamento (procEventoNFe).

Query Parameters

Campo	Tipo	Req?	Descrição
type	string	não	Tipo do XML a baixar: "emission" (padrão) para o nfeProc autorizado, ou "cancel" para o procEventoNFe do cancelamento homologado.

Comportamento

Campo	Tipo	Req?	Descrição
type=emission (ou omitido)	200 · application/xml	não	Retorna o XML nfeProc completo (NFe assinada + protNFe de autorização). Filename: nfe-{chaveAcesso}.xml.
type=cancel	200 · application/xml	não	Retorna o XML procEventoNFe (v1.00) completo (evento assinado + retEvento homologado SEFAZ com cStat 135/136). Filename: nfe-cancelamento-{chaveAcesso}.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	Requisição de type=cancel para uma nota fiscal que não se encontra no estado cancelled
422	Unprocessable	não	Nota ainda em processamento ou XML de emissão não disponível
404	Not Found	não	Nota não encontrada, ou XML de cancelamento não disponível para esta nota

# 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

↩️ Notas de Devolução (finalidade: 4), Referenciamento & Imposto Devolvido

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

🧭 DIFAL Interestadual — Alíquotas Setoriais por Item

📦 PIS e COFINS — Classificação Tributária (CST 49, 04-09, 01/02)

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

1. Base de Cálculo (vBC)

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):

Valores de presencaComprador

🏪 Quando usar indicadorIntermediador

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

Cancelamento

Carta de Correção (CC-e)

Status & Polling

Documentos

↩️ Notas de Devolução (`finalidade: 4`), Referenciamento & Imposto Devolvido

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

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

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

Valores de `presencaComprador`

🏪 Quando usar `indicadorIntermediador`

Tipos de Pagamento (`tipoPagamento`)

Bandeiras de Cartão (`bandeira`)