NCM por descrição: sugestão consultiva no cadastro de produto

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.

Como chamar

POST /v1/fiscal/resolve-ncm
{
  "descricao": "refrigerante cola 2 litros"
}

• 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.

POST /v1/fiscal/resolve-ncm
{
  "descricao": "refrigerante cola 2 litros",
  "contexto": { "cnae": "4711-3/02" }
}

Resposta — descrição com produtos parecidos

{
  "data": {
    "sugestoes": [
      {
        "ncm": "22021000",
        "descricao": "REFRIGERANTE LELE COLA 2 LITROS",
        "confidence": 0.77
      },
      {
        "ncm": "22011000",
        "descricao": "COLA REFRIGERANTE PET 2L ICE",
        "confidence": 0.34
      }
    ],
    "garantia": false,
    "mensagemUsuario": "Encontramos sugestão(ões) de NCM para a descrição informada — confirme a que corresponde ao seu produto. Isso não substitui a revisão do seu contador."
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-07-28T18:00:00.000Z" }
}

• 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:

| Faixa | Leitura | |---|---| | ≥ 0.70 | descrição bateu com um grupo grande de produtos do mesmo NCM — forte candidato | | 0.45 – 0.70 | plausível, confira antes de gravar | | < 0.45 | fraco: o catálogo não tem nada realmente parecido, trate como palpite |

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)

{
  "data": {
    "sugestoes": [],
    "garantia": false,
    "mensagemUsuario": "Ainda não consegui sugerir um NCM para esta descrição — detalhe melhor o produto (tipo, material, uso) ou informe o NCM manualmente. Seu contador ou a tabela oficial da NCM confirmam o código certo."
  },
  "meta": { "requestId": "req_abc123", "timestamp": "2026-07-28T18:00:00.000Z" }
}

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 → 400 RFC 7807, com mensagem em português apontando o campo.

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.