Clasificación por lotes
Envíe hasta 1.000 productos, siga un lote padre y recupere cada clasificación UE o China.
Una solicitud crea un lote padre duradero de 1 a 1.000 filas. El servicio organiza sublotes duraderos de 100 y ejecuta como máximo 32 clasificaciones simultáneamente.
| Filas enviadas | Sublotes internos | Identificador seguido por el cliente |
|---|---|---|
| 500 | 5 | 1 batch_id |
| 1.000 | 10 | 1 batch_id |
El cliente no divide el archivo. Conserva el batch_id y un id estable para cada fila.
El esquema completo está disponible en el contrato OpenAPI.
Rutas
| Jurisdicción | Crear | Seguir | Ámbito de la clave |
|---|---|---|---|
| Unión Europea | POST /v1/classify/batch | GET /v1/classify/batch/{batch_id} | classify |
| China | POST /v1/classify-china/batch | GET /v1/classify-china/batch/{batch_id} | classify_china |
Crear un lote
Cada fila debe contener una descripción, imágenes o ambos.
| Campo | Obligatorio | Descripción |
|---|---|---|
items | Sí | De 1 a 1.000 filas |
items[].id | Recomendado | Referencia ERP estable. Se genera si falta |
items[].content | Condicional | Descripción y características objetivas |
items[].image_urls | Condicional | Hasta 5 imágenes HTTPS |
items[].taric_code | Solo China | Referencia comparativa opcional, nunca una conversión automática |
analysis_mode | No | operational por defecto o legal_deep |
locale | No | fr, en, es o de |
curl -sS -X POST "https://api.thetradehub.eu/v1/classify/batch" \
-H "X-API-Key: $TTH_API_KEY" \
-H "Idempotency-Key: importacion-erp-2026-09" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"id": "SKU-001", "content": "Auriculares Bluetooth con cancelación activa de ruido"},
{"id": "SKU-002", "content": "Bomba centrífuga de acero inoxidable para líquidos alimentarios"}
],
"analysis_mode": "operational",
"locale": "es"
}'La creación devuelve 202 Accepted. Repetir el mismo cuerpo con el mismo Idempotency-Key devuelve el lote existente con 200 OK, sin duplicar el procesamiento ni la facturación.
Seguir y recuperar los resultados
Consulte el lote cada 10 segundos. No imponga un plazo global de 600 segundos a un lote de 1.000 filas.
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":
print(item["id"], item["result"]["classification"]["recommended_code"])
else:
print(item["id"], item["status"], item.get("error"))| Nivel | Estados |
|---|---|
| Lote padre | pending, processing, completed, failed |
| Fila | completed, failed, timeout |
Un lote completed puede contener filas fallidas. Revise siempre los contadores completed y failed y después items.
Reintentar solo los fallos
Cree un lote nuevo que contenga únicamente las filas con estado failed o timeout. Conserve su id y contenido originales y use un nuevo Idempotency-Key de lote. Los resultados válidos del primer lote permanecen disponibles y no se facturan de nuevo.
Para un 429, respete Retry-After. Para 502, 503 o 504, use una espera progresiva. En ambos casos, reutilice el Idempotency-Key original mientras repita la misma solicitud de creación.
Last updated on