Uma decisão de desenho que vale entender antes de integrar: a API não escolhe o imposto da sua venda. Quem sabe se o produto é tributado, isento ou com substituição tributária é a sua empresa e o seu contador. Você manda os tributos item a item; a API confere se a conta fecha e recusa com o campo exato quando não fecha.
O regime decide o campo
O regime cadastrado na tela Empresa (o CRT) define qual código a API espera no ICMS de cada item:
| Regime | Campo | Códigos aceitos hoje |
|---|---|---|
| Simples Nacional (CRT 1 ou 2) | icms.csosn | 101, 102, 103, 300, 400, 500, 900 |
| Regime normal (CRT 3) | icms.cst | 00, 20, 40, 41, 50, 60, 90 |
| Código | Em palavras |
|---|---|
| CSOSN 101 | Simples, tributada, com permissão de crédito |
| CSOSN 102 | Simples, tributada, sem permissão de crédito |
| CSOSN 500 | ICMS já cobrado antes, por substituição ou antecipação |
| CST 00 | Tributada integralmente |
| CST 20 | Tributada com redução da base de cálculo |
| CST 40 / 41 | Isenta / não tributada |
| CST 60 | ICMS cobrado anteriormente por substituição tributária |
O que a API faz sozinha
- Totais da nota: produtos, descontos, frete, seguro, outras despesas e IPI.
- IBS e CBS da Reforma Tributária: saem em toda nota. Sem o campo ibsCbs no item, vão com as alíquotas de teste de 2026 (0,1% de IBS e 0,9% de CBS). Informe ibsCbs para outro código ou alíquota.
- DIFAL: calculado automaticamente em venda para outro estado a consumidor final não contribuinte.
- Tributos aproximados (Lei 12.741): pelo campo valorTributosAproximados do item ou, sem ele, pela tabela do IBPT para o NCM.
Devolução e nota complementar
Mande finalidade 4 (devolução) ou 2 (complementar) com a lista notasReferenciadas, cada uma com a chave de acesso de 44 dígitos da nota original.
O que ainda não é suportado
- ICMS-ST próprio: CST 10, 30 e 70, e CSOSN 201, 202 e 203. Mercadoria que você vende já com ST cobrada antes (CST 60 / CSOSN 500) funciona.
- Operação com o exterior (importação e exportação).
- Cupom da loja (NFC-e).
A API garante que a nota está bem formada e que a conta fecha. Que o imposto está certo para o seu produto, só o seu contador garante.
Conhecer a API de nota fiscal Documentação completa
Tutorial escrito pela equipe da API em 29 de setembro de 2026, conferido com a versão v1 no ar. Regra fiscal muda: o enquadramento de imposto da sua empresa é com o seu contador. Viu algo desatualizado? Fale com a gente pelo WhatsApp.