Classement
Endpoint de classement douanier - créez un job, interrogez le statut et récupérez le code HS, le taux de confiance et la justification GRI.
L'endpoint de classement permet d'obtenir le code HS (Système Harmonisé) d'un produit à partir de sa description textuelle et/ou d'images. Le traitement est asynchrone : vous créez un job, puis vous interrogez son statut jusqu'à obtention des résultats.
Créer un job de classement
/v1/classify/jobsParamètres du corps (JSON)
| Paramètre | Type | Requis | Description |
|---|---|---|---|
content | string | Oui | Description du produit à classer |
image_urls | string[] | Non | URLs d'images du produit (max 5) |
locale | "fr" | "en" | "es" | Non | Langue de la réponse (défaut : "fr") |
Exemple de requête
curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
-H "X-API-Key: th_live_votre_cle_api" \
-H "Content-Type: application/json" \
-d '{
"content": "Casque audio Bluetooth sans fil avec réduction de bruit active, bandeau en cuir, charge USB-C",
"image_urls": ["https://example.com/product/headphones.jpg"],
"locale": "fr"
}'import httpx
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_votre_cle_api"},
)
response = client.post("/v1/classify/jobs", json={
"content": "Casque audio Bluetooth sans fil avec réduction de bruit active, bandeau en cuir, charge USB-C",
"image_urls": ["https://example.com/product/headphones.jpg"],
"locale": "fr",
})
job = response.json()
print(f"Job créé : {job['id']} - Statut : {job['status']}")const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
method: "POST",
headers: {
"X-API-Key": "th_live_votre_cle_api",
"Content-Type": "application/json",
},
body: JSON.stringify({
content: "Casque audio Bluetooth sans fil avec réduction de bruit active, bandeau en cuir, charge USB-C",
image_urls: ["https://example.com/product/headphones.jpg"],
locale: "fr",
}),
});
const job = await response.json();
console.log(`Job créé : ${job.id} - Statut : ${job.status}`);Réponse (202 Accepted)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "pending",
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:00Z"
}Obtenir le statut et les résultats
/v1/classify/jobs/{job_id}Paramètres de chemin
| Paramètre | Type | Description |
|---|---|---|
job_id | string (UUID) | Identifiant du job retourné à la création |
Statuts possibles
| Statut | Description |
|---|---|
pending | Le job est en file d'attente |
processing | Le traitement est en cours |
completed | Le classement est terminé, les résultats sont disponibles |
failed | Une erreur s'est produite pendant le traitement |
Exemple de requête
curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "X-API-Key: th_live_votre_cle_api"import httpx
import time
client = httpx.Client(
base_url="https://api.thetradehub.eu",
headers={"X-API-Key": "th_live_votre_cle_api"},
)
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("Classement terminé !")
print(job["result"])
break
elif job["status"] == "failed":
print(f"Erreur : {job.get('error')}")
break
time.sleep(delay)
delay = min(delay * 2, 5) # Backoff progressif, max 5sconst API_KEY = "th_live_votre_cle_api";
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("Classement terminé !", 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); // Backoff progressif, max 5s
}
}
const result = await pollJob(jobId);Réponse complète (status: completed)
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "completed",
"result": {
"classification": {
"rankings": [
{
"rank": 1,
"hs_code": "8518.30.00",
"description": "Ecouteurs et casques",
"confidence": 0.94,
"gri_justification": "GRI 1 - Le produit est nommément couvert par la position 8518...",
"validated": true
},
{
"rank": 2,
"hs_code": "8517.62.00",
"description": "Appareils de reception, conversion et transmission de données",
"confidence": 0.15,
"gri_justification": "GRI 1 - Position 8517 couvre les appareils de télécommunication. Cependant, le casque est plus spécifiquement couvert par 8518. Rejeté.",
"validated": true
}
]
},
"text": "D'apres les décisions BTI de l'UE et la nomenclature TARIC...",
"session_id": "sess_abc123"
},
"created_at": "2026-02-24T10:30:00Z",
"updated_at": "2026-02-24T10:30:05Z"
}Structure des résultats
result.classification.rankings[]
Jusqu'à 3 propositions de classement par ordre de confiance décroissante.
| Champ | Type | Description |
|---|---|---|
rank | number | Position dans le classement (1 = meilleur) |
hs_code | string | Code HS à 6, 8 ou 10 chiffres |
description | string | Description de la position tarifaire |
confidence | number | Score de confiance entre 0 et 1 |
gri_justification | string | Justification basée sur les Règles Générales Interprétatives |
validated | boolean | true si le code a été vérifié dans la nomenclature TARIC |
result.text
Texte explicatif détaillant le raisonnement de classement.
result.session_id
Identifiant de session permettant de retrouver ce classement dans l'interface web The Trade Hub.
Historique et export
Lister les classements passes
/v1/classify/history| Paramètre | Type | Description |
|---|---|---|
from | date | Date de début (défaut : 30 jours) |
to | date | Date de fin (défaut : aujourd'hui) |
hs | string | Filtre par préfixe de code HS |
status | string | "completed" ou "failed" |
page | number | Page (défaut : 1) |
per_page | number | Résultats par page (défaut : 20, max : 50) |
all_keys | "true" | Voir les classements de toutes les clés API de l'organisation |
Exporter en CSV
/v1/classify/history/exportRetourne un fichier CSV avec tous les classements correspondant aux filtres. Mêmes paramètres que l'endpoint de liste (sauf pagination). Maximum 100 000 lignes.
curl "https://api.thetradehub.eu/v1/classify/history/export?from=2026-01-01&to=2026-03-11" \
-H "X-API-Key: th_live_votre_cle_api" \
-o classifications.csvBonnes pratiques de polling
| Recommandation | Détail |
|---|---|
| Intervalle initial | 1 seconde |
| Backoff | Augmentez progressivement (1s, 2s, 4s, 5s max) |
| Timeout maximum | 30 secondes - au-delà, considérez le job comme échoué |
| Vérification du statut | Toujours vérifier status avant d'accéder à result |
Dernière mise à jour