Classificação fiscal de produtos e serviços
A classificação fiscal recebe o nome (e, se você tiver, a descrição e o NCM) de um produto ou serviço e devolve a sugestão completa de tributação para a sua empresa: identidade (NCM, CEST, origem, item da LC 116, NBS), ICMS ou ISS, PIS/COFINS, IPI, IBS/CBS, Imposto Seletivo e Simples Nacional. Cada valor vem com a norma que o fundamenta, a fonte e o grau de confiança.
Desde a versão 3.16.0.
Só consulta. A chamada não grava produto, não altera a configuração fiscal e não emite nada.
Para gravar o que for aprovado, use POST /produtos ou o cadastro do
FazNota.
Endpoints
| Operação | Endpoint |
|---|---|
| Classificar um produto ou serviço | POST /classificacao-fiscal |
| Classificar de 1 a 10 de uma vez | POST /classificacao-fiscal/lote |
Diferente da emissão, a classificação responde na hora: não há recibo nem polling. A resposta pode levar alguns segundos (veja Tempo de resposta).
A autenticação é a mesma de todas as rotas da v3 (Authorization: Token <chave> ou
Authorization: Bearer <chave>). A empresa vem da chave: o regime tributário (CRT), a UF, o
município e os demais dados do perfil fiscal são lidos do cadastro da empresa no FazNota. O corpo
não aceita perfil.
-
Classificar um produto
Terminal window curl -X POST $BASE/classificacao-fiscal \-H "Authorization: Token $TOKEN" \-H "Content-Type: application/json" \-d '{"referencia": "SKU-NB15","nome": "NOTEBOOK 15 POLEGADAS 8GB RAM","documento": "nfe","destinatario": "contribuinte","destino": "interestadual"}'Resposta (pacote encurtado, veja Como ler o pacote):
{"status": "005","descricao": "Classificação fiscal realizada.","data": {"referencia": "SKU-NB15","pacote": {"versao_contrato": "2.0","identidade": {"_situacao": "calculado","ncm": {"valor": "84713012","fonte": "ia_identidade","confianca": 0.7,"requer_revisao": true,"avisos": ["Notebook é computador portátil de processamento automático de dados, classificado no subitem 8471.30 (portáteis até 10 kg)..."]},"cest": {"valor": "2102800","fundamento": {"norma": "Convênio ICMS 142/2018","dispositivo": "anexo 20","url": "https://www.confaz.fazenda.gov.br/legislacao/convenios/2018/CV142_18","tabela": "Convenio ICMS 142/18 consolidado ate o Conv. ICMS 180/24"},"fonte": "catalogo_oficial","confianca": 1},"origem": {"valor": "0","fonte": "sugestao","confianca": 0.6,"requer_revisao": true,"avisos": ["Origem nacional (0) presumida."]}},"icms": {"_situacao": "calculado","cfop": {"valor": "6102","fundamento": {"norma": "Convênio SINIEF s/nº, de 15 de dezembro de 1970","dispositivo": "Anexo II - Código Fiscal de Operações e de Prestações - CFOP, CFOP 6.102","url": "https://www.confaz.fazenda.gov.br/legislacao/ajustes/sinief/cvsn_70","tabela": "IT 2023.002 v2.10 - Tabela de CFOP","vigencia": "2006-01-01/…"},"fonte": "regra_oficial","confianca": 0.7,"requer_revisao": true},"cst_csosn": { "valor": "00", "fonte": "regra_oficial", "confianca": 0.7, "requer_revisao": true }},"iss": { "_situacao": "nao_se_aplica", "_motivo": "ISS só se aplica a serviço" },"pis_cofins": {"_situacao": "calculado","cst": { "valor": "01", "fonte": "regra_oficial", "confianca": 1 },"aliquota_pis": { "valor": "0.65", "fonte": "regra_oficial", "confianca": 1 },"aliquota_cofins": { "valor": "3", "fonte": "regra_oficial", "confianca": 1 }},"ipi": {"_situacao": "calculado","_avisos": ["IPI é destacado apenas por estabelecimento industrial ou equiparado (RIPI arts. 8º, 9º e 24) — responda empresa_industrial_ou_equiparada_ipi."],"aliquota_tipi": { "valor": "15", "fonte": "catalogo_oficial", "confianca": 1 }},"ibs_cbs": {"_situacao": "calculado","cst": { "valor": "000", "fonte": "regra_oficial", "confianca": 1 },"cclasstrib": { "valor": "000001", "fonte": "catalogo_oficial", "confianca": 1 },"aliquota_cbs": { "valor": "0.9", "fonte": "catalogo_oficial", "confianca": 1 },"aliquota_ibs_uf": { "valor": "0.1", "fonte": "catalogo_oficial", "confianca": 1 }},"imposto_seletivo": {"_situacao": "nao_se_aplica","_motivo": "O Imposto Seletivo so e cobrado a partir de 1o/01/2027 (EC 132/2023, art. 2o: ADCT art. 126, I, b)."},"simples": {"_situacao": "nao_se_aplica","_motivo": "empresa do regime normal (CRT 3) sem opcao pendente pelo Simples Nacional"},"perguntas_pendentes": [{"id": "empresa_industrial_ou_equiparada_ipi","texto": "O estabelecimento emitente e' industrial ou equiparado a industrial para o IPI (fabrica, importa e revende, ou se enquadra nos arts. 9o a 11 do RIPI)?","tipo": "booleano","condicao_oficial": "Decreto 7.212/2010 (RIPI), arts. 8º, 9º e 24, II e III: ...","fundamento": {"norma": "Decreto 7.212/2010 (RIPI)","dispositivo": "arts. 8º, 9º e 24, II e III","url": "https://www.planalto.gov.br/ccivil_03/_ato2007-2010/2010/decreto/d7212.htm"},"campos_afetados": ["ipi.cenq", "ipi.cst", "ipi.destaca_ipi"]},{"id": "produto_sujeito_st_na_uf","texto": "Este produto está sujeito à substituição tributária do ICMS na UF de destino nesta operação?","tipo": "booleano","campos_afetados": ["icms.cfop", "icms.cst_csosn", "identidade.sujeito_st"]}],"validacao": { "ok": true, "validadores": ["cclasstrib", "nfe_leiaute", "nfse"], "achados": [] },"metadados": {"versao_core": "2.0","data_referencia": "2026-11-07","versoes_tabelas": {"ncm": "Nomenclatura Siscomex vigente em 15/07/2026","tipi": "TIPI atualizada ate o ADE RFB 1/2026 (arquivo de 13/02/2026)","cclasstrib": "IT 2025.002 v1.71"},"requer_revisao": true,"falhas": [],"avisos": [{"codigo": "ICMS_ST_DESCONHECIDO","mensagem": "sujeicao a ST nao decidida (tabela CEST indisponivel ou pergunta 'produto_sujeito_st_na_uf' pendente): CFOP/CST montados sem ST, com revisao","modulo": "icms"}],"disclaimer": "Sugestão automática de classificação fiscal. Confirme as configurações com o seu contador antes de emitir — a responsabilidade pela parametrização fiscal é da empresa emitente."}}},"meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.16.0" }} -
Responder às perguntas pendentes (se houver) e reenviar o mesmo produto
Terminal window curl -X POST $BASE/classificacao-fiscal \-H "Authorization: Token $TOKEN" \-H "Content-Type: application/json" \-d '{"referencia": "SKU-NB15","nome": "NOTEBOOK 15 POLEGADAS 8GB RAM","ncm": "8471.30.12","documento": "nfe","destinatario": "contribuinte","destino": "interestadual","respostas": {"empresa_industrial_ou_equiparada_ipi": false,"produto_sujeito_st_na_uf": false}}'Veja Perguntas e respostas.
Campos do produto
Os nomes seguem o padrão da v3 (kebab-case). Os valores de lista aceitam maiúsculas (NFCE vale
como nfce).
| Campo | Obrigatório | Regra |
|---|---|---|
nome | sim | Nome do produto ou serviço, até 150 caracteres |
natureza | não | mercadoria (padrão) ou servico |
descricao | não | Descrição livre, até 500 caracteres. Ajuda a identificar o item |
ncm | não | Só para mercadoria. 8 dígitos; pontos aceitos (8471.30.12) |
item-lc116 | não | Só para serviço. Subitem da LC 116 no formato 1.07 ou 01.07 |
nbs | não | Só para serviço. 9 dígitos |
documento | não | nfe, nfce ou nfse. Padrão: nfe para mercadoria, nfse para serviço. nfse só com serviço; nfce não aceita serviço |
operacao | não | venda (padrão), devolucao, remessa, bonificacao, transferencia, retorno, compra, nota_credito, nota_debito ou outras |
finalidade | não | revenda (padrão), producao_propria, industrializacao, uso_consumo ou ativo_imobilizado |
destinatario | não | consumidor_final (padrão), contribuinte, nao_contribuinte, orgao_publico ou exterior |
destino | não | interna (padrão), interestadual ou exterior |
data-referencia | não | Data da operação (AAAA-MM-DD), que decide a legislação e as alíquotas vigentes. Padrão: hoje |
respostas | não | Objeto { "id_da_pergunta": valor } com até 30 respostas. Veja Perguntas e respostas |
referencia | não | Texto livre seu (o SKU, por exemplo), até 60 caracteres. Volta igual na resposta. Útil no lote |
Quando um campo de uso fica de fora, o motor aplica o padrão e registra em
pacote.entrada.padroes_aplicados (ex.: "uso.operacao=venda").
Lote (até 10 por chamada)
curl -X POST $BASE/classificacao-fiscal/lote \ -H "Authorization: Token $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "produtos": [ { "referencia": "SKU-1", "nome": "ARROZ BRANCO TIPO 1 5KG", "ncm": "1006.30.21", "documento": "nfce" }, { "referencia": "SKU-2", "nome": "REFRIGERANTE COLA 2L", "documento": "nfce" }, { "referencia": "SRV-1", "natureza": "servico", "nome": "CORTE DE CABELO MASCULINO" }, { "referencia": "SKU-4", "nome": "CAFE TORRADO 500G", "ncm": "123" } ] }'{ "status": "005", "descricao": "Lote de classificação fiscal processado.", "data": { "total": 4, "sucesso": 3, "falhas": 1, "resultados": [ { "indice": 0, "referencia": "SKU-1", "status": "005", "descricao": "Classificação fiscal realizada.", "pacote": { } }, { "indice": 1, "referencia": "SKU-2", "status": "005", "descricao": "Classificação fiscal realizada.", "pacote": { } }, { "indice": 2, "referencia": "SRV-1", "status": "005", "descricao": "Classificação fiscal realizada.", "pacote": { } }, { "indice": 3, "referencia": "SKU-4", "status": "400", "descricao": "ncm deve ter 8 dígitos.", "campo": "ncm" } ] }, "meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.16.0" }}- Cada item tem status próprio. Um item recusado ou com falha não derruba os outros. O
statusdo envelope é005sempre que o lote foi aceito; olhedata.falhase ostatusde cada item. indiceé a posição do item emprodutos(começa em 0), ereferenciavolta como você mandou. Os resultados vêm na mesma ordem do pedido.- Os itens são processados em paralelo. Um item que não termina no prazo do lote volta com
status: "999"e a descrição “O item não terminou no prazo do lote. Reenvie este produto.” Reenvie só ele. - Lote vazio ou com mais de 10 produtos é recusado inteiro (
status: "400",data.campo: "produtos"). Para mais itens, divida em várias chamadas.
Como ler o pacote
O pacote é o resultado do motor de classificação fiscal do FazNota (contrato 2.x, chaves em
snake_case). Contrato aditivo: blocos, campos e códigos novos podem aparecer, e chave desconhecida
deve ser ignorada.
Blocos
| Bloco | Conteúdo |
|---|---|
identidade | NCM, CEST, origem e descrição oficial (mercadoria); item da LC 116, NBS, código de tributação nacional (serviço) |
icms | CFOP, CST/CSOSN, alíquota interestadual, DIFAL. nao_se_aplica para serviço |
iss | Exigibilidade, alíquotas mínima/máxima, local de incidência, retenção. nao_se_aplica para mercadoria |
pis_cofins | CST e alíquotas de PIS e COFINS |
ipi | Alíquota da TIPI, se é não tributado |
ibs_cbs | CST e cClassTrib da reforma tributária, alíquotas do ano, grupos da NF-e |
imposto_seletivo | Imposto Seletivo (cobrado a partir de 2027) |
simples | Dados do Simples Nacional para o documento (ex.: op_simp_nac, atividade do Simples na NFS-e) |
perguntas_pendentes | Fatos que só a empresa sabe e que mudam o resultado |
validacao | Conferência da combinação sugerida contra regras oficiais de rejeição |
metadados | Versões das tabelas, avisos, falhas e o aviso do contador |
O pacote também traz entrada (o pedido como o motor o entendeu, com os padrões aplicados) e
perfil_usado (o perfil fiscal da empresa que foi usado: CRT, regime, UF e de onde veio cada dado).
Todo bloco tem _situacao: calculado, nao_se_aplica, nao_calculado ou pendente_de_norma
(depende de norma ainda não publicada). Pode ter também _motivo (por que não se aplica) e _avisos
(textos para quem confere). Os demais campos do bloco são campos fiscais.
Cada campo
| Chave | Significado |
|---|---|
valor | O valor sugerido. Pode ser texto, número, booleano, objeto ou null (quando depende de uma resposta) |
fundamento | De onde vem: norma, dispositivo, url, regulamento (texto do dispositivo), tabela (versão da tabela oficial) e vigencia (início/fim, … = sem fim). Só as chaves conhecidas aparecem |
fonte | catalogo_oficial (tabela oficial), regra_oficial (regra de leiaute ou norma), perfil_empresa (cadastro da empresa), informado (veio do seu pedido), ia_identidade / cache_identidade (identificação do item), pratica_da_base, sugestao, anexo_viii_sugestao, pendente_de_norma |
confianca | De 0 a 1 |
requer_revisao | true quando o valor precisa de conferência humana. Ausente = não exige |
condicao | Quando o valor depende de um fato: texto, pergunta e resposta |
avisos | Observações sobre o valor |
Só catalogo_oficial, regra_oficial e perfil_empresa sustentam um valor como certo. As demais
fontes vêm com requer_revisao. A identificação por IA nunca decide tributação: ela só aponta o NCM
ou o serviço, e a tributação sai das tabelas e regras oficiais.
validacao
ok é false quando algum achado tem severidade erro. Cada item de achados é uma combinação
que a SEFAZ ou o Ambiente Nacional da NFS-e rejeitaria (rejeições como 386, 590, 725, 930, E0958):
| Chave | Significado |
|---|---|
codigo | NFE_<cStat> ou NFSE_<código> (ex.: NFE_386, NFSE_E0958), ou um código descritivo quando a regra não tem número oficial |
severidade | erro, alerta ou info |
campo | Campo do pacote afetado (ex.: icms.cfop) |
mensagem | Mensagem oficial da rejeição, com o detalhe |
regra_oficial | Norma e regra (ex.: NT 2026.002 v1.11 ..., regra N12a-40) |
fundamento | Quando houver |
validador | Quem conferiu (nfe_leiaute, nfse, cclasstrib) |
metadados
| Chave | Significado |
|---|---|
versao_core | Versão do motor |
data_referencia | Data usada para a legislação vigente |
versoes_tabelas | Versão de cada tabela oficial consultada (NCM, TIPI, cClassTrib, CEST…) |
requer_revisao | true se qualquer campo pede revisão |
avisos | {codigo, mensagem, modulo}: dado do perfil presumido ou ausente, pergunta pendente que afeta o resultado etc. |
falhas | Partes que não puderam ser calculadas (ex.: tabela oficial indisponível). Lista vazia = tudo calculado |
disclaimer | O aviso de conferência pelo contador |
Perguntas e respostas
Alguns dados só a empresa sabe, por exemplo: se ela é industrial para o IPI, se o produto está na
substituição tributária na UF de destino, qual a alíquota de ISS da lei do município. O motor nunca
presume esses fatos. Ele devolve o pacote com o que dá para afirmar e lista o que falta em
perguntas_pendentes:
| Chave | Significado |
|---|---|
id | Identificador da pergunta, para usar em respostas |
texto | A pergunta, pronta para mostrar ao usuário |
tipo | booleano, escolha ou texto |
opcoes | Valores aceitos, quando tipo é escolha |
condicao_oficial | O texto da norma que define o fato |
fundamento | A norma, como nos campos |
campos_afetados | Campos do pacote que mudam com a resposta (ex.: ipi.cst) |
Para responder, reenvie o mesmo produto com respostas:
{ "natureza": "servico", "nome": "CORTE DE CABELO MASCULINO", "respostas": { "aliquota_iss_municipio": "2", "atividade_simples_nfse": "07" }}booleano:trueoufalse.escolha: um dos valores deopcoes.texto: texto de até 80 caracteres.- Os identificadores têm só letras minúsculas, números e
_(até 80 caracteres). No máximo 30 respostas por produto. - Uma resposta pode revelar outra pergunta. Repita até
perguntas_pendentesvir vazia ou até você decidir parar. As respostas valem só para aquela chamada: nada é guardado.
Tempo de resposta
- Com
ncmouitem-lc116/nbsinformado, a resposta costuma levar poucos segundos. - Sem o código, o motor identifica o item por IA, o que leva mais tempo.
- Configure o timeout do seu cliente HTTP com folga: 70 segundos para
POST /classificacao-fiscale 90 segundos para o lote.
Erros
Todas as respostas são HTTP 200, com o resultado em status, como no resto da v3. A exceção são as
falhas de autenticação (401/403) e o limite de consumo (429).
status | Quando | O que fazer |
|---|---|---|
005 | Classificado (individual) ou lote aceito | Leia o pacote (no lote, confira o status de cada item) |
400 | Pedido fora do formato (nome ausente, ncm sem 8 dígitos, ncm em serviço, nbs ou item-lc116 em mercadoria, data fora de AAAA-MM-DD, JSON inválido, lote vazio ou com mais de 10) ou recusado pelo motor (valor fora da lista, nfse com mercadoria…). O motivo vem na descricao e o campo em data.campo | Corrija o campo indicado. Repetir igual não resolve |
999 | Motor indisponível, falha interna ou item que não terminou no prazo do lote | Tente de novo em instantes. Cite o meta.request_id no suporte se persistir |
Exemplo de recusa:
{ "status": "400", "descricao": "ncm é só para mercadoria; para serviço use item-lc116 e nbs.", "data": { "campo": "ncm" }, "meta": { "request_id": "req_...", "timestamp": "...", "api_version": "3.16.0" }}No individual, a referencia enviada também volta em data quando há recusa.
Limites
| Item | Limite |
|---|---|
| Produtos por lote | 1 a 10 |
nome | 150 caracteres |
descricao | 500 caracteres |
referencia | 60 caracteres |
respostas | 30 por produto; valor de texto até 80 caracteres |
As chamadas contam no mesmo limite de consumo das demais rotas da v3.