> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolver NCM

> POST /v1/fiscal/resolve-ncm: sugestões de NCM a partir da descrição do produto, consultivo e sem garantia.

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

<Warning>
  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.
</Warning>

<Info>
  **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**](/api-reference/campos-fiscal-resolve-ncm).
</Info>

## Como chamar

```json theme={null}
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.

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

## Resposta: descrição com produtos parecidos

```json theme={null}
{
  "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)

```json theme={null}
{
  "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, retorna **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](/guides/cerebro-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](/guides/cerebro-fiscal),
[Serviço Padrão por CNAE](/guides/resolve-servico-padrao),
[CFOP, NCM e CST](/conceitos/cfop-ncm-cst).