Resolver NCM

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

​

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

​

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" }
}

​

Erros de validação

​

O que fazer com a sugestão