Clasificacion

Endpoint de clasificacion aduanera - cree un job, consulte el estado y obtenga el codigo HS, la confianza y la justificacion GRI.

El endpoint de clasificacion permite obtener el codigo HS (Sistema Armonizado) de un producto a partir de su descripcion textual y/o imagenes. El procesamiento es asincrono: usted crea un job, luego consulta su estado hasta obtener los resultados.

Crear un job de clasificacion

POST/v1/classify/jobs

Parametros del cuerpo (JSON)

Parametro	Tipo	Requerido	Descripcion
`content`	`string`	Si	Descripcion del producto a clasificar
`image_urls`	`string[]`	No	URLs de imagenes del producto (max 5)
`locale`	`"fr"` \| `"en"` \| `"es"`	No	Idioma de la respuesta (por defecto: `"fr"`)

Ejemplo de solicitud

curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
  -H "X-API-Key: th_live_su_clave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    "image_urls": ["https://example.com/product/headphones.jpg"],
    "locale": "es"
  }'

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_su_clave_api"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    "image_urls": ["https://example.com/product/headphones.jpg"],
    "locale": "es",
})

job = response.json()
print(f"Job creado: {job['id']} - Estado: {job['status']}")

const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "th_live_su_clave_api",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    image_urls: ["https://example.com/product/headphones.jpg"],
    locale: "es",
  }),
});

const job = await response.json();
console.log(`Job creado: ${job.id} - Estado: ${job.status}`);

Respuesta (202 Accepted)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-02-24T10:30:00Z",
  "updated_at": "2026-02-24T10:30:00Z"
}

Obtener el estado y los resultados

GET/v1/classify/jobs/{job_id}

Parametros de ruta

Parametro	Tipo	Descripcion
`job_id`	`string` (UUID)	Identificador del job devuelto en la creacion

Estados posibles

Estado	Descripcion
`pending`	El job esta en cola
`processing`	El procesamiento esta en curso
`completed`	La clasificacion esta completa, los resultados estan disponibles
`failed`	Ocurrio un error durante el procesamiento

Ejemplo de solicitud

curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: th_live_su_clave_api"

import httpx
import time

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_su_clave_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("Clasificacion completada!")
        print(job["result"])
        break
    elif job["status"] == "failed":
        print(f"Error: {job.get('error')}")
        break

    time.sleep(delay)
    delay = min(delay * 2, 5)  # Backoff progresivo, max 5s

const API_KEY = "th_live_su_clave_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("Clasificacion completada!", 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 progresivo, max 5s
  }
}

const result = await pollJob(jobId);

Respuesta completa (status: completed)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "result": {
    "classification": {
      "rankings": [
        {
          "rank": 1,
          "hs_code": "8518.30.00",
          "description": "Auriculares y cascos",
          "confidence": 0.94,
          "gri_justification": "RGI 1 - El producto esta expresamente cubierto por la posicion 8518...",
          "validated": true
        },
        {
          "rank": 2,
          "hs_code": "8517.62.00",
          "description": "Aparatos de recepcion, conversion y transmision de datos",
          "confidence": 0.15,
          "gri_justification": "RGI 1 - La posicion 8517 cubre los aparatos de telecomunicacion. Sin embargo, los auriculares estan mas especificamente cubiertos por 8518. Rechazado.",
          "validated": true
        }
      ]
    },
    "text": "Segun las decisiones IVO de la UE y la nomenclatura TARIC...",
    "session_id": "sess_abc123"
  },
  "created_at": "2026-02-24T10:30:00Z",
  "updated_at": "2026-02-24T10:30:05Z"
}

Estructura de los resultados

`result.classification.rankings[]`

Hasta 3 propuestas de clasificacion ordenadas por confianza descendente.

Campo	Tipo	Descripcion
`rank`	`number`	Posicion en la clasificacion (1 = mejor coincidencia)
`hs_code`	`string`	Codigo HS a 6, 8 o 10 digitos
`description`	`string`	Descripcion de la partida arancelaria
`confidence`	`number`	Puntuacion de confianza entre 0 y 1
`gri_justification`	`string`	Justificacion basada en las Reglas Generales de Interpretacion
`validated`	`boolean`	`true` si el codigo ha sido verificado en la nomenclatura TARIC

`result.text`

Texto explicativo que detalla el razonamiento de clasificacion.

`result.session_id`

Identificador de sesion para encontrar esta clasificacion en la interfaz web de The Trade Hub.

Buenas practicas de polling

Recomendacion	Detalle
Intervalo inicial	1 segundo
Backoff	Aumente progresivamente (1s, 2s, 4s, 5s max)
Timeout maximo	30 segundos - mas alla, considere el job como fallido
Verificacion del estado	Siempre verifique `status` antes de acceder a `result`

Crear un job de clasificacion

POST/v1/classify/jobs

Parametros del cuerpo (JSON)

Parametro	Tipo	Requerido	Descripcion
`content`	`string`	Si	Descripcion del producto a clasificar
`image_urls`	`string[]`	No	URLs de imagenes del producto (max 5)
`locale`	`"fr"` \| `"en"` \| `"es"`	No	Idioma de la respuesta (por defecto: `"fr"`)

Ejemplo de solicitud

curl -X POST https://api.thetradehub.eu/v1/classify/jobs \
  -H "X-API-Key: th_live_su_clave_api" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    "image_urls": ["https://example.com/product/headphones.jpg"],
    "locale": "es"
  }'

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_su_clave_api"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    "image_urls": ["https://example.com/product/headphones.jpg"],
    "locale": "es",
})

job = response.json()
print(f"Job creado: {job['id']} - Estado: {job['status']}")

const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "th_live_su_clave_api",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    content: "Auriculares Bluetooth inalambricos con cancelacion activa de ruido, diadema de cuero, carga USB-C",
    image_urls: ["https://example.com/product/headphones.jpg"],
    locale: "es",
  }),
});

const job = await response.json();
console.log(`Job creado: ${job.id} - Estado: ${job.status}`);

Respuesta (202 Accepted)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "created_at": "2026-02-24T10:30:00Z",
  "updated_at": "2026-02-24T10:30:00Z"
}

Obtener el estado y los resultados

GET/v1/classify/jobs/{job_id}

Parametros de ruta

Parametro	Tipo	Descripcion
`job_id`	`string` (UUID)	Identificador del job devuelto en la creacion

Estados posibles

Estado	Descripcion
`pending`	El job esta en cola
`processing`	El procesamiento esta en curso
`completed`	La clasificacion esta completa, los resultados estan disponibles
`failed`	Ocurrio un error durante el procesamiento

Ejemplo de solicitud

curl https://api.thetradehub.eu/v1/classify/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: th_live_su_clave_api"

import httpx
import time

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_su_clave_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("Clasificacion completada!")
        print(job["result"])
        break
    elif job["status"] == "failed":
        print(f"Error: {job.get('error')}")
        break

    time.sleep(delay)
    delay = min(delay * 2, 5)  # Backoff progresivo, max 5s

const API_KEY = "th_live_su_clave_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("Clasificacion completada!", 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 progresivo, max 5s
  }
}

const result = await pollJob(jobId);

Respuesta completa (status: completed)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "completed",
  "result": {
    "classification": {
      "rankings": [
        {
          "rank": 1,
          "hs_code": "8518.30.00",
          "description": "Auriculares y cascos",
          "confidence": 0.94,
          "gri_justification": "RGI 1 - El producto esta expresamente cubierto por la posicion 8518...",
          "validated": true
        },
        {
          "rank": 2,
          "hs_code": "8517.62.00",
          "description": "Aparatos de recepcion, conversion y transmision de datos",
          "confidence": 0.15,
          "gri_justification": "RGI 1 - La posicion 8517 cubre los aparatos de telecomunicacion. Sin embargo, los auriculares estan mas especificamente cubiertos por 8518. Rechazado.",
          "validated": true
        }
      ]
    },
    "text": "Segun las decisiones IVO de la UE y la nomenclatura TARIC...",
    "session_id": "sess_abc123"
  },
  "created_at": "2026-02-24T10:30:00Z",
  "updated_at": "2026-02-24T10:30:05Z"
}

Estructura de los resultados

`result.classification.rankings[]`

Hasta 3 propuestas de clasificacion ordenadas por confianza descendente.

Campo	Tipo	Descripcion
`rank`	`number`	Posicion en la clasificacion (1 = mejor coincidencia)
`hs_code`	`string`	Codigo HS a 6, 8 o 10 digitos
`description`	`string`	Descripcion de la partida arancelaria
`confidence`	`number`	Puntuacion de confianza entre 0 y 1
`gri_justification`	`string`	Justificacion basada en las Reglas Generales de Interpretacion
`validated`	`boolean`	`true` si el codigo ha sido verificado en la nomenclatura TARIC

`result.text`

Texto explicativo que detalla el razonamiento de clasificacion.

`result.session_id`

Identificador de sesion para encontrar esta clasificacion en la interfaz web de The Trade Hub.

Buenas practicas de polling

Recomendacion	Detalle
Intervalo inicial	1 segundo
Backoff	Aumente progresivamente (1s, 2s, 4s, 5s max)
Timeout maximo	30 segundos - mas alla, considere el job como fallido
Verificacion del estado	Siempre verifique `status` antes de acceder a `result`

Crear un job de clasificacion

Parametros del cuerpo (JSON)

Ejemplo de solicitud

Respuesta (202 Accepted)

Obtener el estado y los resultados

Parametros de ruta

Estados posibles

Ejemplo de solicitud

Respuesta completa (status: completed)

Estructura de los resultados

`result.classification.rankings[]`

`result.text`

`result.session_id`

Buenas practicas de polling

En esta página

Clasificacion

Crear un job de clasificacion

Parametros del cuerpo (JSON)

Ejemplo de solicitud

Respuesta (202 Accepted)

Obtener el estado y los resultados

Parametros de ruta

Estados posibles

Ejemplo de solicitud

Respuesta completa (status: completed)

Estructura de los resultados

`result.classification.rankings[]`

`result.text`

`result.session_id`

Buenas practicas de polling

En esta página