If you sell to or from Brazil, every product needs an NCM code (8 digits) on the invoice (NF-e). Everyone else trading internationally needs the HS code (6 digits). Getting it wrong means rejected invoices, wrong taxes and customs delays. Getting it right usually means someone reading a 10,000-line tariff table.
I built a small API that does the first pass for you: send a product description, get back up to 3 suggestions with confidence scores. Every code it returns exists in the official Siscomex table (Gecex Resolution 926/2026). The model can't invent a code.
How it works
- An LLM reads the description and lists the likely chapters and technical terms.
- A search over the official table (BM25) turns that into a list of real candidate codes.
- The LLM picks from that list only, with classification notes for known traps (e-bikes, vapes, drones, coffee capsules, supplements...).
- Anything not in the table is discarded before the response.
On a set of 28 deliberately tricky products, the first suggestion was right 27 times.
Get a key
Subscribe to the free plan (50 calls/month, no card) on RapidAPI:
π https://rapidapi.com/t0ldstudio/api/ncm-hs-code-classifier
cURL
curl -X POST https://ncm-hs-code-classifier.p.rapidapi.com/v1/classificar \
-H "Content-Type: application/json" \
-H "X-RapidAPI-Key: YOUR_KEY" \
-H "X-RapidAPI-Host: ncm-hs-code-classifier.p.rapidapi.com" \
-d '{"descricao": "Wireless bluetooth earbuds with charging case", "idioma": "en"}'
Real response (trimmed; the full one also has the Portuguese description and the code hierarchy):
{
"produto": "Wireless bluetooth earbuds with charging case",
"sugestoes": [
{
"ncm": "85183000",
"ncm_formatado": "8518.30.00",
"hs6": "851830",
"hs_descricao_en": "Headphones and earphones, whether or not combined with a microphone, and sets consisting of a microphone and one or more loudspeakers",
"confianca": 1.0,
"justificativa": "Wireless bluetooth earbuds are specifically classified as headphones under heading 8518."
}
],
"aviso": "Automated suggestion. Tariff classification is the importer's/taxpayer's responsibility; confirm with a broker.",
"cache": true
}
Python
import requests
URL = "https://ncm-hs-code-classifier.p.rapidapi.com/v1/classificar"
HEADERS = {
"X-RapidAPI-Key": "YOUR_KEY",
"X-RapidAPI-Host": "ncm-hs-code-classifier.p.rapidapi.com",
}
def classify(description: str) -> dict:
r = requests.post(URL, json={"descricao": description, "idioma": "en"}, headers=HEADERS, timeout=60)
r.raise_for_status()
return r.json()["sugestoes"][0]
best = classify("Electric bicycle with pedal assist, 250W motor")
print(best["ncm_formatado"], best["hs6"], best["confianca"]) # 8711.60.00 871160 ...
JavaScript (Node 18+)
const res = await fetch("https://ncm-hs-code-classifier.p.rapidapi.com/v1/classificar", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-RapidAPI-Key": process.env.RAPIDAPI_KEY,
"X-RapidAPI-Host": "ncm-hs-code-classifier.p.rapidapi.com",
},
body: JSON.stringify({ descricao: "Disposable vape with nicotine", idioma: "en" }),
});
const { sugestoes } = await res.json();
console.log(sugestoes[0].ncm_formatado); // 2404.12.00
Classifying a whole catalog
Read a CSV of SKUs, classify each one, and flag low-confidence rows for a human to review:
import csv, time
with open("products.csv") as f_in, open("products_ncm.csv", "w", newline="") as f_out:
reader = csv.DictReader(f_in)
writer = csv.DictWriter(f_out, fieldnames=reader.fieldnames + ["ncm", "hs", "confidence", "review"])
writer.writeheader()
for row in reader:
s = classify(row["title"])
writer.writerow({**row, "ncm": s["ncm"], "hs": s["hs6"],
"confidence": s["confianca"], "review": s["confianca"] < 0.7})
time.sleep(1) # stay under the rate limit
Repeated descriptions are served from cache, so re-running the file is fast.
Other endpoints
-
GET /v1/ncm/{code}: description and hierarchy of any NCM code -
GET /v1/ncm?q=bicycle: full-text search in the official table -
GET /health: status and table version
A word of caution
This is a suggestion engine, not a customs ruling. For anything that goes on an invoice, have your accountant or customs broker confirm the code. The API gives them a strong starting point with the reasoning attached.
Full docs: https://api-production-c57a2db7.up.railway.app
Questions, wrong classifications or feature requests: leave a comment, I read all of them.
Top comments (1)
Constraining the model to pick only from the official table is the right call, and I like that the response carries a disclaimer. One practical addition from the sourcing side: the HS code often depends on facts a one-line product description doesn't contain, such as material composition, power rating, or whether an accessory is sold as a set. Classification traps like e-bikes tend to hinge on motor wattage and speed limits. It could help to have the API return the "missing attributes" that would change the chapter, so the catalog CSV flow can flag rows to enrich rather than just rows with low confidence. Also worth storing the code along with the date and table version used, since tariff schedules get amended and you'll want to explain why an older SKU was classified differently.