Skip to main content
POST /v1/fiscal/resolve-ncm recebe a descrição de um produto em linguagem natural ("camiseta de algodão estampada", "refrigerante cola 2 litros") e devolve até 5 sugestões de NCM, ordenadas por confiança. Pensado para o cadastro de produto: quem está emitindo descreve o que vende, o sistema oferece os códigos mais prováveis e a pessoa confirma.
  • Consultivo, nunca automático: só sugere. Quem escolhe o NCM é você; o endpoint não escreve em cadastro nenhum.
  • Determinístico, sem IA no caminho: uma consulta de similaridade contra o catálogo de produtos. Mesma entrada, mesma resposta.
  • Silêncio honesto: sem produto parecido no catálogo, 200 com sugestoes: [], nunca um NCM inventado.
Este endpoint não substitui a revisão do seu contador e não garante a classificação. garantia é sempre false, o NCM da nota é responsabilidade de quem emite.
Quais campos enviar? A lista completa (todos os parâmetros, tipos e obrigatoriedade, gerada direto do contrato real) está no Catálogo de campos: resolve-ncm.

​
Como chamar

  • descricao é obrigatória: de 3 a 200 caracteres (o texto é normalizado com trim antes da consulta).
  • contexto.cnae é opcional e aceita qualquer máscara ("4711-3/02" ou "4711302"). Ele é validado e registrado, mas não influencia a ordenação nesta versão, está reservado para desempate futuro. Documentamos isso em vez de fingir: não existe hoje uma fonte oficial CNAE → NCM para desempatar, e aqui não entra regra sem fonte.

​
Resposta: descrição com produtos parecidos

  • ncm vem sempre com 8 dígitos, sem máscara.
  • sugestoes vem ordenada por confidence decrescente, no máximo 5 itens.
  • descricao é o produto real mais parecido que carrega aquele NCM no catálogo, serve para você reconhecer o código (“é isso mesmo que eu vendo?”). Não é o texto oficial da nomenclatura: o texto normativo da NCM vive na TIPI, não neste endpoint.

​
Como ler o confidence

confidence (0 a 1) é a similaridade medida entre a sua descrição e o melhor produto parecido do catálogo, descontada quando aquele NCM aparece isolado entre os semelhantes. Não é probabilidade de acerto fiscal e não vira garantia. Régua prática: Descrições genéricas rendem confiança baixa. Detalhar o produto (tipo, material, apresentação, volume) melhora bastante o resultado.

​
Resposta: nada parecido (honesto, não é erro)

Lista vazia não é erro: significa que nenhum produto do catálogo ficou perto o bastante da descrição. Nunca devolvemos um NCM “chutado” para preencher a resposta.

​
Erros de validação

Descrição ausente, com menos de 3 caracteres (após trim), acima de 200 caracteres, ou contexto.cnae fora do formato de 7 dígitos, retorna 400 RFC 7807, com mensagem em português apontando o campo.

​
Cascata de NCM e confirmação do comerciante (em implantação)

A cascata é liberada por parceiro, em piloto. Para o parceiro que não foi liberado, o comportamento acima não muda. Para o parceiro liberado, o Cérebro Fiscal deixa de chutar NCM pelo produto parecido para item sem NCM confiável e segue três degraus:
  1. o Jev percorre a árvore oficial da NCM e só aceita sozinho quando a resposta é alta e bem separada da segunda opção;
  2. um modelo de raciocínio escolhe só entre códigos oficiais vigentes, aplicando as Regras Gerais de Interpretação;
  3. persistindo a dúvida, a emissão assistida não emite: devolve 422 CONFIRMACAO_NCM_NECESSARIA antes de reservar número, com confirmacao_ncm_necessaria (opções com a descrição oficial e em linguagem simples, uma pergunta de fato e o contexto_id).
Com a cascata ligada, esta rota também devolve cascata.finalistas (códigos oficiais vigentes, com a descrição da tabela NCM) ao lado das sugestoes.

​
Confirmar com o comerciante

Envie opcao (uma das opções devolvidas, sem alterar NCM nem CEST) ou resposta (o texto que o comerciante respondeu à pergunta de fato). Resposta que não traz o fato que separa as opções volta com status: "pendente". Contexto de outra empresa, vencido, já usado ou opção fora da lista é recusado sem gravar nada (404, 409 CONFIRMACAO_EXPIRADA/CONFIRMACAO_JA_RESOLVIDA/ CONFIRMACAO_DESATUALIZADA, 422 CONFIRMACAO_OPCAO_INVALIDA). Confirmado, reenvie a emissão: o item sai com o NCM escolhido.

​
O comerciante confirma uma vez

Para item sem GTIN (campo ausente ou SEM GTIN), a confirmação fica lembrada para a empresa: a próxima emissão com a mesma descrição no mesmo emissor sai com o NCM confirmado, sem nova pergunta. A descrição precisa ser a mesma escrita (maiúsculas e espaços repetidos não contam; acento, número, unidade e qualquer palavra contam): leite em pó 400g e leite em pó 800g são produtos diferentes e cada um é confirmado uma vez. Outra empresa, mesmo do mesmo parceiro, nunca aproveita a escolha. Antes de reaproveitar, o código é conferido de novo na tabela vigente na data da emissão. Código extinto ou CEST que saiu da tabela não é reaproveitado: o item volta para a cascata e, na dúvida, para a pergunta. Uma segunda confirmação com escolha diferente para a mesma descrição, enquanto a primeira continua valendo, é recusada com 409 MEMORIA_DESCRICAO_CONFLITO e nada é gravado. Item com GTIN continua resolvido pelo GTIN.

​
Motivo da dúvida: real ou transitório

confirmacao_ncm_necessaria.motivo diz por que o motor não decidiu sozinho, e o reenvio se comporta de um jeito para cada família: Para não insistir num serviço fora do ar, o reenvio consulta o classificador no máximo 3 vezes a cada 10 minutos por item; acima disso devolve o último contexto, ainda com jev_indisponivel, sem nova consulta. Passada a janela, volta a tentar. arvore_ausente fica na família real de propósito: é a tabela NCM do motor que precisa ser carregada, e reenviar não resolve.

​
Corrigir ou revogar a escolha lembrada (sem GTIN)

Se a escolha lembrada para uma descrição sem GTIN estiver errada, corrija-a para a empresa. A próxima emissão com a mesma descrição já sai com o NCM corrigido, e a confirmação antiga deixa de valer:
descricao é a descrição do item como vai na nota (mesma regra de igualdade acima). cest é opcional e precisa estar listado para o NCM. O NCM precisa ser código final vigente na tabela oficial; senão 422 CORRECAO_NCM_NAO_VIGENTE ou CORRECAO_CEST_FORA_DA_TABELA, sem gravar nada. A resposta (200) traz efeito (criada, substituida ou mantida), a escolha anterior e contextosRevogados. Para apagar a escolha e voltar a classificar o produto do zero (nova decisão ou nova pergunta):
As duas rotas valem só para a empresa informada, do parceiro autenticado (empresa de outro parceiro: 403, nada muda), e ficam registradas na auditoria. Produto com GTIN continua sendo corrigido em classification/correct, que exige o ean como GTIN válido (veja “Confirmar ou corrigir a classificação de um produto com GTIN”, abaixo).

​
Código de serviço da NFS-e (em implantação)

A mesma rota fecha a dúvida sobre o código de serviço da NFS-e assistida. Com a cascata de serviço ligada, a NFS-e sem dpsNacional.cTribNac cuja descrição não basta para escolher o código volta 422 CONFIRMACAO_SERVICO_NECESSARIA antes de reservar o número, com confirmacao_servico_necessaria (pergunta de fato e opções oficiais) em details.camposNaoResolvidos[]. Confirme com tipo: "servico":
A opção é { cTribNac }, exatamente como devolvida; ou mande resposta. As recusas são as mesmas acima, e repetir a mesma confirmação devolve o mesmo resultado sem gravar de novo. O código 99.01 (sem incidência) nunca aparece como opção. Confirmado, reenvie a emissão.

​
Confirmar ou corrigir a classificação de um produto com GTIN

Depois da emissão, a empresa pode confirmar que o NCM de um produto está certo ou trocar por outro. As duas rotas gravam a escolha só para a empresa informada (não mexem no catálogo geral) e a próxima nota com o mesmo GTIN já sai com ela:
POST /v1/fiscal/classification/correct recebe o mesmo corpo com o NCM novo. Resposta 201 com o override gravado. O ean identifica o produto, então precisa ser um GTIN de verdade: 8, 12, 13 ou 14 dígitos com o dígito verificador GS1 correto. Espaços nas pontas são removidos. Qualquer outra coisa volta 400 VALIDATION_ERROR em errors[].field: "ean", sem gravar nada: Produto sem GTIN não usa estas rotas. A escolha dele é guardada pela descrição: corrija em POST /v1/fiscal/classification/description-memory/correct (veja “Corrigir ou revogar a escolha lembrada”, acima).

​
O que fazer com a sugestão

O fluxo recomendado é: chamar o endpoint no cadastro do produto, mostrar as sugestões com a descricao de referência, deixar a pessoa escolher (ou digitar outro NCM) e só então gravar o produto no seu sistema. Depois da emissão, o Cérebro Fiscal usa o NCM confirmado para resolver a tributação, e o loop de classification/confirm e classification/correct deixa a classificação melhor a cada nota. Veja também: Cérebro Fiscal, Serviço Padrão por CNAE, CFOP, NCM e CST.