Pular para o conteúdo

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çãoEndpoint
Classificar um produto ou serviçoPOST /classificacao-fiscal
Classificar de 1 a 10 de uma vezPOST /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.

  1. 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" }
    }
  2. 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).

CampoObrigatórioRegra
nomesimNome do produto ou serviço, até 150 caracteres
naturezanãomercadoria (padrão) ou servico
descricaonãoDescrição livre, até 500 caracteres. Ajuda a identificar o item
ncmnãoSó para mercadoria. 8 dígitos; pontos aceitos (8471.30.12)
item-lc116nãoSó para serviço. Subitem da LC 116 no formato 1.07 ou 01.07
nbsnãoSó para serviço. 9 dígitos
documentonãonfe, nfce ou nfse. Padrão: nfe para mercadoria, nfse para serviço. nfse só com serviço; nfce não aceita serviço
operacaonãovenda (padrão), devolucao, remessa, bonificacao, transferencia, retorno, compra, nota_credito, nota_debito ou outras
finalidadenãorevenda (padrão), producao_propria, industrializacao, uso_consumo ou ativo_imobilizado
destinatarionãoconsumidor_final (padrão), contribuinte, nao_contribuinte, orgao_publico ou exterior
destinonãointerna (padrão), interestadual ou exterior
data-referencianãoData da operação (AAAA-MM-DD), que decide a legislação e as alíquotas vigentes. Padrão: hoje
respostasnãoObjeto { "id_da_pergunta": valor } com até 30 respostas. Veja Perguntas e respostas
referencianãoTexto 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)

Terminal window
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 status do envelope é 005 sempre que o lote foi aceito; olhe data.falhas e o status de cada item.
  • indice é a posição do item em produtos (começa em 0), e referencia volta 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

BlocoConteúdo
identidadeNCM, CEST, origem e descrição oficial (mercadoria); item da LC 116, NBS, código de tributação nacional (serviço)
icmsCFOP, CST/CSOSN, alíquota interestadual, DIFAL. nao_se_aplica para serviço
issExigibilidade, alíquotas mínima/máxima, local de incidência, retenção. nao_se_aplica para mercadoria
pis_cofinsCST e alíquotas de PIS e COFINS
ipiAlíquota da TIPI, se é não tributado
ibs_cbsCST e cClassTrib da reforma tributária, alíquotas do ano, grupos da NF-e
imposto_seletivoImposto Seletivo (cobrado a partir de 2027)
simplesDados do Simples Nacional para o documento (ex.: op_simp_nac, atividade do Simples na NFS-e)
perguntas_pendentesFatos que só a empresa sabe e que mudam o resultado
validacaoConferência da combinação sugerida contra regras oficiais de rejeição
metadadosVersõ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

ChaveSignificado
valorO valor sugerido. Pode ser texto, número, booleano, objeto ou null (quando depende de uma resposta)
fundamentoDe 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
fontecatalogo_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
confiancaDe 0 a 1
requer_revisaotrue quando o valor precisa de conferência humana. Ausente = não exige
condicaoQuando o valor depende de um fato: texto, pergunta e resposta
avisosObservaçõ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):

ChaveSignificado
codigoNFE_<cStat> ou NFSE_<código> (ex.: NFE_386, NFSE_E0958), ou um código descritivo quando a regra não tem número oficial
severidadeerro, alerta ou info
campoCampo do pacote afetado (ex.: icms.cfop)
mensagemMensagem oficial da rejeição, com o detalhe
regra_oficialNorma e regra (ex.: NT 2026.002 v1.11 ..., regra N12a-40)
fundamentoQuando houver
validadorQuem conferiu (nfe_leiaute, nfse, cclasstrib)

metadados

ChaveSignificado
versao_coreVersão do motor
data_referenciaData usada para a legislação vigente
versoes_tabelasVersão de cada tabela oficial consultada (NCM, TIPI, cClassTrib, CEST…)
requer_revisaotrue se qualquer campo pede revisão
avisos{codigo, mensagem, modulo}: dado do perfil presumido ou ausente, pergunta pendente que afeta o resultado etc.
falhasPartes que não puderam ser calculadas (ex.: tabela oficial indisponível). Lista vazia = tudo calculado
disclaimerO 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:

ChaveSignificado
idIdentificador da pergunta, para usar em respostas
textoA pergunta, pronta para mostrar ao usuário
tipobooleano, escolha ou texto
opcoesValores aceitos, quando tipo é escolha
condicao_oficialO texto da norma que define o fato
fundamentoA norma, como nos campos
campos_afetadosCampos 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: true ou false. escolha: um dos valores de opcoes. 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_pendentes vir vazia ou até você decidir parar. As respostas valem só para aquela chamada: nada é guardado.

Tempo de resposta

  • Com ncm ou item-lc116/nbs informado, 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-fiscal e 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).

statusQuandoO que fazer
005Classificado (individual) ou lote aceitoLeia o pacote (no lote, confira o status de cada item)
400Pedido 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.campoCorrija o campo indicado. Repetir igual não resolve
999Motor indisponível, falha interna ou item que não terminou no prazo do loteTente 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

ItemLimite
Produtos por lote1 a 10
nome150 caracteres
descricao500 caracteres
referencia60 caracteres
respostas30 por produto; valor de texto até 80 caracteres

As chamadas contam no mesmo limite de consumo das demais rotas da v3.