API NCM & HS Code
Descrição do produto → NCM de 8 dígitos + código HS, em uma chamada.
Product description → Brazilian NCM + international HS code, in one call.
Chave grátis (50 chamadas/mês) · Free API key →
Por que usar
- Nenhum código inventado. Toda sugestão é conferida contra a tabela NCM vigente do Siscomex; código que não existe é descartado antes de sair da API.
- Explica a escolha. Cada NCM vem com confiança (0–1), justificativa e o caminho completo na TIPI (capítulo → posição → subposição → item).
- NCM + HS juntos. O HS de 6 dígitos (com descrição em inglês) serve para exportação, marketplaces internacionais e despachantes.
- Entende português e inglês, inclusive títulos de anúncio ("fone bluetooth tws", "kit 3 panelas antiaderente").
- Barato em lote. Descrições repetidas voltam do cache sem consumir crédito de IA.
Para quem: ERPs e emissores de NF-e, integradores de marketplace (Mercado Livre, Shopee, Amazon), e-commerce com catálogo grande, escritórios contábeis e despachantes.
Início rápido
Base URL: https://api-production-c57a2db7.up.railway.app · Autenticação: assine qualquer plano (inclusive o grátis) na RapidAPI e use os headers X-RapidAPI-Key / X-RapidAPI-Host que ela mostra — ou o header X-API-Key se você tiver chave direta.
curl -X POST "$BASE/v1/classificar" \
-H "X-API-Key: SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"descricao": "Fone de ouvido bluetooth sem fio com microfone"}'import requests
r = requests.post(
"https://api-production-c57a2db7.up.railway.app/v1/classificar",
headers={"X-API-Key": "SUA_CHAVE"},
json={"descricao": "Fone de ouvido bluetooth sem fio com microfone"},
timeout=30,
)
r.raise_for_status()
melhor = r.json()["sugestoes"][0]
print(melhor["ncm_formatado"], melhor["confianca"], melhor["hs6"])const r = await fetch("https://api-production-c57a2db7.up.railway.app/v1/classificar", {
method: "POST",
headers: { "X-API-Key": "SUA_CHAVE", "Content-Type": "application/json" },
body: JSON.stringify({ descricao: "Fone de ouvido bluetooth sem fio com microfone" }),
});
const { sugestoes } = await r.json();
console.log(sugestoes[0].ncm_formatado, sugestoes[0].confianca);Resposta
{
"produto": "Fone de ouvido bluetooth sem fio com microfone",
"sugestoes": [
{
"ncm": "85183000",
"ncm_formatado": "8518.30.00",
"descricao": "Fones de ouvido (Auscultadores e auriculares), mesmo combinados com um microfone, ...",
"caminho": [
{"codigo": "85", "descricao": "Máquinas, aparelhos e materiais elétricos, e suas partes; ..."},
{"codigo": "8518", "descricao": "Microfones e seus suportes; alto-falantes ..."},
{"codigo": "85183000", "descricao": "Fones de ouvido ..."}
],
"folha": true,
"hs6": "851830",
"hs_descricao_en": "Headphones and earphones, whether or not combined with a microphone ...",
"confianca": 0.95,
"justificativa": "Fone de ouvido com microfone integrado, posição 8518.30."
}
],
"observacao": "",
"tabela_ncm": "Resolução Gecex nº 926/2026 (Vigente em 15/11/2026)",
"aviso": "Sugestão automática. A classificação fiscal é responsabilidade do contribuinte; confirme com seu contador.",
"cache": false
}
Endpoints
| Método e rota | O que faz | Consome crédito |
|---|---|---|
POST /v1/classificar | Descrição → até 3 NCMs + HS. Corpo: descricao (3–500 caracteres, obrigatório), gtin (EAN 8–14 dígitos, opcional), idioma (pt ou en, idioma da justificativa). | 1 por chamada (falhas são estornadas) |
GET /v1/ncm/{codigo} | Consulta um NCM (com ou sem pontos): descrição, caminho na TIPI, HS6. | Não |
GET /v1/ncm?q=texto&limite=10 | Busca textual na tabela NCM, sem IA. | Não |
GET /health | Status e versão da tabela. | Não |
Referência interativa (OpenAPI/Swagger): /docs · ReDoc: /redoc · Esquema: /openapi.json
Erros
| Código | Significado |
|---|---|
| 401 | Chave ausente ou inválida. |
| 402 | Sem créditos. |
| 403 | Assinatura RapidAPI inválida (header de proxy incorreto). |
| 404 | NCM não existe na tabela vigente. |
| 422 | Entrada inválida (ex.: descrição curta demais) ou não foi possível classificar com segurança. Crédito estornado. |
| 429 | Limite de requisições por minuto excedido. |
| 502 | Falha temporária do provedor de IA. Crédito estornado; tente de novo. |
Boas práticas
- Descreva o que é, material e uso ("garrafa térmica de aço inox 1 L" é melhor que "garrafa 1L").
- Use a confiança: abaixo de 0,7, mande para revisão humana; leia o campo
observacao. - Guarde o NCM escolhido no seu cadastro — não reclassifique o mesmo produto a cada venda.
⚠️ A API sugere a classificação; ela não substitui a análise de um contador ou despachante. A responsabilidade pela classificação fiscal é do contribuinte. Veja os Termos de Uso.
English summary
REST API that turns a free-text product description into up to three Brazilian NCM codes (8 digits) plus the 6-digit HS code with its English description. Every code is validated against the official Siscomex NCM table, so the API never returns a non-existent code. Send "idioma": "en" for English justifications. Get a free key (50 calls/month) or a paid plan on RapidAPI. Suggestions are informational — always confirm with a customs broker or accountant.