Classement par lot

Envoyez jusqu’à 1 000 produits, suivez un lot parent et récupérez chaque classement UE ou Chine.

Un appel crée un lot parent durable de 1 à 1 000 lignes. Le service organise le travail en sous-lots de 100 et exécute au maximum 32 classements simultanément.

Taille envoyée	Sous-lots internes	Identifiant suivi par le client
500 lignes	5	1 `batch_id`
1 000 lignes	10	1 `batch_id`

Le client ne découpe pas le fichier. Il conserve le batch_id et un id stable pour chaque ligne.

Le schéma complet est disponible dans le contrat OpenAPI.

Routes

Juridiction	Créer	Suivre	Périmètre de la clé
Union européenne	`POST /v1/classify/batch`	`GET /v1/classify/batch/{batch_id}`	`classify`
Chine	`POST /v1/classify-china/batch`	`GET /v1/classify-china/batch/{batch_id}`	`classify_china`

Créer un lot

Chaque ligne doit contenir une description, des images, ou les deux.

Champ	Requis	Description
`items`	Oui	De 1 à 1 000 lignes
`items[].id`	Recommandé	Référence ERP stable. Générée si elle manque
`items[].content`	Conditionnel	Description et caractéristiques objectives
`items[].image_urls`	Conditionnel	Jusqu’à 5 images HTTPS
`items[].taric_code`	Chine seulement	Référence comparative facultative, jamais une conversion automatique
`analysis_mode`	Non	`operational` par défaut ou `legal_deep`
`locale`	Non	`fr`, `en`, `es` ou `de`

curl -sS -X POST "https://api.thetradehub.eu/v1/classify/batch" \
  -H "X-API-Key: $TTH_API_KEY" \
  -H "Idempotency-Key: import-erp-2026-09" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "SKU-001",
        "content": "Casque Bluetooth avec réduction de bruit et recharge USB-C"
      },
      {
        "id": "SKU-002",
        "content": "Pompe centrifuge en acier inoxydable pour liquides alimentaires"
      }
    ],
    "analysis_mode": "operational",
    "locale": "fr"
  }'

Une création retourne 202 Accepted. Le rejeu du même corps avec le même Idempotency-Key retourne le lot existant avec 200 OK, sans double traitement ni double facturation.

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "status": "processing",
  "total": 2,
  "completed": 0,
  "failed": 0,
  "progress": 0,
  "created_at": "2026-09-10T10:30:00Z",
  "updated_at": "2026-09-10T10:30:00Z"
}

Suivre et récupérer les résultats

Interrogez le lot toutes les 10 secondes. Ne fixez pas un délai global de 600 secondes à un lot de 1 000 lignes.

import os
import time

import httpx

batch_id = "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
headers = {"X-API-Key": os.environ["TTH_API_KEY"]}

with httpx.Client(base_url="https://api.thetradehub.eu", headers=headers, timeout=30) as client:
    while True:
        response = client.get(f"/v1/classify/batch/{batch_id}")
        response.raise_for_status()
        batch = response.json()
        print(batch["status"], batch["completed"], batch["failed"], batch["total"])

        if batch["status"] in ("completed", "failed"):
            break
        time.sleep(10)

for item in batch.get("items", []):
    if item["status"] == "completed":
        decision = item["result"]["classification"]
        print(item["id"], decision["recommended_code"])
    else:
        print(item["id"], item["status"], item.get("error"))

Niveau	Statuts
Lot parent	`pending`, `processing`, `completed`, `failed`
Ligne	`completed`, `failed`, `timeout`

Un lot completed peut contenir des lignes en échec. Utilisez toujours les compteurs completed et failed, puis examinez items.

Reprendre uniquement les échecs

Filtrez les lignes dont status vaut failed ou timeout.
Conservez leur id et leur contenu d’origine.
Créez un nouveau lot limité à ces lignes.
Utilisez un nouvel Idempotency-Key pour cette reprise.

Les résultats valides du premier lot restent disponibles et ne sont pas refacturés.

Erreurs à traiter

HTTP	Action
`400`	Corrigez le corps ou réduisez le lot à 1 000 lignes
`401`	Vérifiez `X-API-Key`
`403`	Vérifiez le périmètre `classify` ou `classify_china`
`429`	Respectez `Retry-After`, puis rejouez avec le même `Idempotency-Key`
`502`, `503`, `504`	Réessayez avec une temporisation progressive et le même `Idempotency-Key`

Ne journalisez jamais la clé API, les images en base64 ni les données commerciales sensibles.

Un appel crée un lot parent durable de 1 à 1 000 lignes. Le service organise le travail en sous-lots de 100 et exécute au maximum 32 classements simultanément.

Taille envoyée	Sous-lots internes	Identifiant suivi par le client
500 lignes	5	1 `batch_id`
1 000 lignes	10	1 `batch_id`

Le client ne découpe pas le fichier. Il conserve le batch_id et un id stable pour chaque ligne.

Le schéma complet est disponible dans le contrat OpenAPI.

Routes

Juridiction	Créer	Suivre	Périmètre de la clé
Union européenne	`POST /v1/classify/batch`	`GET /v1/classify/batch/{batch_id}`	`classify`
Chine	`POST /v1/classify-china/batch`	`GET /v1/classify-china/batch/{batch_id}`	`classify_china`

Créer un lot

Chaque ligne doit contenir une description, des images, ou les deux.

Champ	Requis	Description
`items`	Oui	De 1 à 1 000 lignes
`items[].id`	Recommandé	Référence ERP stable. Générée si elle manque
`items[].content`	Conditionnel	Description et caractéristiques objectives
`items[].image_urls`	Conditionnel	Jusqu’à 5 images HTTPS
`items[].taric_code`	Chine seulement	Référence comparative facultative, jamais une conversion automatique
`analysis_mode`	Non	`operational` par défaut ou `legal_deep`
`locale`	Non	`fr`, `en`, `es` ou `de`

curl -sS -X POST "https://api.thetradehub.eu/v1/classify/batch" \
  -H "X-API-Key: $TTH_API_KEY" \
  -H "Idempotency-Key: import-erp-2026-09" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "SKU-001",
        "content": "Casque Bluetooth avec réduction de bruit et recharge USB-C"
      },
      {
        "id": "SKU-002",
        "content": "Pompe centrifuge en acier inoxydable pour liquides alimentaires"
      }
    ],
    "analysis_mode": "operational",
    "locale": "fr"
  }'

Une création retourne 202 Accepted. Le rejeu du même corps avec le même Idempotency-Key retourne le lot existant avec 200 OK, sans double traitement ni double facturation.

{
  "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "status": "processing",
  "total": 2,
  "completed": 0,
  "failed": 0,
  "progress": 0,
  "created_at": "2026-09-10T10:30:00Z",
  "updated_at": "2026-09-10T10:30:00Z"
}

Suivre et récupérer les résultats

Interrogez le lot toutes les 10 secondes. Ne fixez pas un délai global de 600 secondes à un lot de 1 000 lignes.

import os
import time

import httpx

batch_id = "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
headers = {"X-API-Key": os.environ["TTH_API_KEY"]}

with httpx.Client(base_url="https://api.thetradehub.eu", headers=headers, timeout=30) as client:
    while True:
        response = client.get(f"/v1/classify/batch/{batch_id}")
        response.raise_for_status()
        batch = response.json()
        print(batch["status"], batch["completed"], batch["failed"], batch["total"])

        if batch["status"] in ("completed", "failed"):
            break
        time.sleep(10)

for item in batch.get("items", []):
    if item["status"] == "completed":
        decision = item["result"]["classification"]
        print(item["id"], decision["recommended_code"])
    else:
        print(item["id"], item["status"], item.get("error"))

Niveau	Statuts
Lot parent	`pending`, `processing`, `completed`, `failed`
Ligne	`completed`, `failed`, `timeout`

Un lot completed peut contenir des lignes en échec. Utilisez toujours les compteurs completed et failed, puis examinez items.

Reprendre uniquement les échecs

Filtrez les lignes dont status vaut failed ou timeout.
Conservez leur id et leur contenu d’origine.
Créez un nouveau lot limité à ces lignes.
Utilisez un nouvel Idempotency-Key pour cette reprise.

Les résultats valides du premier lot restent disponibles et ne sont pas refacturés.

Erreurs à traiter

HTTP	Action
`400`	Corrigez le corps ou réduisez le lot à 1 000 lignes
`401`	Vérifiez `X-API-Key`
`403`	Vérifiez le périmètre `classify` ou `classify_china`
`429`	Respectez `Retry-After`, puis rejouez avec le même `Idempotency-Key`
`502`, `503`, `504`	Réessayez avec une temporisation progressive et le même `Idempotency-Key`

Ne journalisez jamais la clé API, les images en base64 ni les données commerciales sensibles.

Routes

Créer un lot

Suivre et récupérer les résultats

Reprendre uniquement les échecs

Erreurs à traiter

On this page

Classement par lot

Routes

Créer un lot

Suivre et récupérer les résultats

Reprendre uniquement les échecs

Erreurs à traiter

On this page