Consulta de NCM

Quem cadastra produto sabe o que o produto é. Não sabe o número de oito dígitos.

Essas três rotas cobrem os dois sentidos dessa tradução — da descrição para o código, e do código de volta para a descrição oficial:

Rota	Para quê
POST /v1/ncm/buscar	você tem a descrição e quer o código
GET /v1/ncm/{codigo}	você tem o código e quer saber o que ele significa
GET /v1/ncm/{codigo}/validar	o código ainda existe na tabela vigente?

Os dados vêm da tabela oficial publicada pelo governo, com a descrição, a vigência e o ato normativo de cada código.

Buscar pela descrição

curl -s https://api.conota.dev/v1/ncm/buscar \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"descricao": "parafuso"}'

{
  "sucesso": true,
  "termo": "parafuso",
  "total": 8,
  "ncms": [
    {
      "codigo": "73181400",
      "descricao": "Parafusos autoperfurantes",
      "inicio_vigencia": "01/04/2022",
      "fim_vigencia": "31/12/9999",
      "ato": "Res Gecex",
      "numero_ato": "272",
      "ano_ato": "2021"
    }
  ]
}

Como o termo casa

O texto é procurado em qualquer posição da descrição oficial. Por isso autoperfurantes encontra Parafusos autoperfurantes, mesmo sendo a segunda palavra.

Mas a busca é literal: não entende sinônimo, plural nem frase.

Envie	Não envie
parafuso	parafuso de aço inox 3/8
amendoim	amendoins torrados

Uma palavra, no singular, escrita como o texto oficial escreveria. Se não vier resultado, tente outra palavra do mesmo produto antes de concluir que ele não tem NCM.

Só códigos de oito dígitos

A tabela oficial também traz os níveis intermediários da árvore — 73 é um capítulo, 7318 é uma posição. Nenhum dos dois vale numa nota: o campo NCM exige o código final de oito dígitos, e mandar 7318 rende rejeição.

Por isso a resposta traz apenas os códigos de oito dígitos por padrão. Para enxergar a árvore inteira — útil para explorar, nunca para emitir — envie:

{ "descricao": "parafuso", "apenas_codigos_finais": false }

Restringir ao começo da descrição

Quando a busca ampla traz resultado demais, so_inicio exige que a descrição comece com o termo:

{ "descricao": "parafuso", "so_inicio": true }

É mais preciso e acha menos. autoperfurantes com so_inicio: true não acha nada.

Busca sem resultado não é erro

Termo que não existe na tabela devolve 200 com a lista vazia:

{ "sucesso": true, "termo": "zzzqqq", "total": 0, "ncms": [] }

Trate total: 0 como "não achei com essa palavra", não como falha.

Consultar um código

curl -s https://api.conota.dev/v1/ncm/73181400 \
  -H "Authorization: Bearer SUA_CHAVE"

Código inexistente devolve 404 com encontrado: false.

Validar um código

curl -s https://api.conota.dev/v1/ncm/73181400/validar \
  -H "Authorization: Bearer SUA_CHAVE"

{ "sucesso": true, "valido": true }

Vale para conferir cadastro antigo antes de emitir: NCM sai de vigência por ato normativo, e um código que funcionava no ano passado pode não existir mais.

Onde isso rende mais

Rodar a validação sobre o catálogo inteiro, uma vez, encontra os produtos que vão levar rejeição — antes de a rejeição acontecer no cliente.

Cota e desempenho

As três rotas consomem cota de ncm, na mesma família de CEP e CNPJ. A cota existe para haver controle, não para limitar uso legítimo.

A tabela fica em cache no Conota. A primeira consulta depois de uma renovação pode demorar um pouco mais; as seguintes respondem na hora.

Pelo MCP

As mesmas consultas existem como ferramentas de MCP — buscar_ncm_por_descricao, consultar_ncm e validar_ncm. É onde a busca por descrição rende mais: perguntar "qual o NCM de um parafuso de aço" é o uso natural de um assistente. Ver MCP.