Klassifizierung
Zolltarifliche Klassifizierungs-Endpoint – erstellen Sie einen Auftrag, prüfen Sie den Status und rufen Sie den HS-Code, Vertrauensscore und GRI-Begründung ab.
Der Klassifizierungs-Endpoint liefert den HS-Code (Harmonisiertes System) für ein Produkt basierend auf dessen Textbeschreibung und/oder Bildern. Die Verarbeitung erfolgt asynchron: Sie erstellen einen Auftrag, prüfen dann dessen Status, bis Ergebnisse verfügbar sind.
Einen Klassifizierungsauftrag erstellen
POST
/v1/classify/jobsBody-Parameter (JSON)
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
content | string | Ja | Produktbeschreibung zur Klassifizierung |
image_urls | string[] | Nein | Produktbild-URLs (max. 5) |
locale | "fr" | "en" | "es" | Nein | Antwortsprache (Standard: "fr") |
Beispielanfrage
curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
-H "X-API-Key: th_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"content": "Wireless Bluetooth headphones with active noise cancellation, leather headband, USB-C charging",
"image_urls": ["https://example.com/product/headphones.jpg"],
"locale": "en"
}'import httpx
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_your_api_key"},
)
response = client.post("/v1/classify/jobs", json={
"content": "Wireless Bluetooth headphones with active noise cancellation, leather headband, USB-C charging",
"image_urls": ["https://example.com/product/headphones.jpg"],
"locale": "en",
})
job = response.json()
print(f"Auftrag erstellt: {job['id']} - Status: {job['status']}")const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
method: "POST",
headers: {
"X-API-Key": "th_live_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
content: "Wireless Bluetooth headphones with active noise cancellation, leather headband, USB-C charging",
image_urls: ["https://example.com/product/headphones.jpg"],
locale: "en",
}),
});
const job = await response.json();
console.log(`Auftrag erstellt: ${job.id} - Status: ${job.status}`);Antwort (202 Accepted)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:00Z"
}Auftragsstatus und Ergebnisse abrufen
GET
/v1/classify/jobs/{job_id}Pfadparameter
| Parameter | Typ | Beschreibung |
|---|---|---|
job_id | string (UUID) | Auftragskennung, die bei der Erstellung zurückgegeben wurde |
Mögliche Status
| Status | Beschreibung |
|---|---|
pending | Der Auftrag ist in der Warteschlange |
processing | Die Verarbeitung läuft |
completed | Die Klassifizierung ist abgeschlossen, Ergebnisse sind verfügbar |
failed | Während der Verarbeitung ist ein Fehler aufgetreten |
Beispielanfrage
curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "X-API-Key: th_live_your_api_key"import httpx
import time
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_your_api_key"},
)
job_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
delay = 1
while True:
response = client.get(f"/v1/classify/jobs/{job_id}")
job = response.json()
if job["status"] == "completed":
print("Klassifizierung abgeschlossen!")
print(job["result"])
break
elif job["status"] == "failed":
print(f"Fehler: {job.get('error')}")
break
time.sleep(delay)
delay = min(delay * 2, 5) # Progressives Backoff, max. 5sconst API_KEY = "th_live_your_api_key";
const jobId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
async function pollJob(jobId) {
let delay = 1000;
while (true) {
const response = await fetch(
`https://api.thetradehub.eu/v1/classify/jobs/${jobId}`,
{ headers: { "X-API-Key": API_KEY } }
);
const job = await response.json();
if (job.status === "completed") {
console.log("Klassifizierung abgeschlossen!", job.result);
return job;
}
if (job.status === "failed") {
throw new Error(job.error);
}
await new Promise((r) => setTimeout(r, delay));
delay = Math.min(delay * 2, 5000); // Progressives Backoff, max. 5s
}
}
const result = await pollJob(jobId);Vollständige Antwort (Status: completed)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"result": {
"classification": {
"rankings": [
{
"rank": 1,
"hs_code": "8518.30.00",
"description": "Kopfhörer und Ohrhörer",
"confidence": 0.94,
"gri_justification": "GIR 1 - Das Produkt ist speziell durch die Position 8518 abgedeckt...",
"validated": true
},
{
"rank": 2,
"hs_code": "8517.62.00",
"description": "Geräte zum Empfang, zur Umwandlung und Übertragung von Daten",
"confidence": 0.15,
"gri_justification": "GIR 1 - Position 8517 umfasst Telekommunikationsgeräte. Die Kopfhörer sind jedoch spezifischer durch 8518 abgedeckt. Abgelehnt.",
"validated": true
}
]
},
"text": "Basierend auf EU-vZTA-Entscheidungen und TARIC-Nomenklatur...",
"session_id": "sess_abc123"
},
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:05Z"
}Ergebnisstruktur
result.classification.rankings[]
Bis zu 3 Klassifizierungsvorschläge, sortiert nach absteigendem Vertrauensscore.
| Feld | Typ | Beschreibung |
|---|---|---|
rank | number | Rangfolge (1 = beste Übereinstimmung) |
hs_code | string | HS-Code mit 6, 8 oder 10 Stellen |
description | string | Beschreibung des Tarifpostens |
confidence | number | Vertrauensscore zwischen 0 und 1 |
gri_justification | string | Begründung basierend auf den Allgemeinen Auslegungsregeln (GIR) |
validated | boolean | true, wenn der Code gegen die TARIC-Nomenklatur geprüft wurde |
result.text
Freitext-Erklärung mit Details zur Klassifizierungsbegründung.
result.session_id
Sitzungskennung zur Auffindung dieser Klassifizierung in der Weboberfläche von The Trade Hub.
Best Practices für das Polling
| Empfehlung | Details |
|---|---|
| Anfangsintervall | 1 Sekunde |
| Backoff | Progressiv erhöhen (1s, 2s, 4s, max. 5s) |
| Maximale Wartezeit | 30 Sekunden – danach gilt der Auftrag als fehlgeschlagen |
| Statusprüfung | Prüfen Sie immer status, bevor Sie auf result zugreifen |
Last updated on