📚 Documentação da API

🧭 Visão geral

A API do NCM Finder recebe os dados de um produto (nome, descrição, peso, dimensões e/ou EAN) e retorna o código NCM sugerido pela IA, já validado como vigente na tabela da Receita Federal, além da alíquota de IPI vinculada (tabela TIPI), quando disponível.

Você precisa de uma ApiKey para autenticar as requisições. Crie sua conta gratuitamente em /cadastro — cada token vem com uma franquia mensal grátis, renovada automaticamente todo mês.

🔐 Autenticação

Toda requisição autenticada deve enviar sua ApiKey no header X-Api-Key:

X-Api-Key: 00000000-0000-0000-0000-000000000000

Sem o header, ou com uma chave inválida/inativa, a API responde 401 Unauthorized. Gerencie suas chaves (criar, renomear, ativar/desativar) no painel após o cadastro.

📦 Classificar um produto

Todos os campos do corpo são opcionais, mas pelo menos um precisa ser preenchido para a IA ter o que classificar.

curl -X POST https://www.ncmfinder.com/api/classificacao \
  -H "X-Api-Key: SUA-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Notebook Dell Inspiron", "peso": 2.5}'

{
  "ncm": "84713012",
  "hsCode": "847130",
  "ncmProibido": false,
  "descricaoNCM": "Máquinas automáticas para processamento de dados, portáteis, de peso <= 10kg",
  "aliquota": "15",
  "nome": "Notebook Dell Inspiron"
}

aliquota é a alíquota de IPI (tabela TIPI) vinculada ao NCM retornado, quando existir na base — pode vir null se o NCM não tiver TIPI associada. Cada chamada consome 1 crédito da sua franquia mensal ou dos seus créditos extras, independentemente de o resultado já existir numa base interna de referências anteriores — o preço e o comportamento são os mesmos em qualquer caso.

🗂️ Classificar em lote

Aceita uma lista de até 100 produtos (mesmo formato do endpoint acima) em uma única chamada. Cada item é cobrado individualmente — um lote de 100 produtos consome 100 créditos.

curl -X POST https://www.ncmfinder.com/api/classificacao/lote \
  -H "X-Api-Key: SUA-API-KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"nome": "Notebook Dell Inspiron", "peso": 2.5},
    {"nome": "Mouse sem fio", "ean": "7891234567890"}
  ]'

{
  "total": 2,
  "sucessos": 2,
  "erros": 0,
  "resultados": [
    { "ncm": "84713012", "hsCode": "847130", "ncmProibido": false, "descricaoNCM": "...", "aliquota": "15", "nome": "Notebook Dell Inspiron" },
    { "ncm": "84716052", "hsCode": "847160", "ncmProibido": false, "descricaoNCM": "...", "aliquota": "NT", "nome": "Mouse sem fio" }
  ],
  "detalhesErros": []
}

Se um item específico falhar (ex.: sem créditos), o lote continua processando os demais — o item com problema volta em resultados com ncm: null e uma mensagem em detalhesErros, em vez de derrubar a chamada inteira.

💻 Exemplos de código

Integração completa do endpoint de classificação única em três linguagens.

curl -X POST https://www.ncmfinder.com/api/classificacao \
  -H "X-Api-Key: SUA-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"nome": "Notebook Dell Inspiron", "peso": 2.5}'

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "SUA-API-KEY");

var response = await client.PostAsJsonAsync(
    "https://www.ncmfinder.com/api/classificacao",
    new { nome = "Notebook Dell Inspiron", peso = 2.5 }
);

response.EnsureSuccessStatusCode();
var resultado = await response.Content.ReadFromJsonAsync<ClassificacaoResponse>();

Console.WriteLine($"NCM: {resultado.Ncm} | Alíquota IPI: {resultado.Aliquota}");

const response = await fetch('https://www.ncmfinder.com/api/classificacao', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'SUA-API-KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ nome: 'Notebook Dell Inspiron', peso: 2.5 })
});

if (!response.ok) {
  const erro = await response.json();
  throw new Error(erro.mensagem ?? 'Falha ao classificar produto');
}

const resultado = await response.json();
console.log(`NCM: ${resultado.ncm} | Alíquota IPI: ${resultado.aliquota}`);

⚠️ Códigos de erro

✅ Boas práticas

• Envie o máximo de campos que tiver disponível (nome + descrição + EAN) — quanto mais contexto, mais precisa a classificação.
• Prefira o endpoint em lote ao importar catálogos inteiros, para reduzir overhead de rede (a cobrança por item é a mesma).
• Trate 429 com retry e backoff, e acompanhe pelo painel quando sua franquia mensal reseta.
• A classificação por IA tem alta precisão, mas não substitui a validação de um profissional para casos fiscais críticos — a responsabilidade final pela classificação é do usuário da API.