Issue NF-e

Every tax parameter is optional (nullable); requests that carry only tax codes keep working unchanged. Each parameter is resolved as request value > company profile > platform rate table (CRT=3 companies) > rejection naming the field path (itens[n].impostos..., n starting at 1). Percentages are written as 18 for 18 %; amounts are in BRL. The platform never infers a base reduction, an ST margin, a deferral percentage or a unit tax amount: send them whenever the tax code needs them.

Hard rules (enforced by the tax engine, returned as 10005000):

• CRT 1/4 sellers must use 3-digit CSOSN codes, CRT 2/3 sellers must use 2-digit CST codes; a mismatch is rejected at acceptance with 10004046;
• non-taxpayer buyers (individuals / no IE) cannot use CSOSN 101, the withheld-ST code family, or percentualCreditoSimples; rejected at acceptance with 10004047; MEI sellers (CRT 4) cannot use 101;
• ST codes (10/30/70, 201/202/203) are rejected for non-taxpayer buyers (SEFAZ cStat 600): ST prepays the resale chain and a consumer is the end of it. B2C sales of ST goods use CST 60 / CSOSN 500 (withheld upstream) and, across states, DIFAL;
• State benefit code (cBenef): CST 20/30/40/41/50/51/70/90 must carry codigoBeneficioFiscal; missing it is rejected on submission with 10004020. SEFAZ-SP validates the same set with 930 (CST 90 without a code is rejected too) and rejects the literal SEM CBENEF with 946;
• non-ST codes must not carry substituicaoTributaria (10004044);
• items under ST codes (10/30/60/70, 201/202/203/500) must carry cest; a missing CEST is rejected at acceptance with 10004043 (itens[n].cest);
• CST 90 / CSOSN 900 are composite: send at least one of the own-tax, ST or credit groups.

cliente.inscricaoEstadual is the buyer state registration (NF-e dest/IE). Required for CNPJ buyers: it sets indIEDest=1; a CNPJ buyer without it is rejected with 10004034 before an invoice number is consumed (SEFAZ would reject with 232 after numbering). Not allowed for CPF buyers (10004031). Formatting characters are stripped. Example: "123.456.789.012".

The B2B scenario (ICMS-taxpayer buyer) depends on this field: CSOSN 101 / 201 and CST 10 / 30 / 70 are only valid for taxpayer buyers.

Rules: a return line without a reference → 10004021; a reference on a non-return invoice → 10004022; original not found or not owned by this company → 10004023; original not authorized → 10004024; item not found on the original → 10004025; quantity above the original line (aggregated across lines that reference the same original item) → 10004026. Use inbound CFOPs (1xxx / 2xxx) and inbound PIS/COFINS codes (50–75 / 98, aliquota required); the tax parameters of the original invoice are mirrored per line.

{
  "id": "DEV-000014553",
  "ambienteEmissao": "Producao",
  "finalidade": "Devolucao",
  "notaReferenciada": { "chaveAcesso": "35241204893402000113650010000117691017244265" },
  "pedido": { "presencaConsumidor": "OperacaoPelaInternet", "pagamento": { "formas": [ { "tipo": "SemPagamento", "valor": 0 } ] } },
  "cliente": { "tipoPessoa": "F", "nome": "Demo Client", "cpfCnpj": "88533234775", "endereco": { "uf": "PR", "cidade": "4106902", "logradouro": "Rua Presidente Wilson", "numero": "911", "bairro": "Uberaba", "cep": "81570440" } },
  "itens": [
    {
      "cfop": "2202", "codigo": "000068", "descricao": "Pendrive Kingston 16GB", "ncm": "85235190",
      "quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 28.47,
      "notaReferenciada": { "numeroItem": 1 },
      "impostos": {
        "icms": { "situacaoTributaria": "102" },
        "pis": { "situacaoTributaria": "70", "aliquota": 0 },
        "cofins": { "situacaoTributaria": "70", "aliquota": 0 }
      }
    }
  ]
}

Optional; fuel, energy, specific interstate operations and the 2026 IBS/CBS overrides.

Pairing rules, applicable codes and the per-CST ad rem requirements of these groups are validated by the tax engine, which returns 10005000 with the internal field name.