> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camtomx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API clasificacion arancelaria automatica

> Endpoint REST para clasificar mercancias con IA. Envia descripcion o imagen y recibe fraccion arancelaria con confianza y justificacion.

Clasificacion arancelaria interactiva. Envia una descripcion de producto, imagenes de soporte o documentos y recibe codigos HS sugeridos con nivel de confianza y razonamiento. Soporta respuestas en streaming (NDJSON).

```
POST https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini
```

**Costo:** 1 credito por clasificacion.

## Request

### Headers

| Header          | Tipo   | Requerido | Descripcion        |
| --------------- | ------ | --------- | ------------------ |
| `Authorization` | string | Si        | `Bearer <api_key>` |

<Warning>
  Este endpoint usa `multipart/form-data`, NO `application/json`. No establezcas `Content-Type` manualmente -- la mayoria de los clientes HTTP lo configuran automaticamente con el boundary correcto al enviar formularios.
</Warning>

### Query parameters

<ParamField query="country_code" type="string" required>
  Codigo de pais para la clasificacion. Determina la nomenclatura arancelaria a utilizar.

  Valores permitidos:

  * `MEX` -- Mexico (TIGIE)
  * `COL` -- Colombia
  * `USA` -- Estados Unidos
  * `ARG` -- Argentina
  * `WORLD` -- Sistema Armonizado internacional (6 digitos)
</ParamField>

<ParamField query="model" type="string" default="pro">
  Tier del modelo de clasificacion.

  Valores permitidos:

  * `fast` -- Mas rapido, menor precision
  * `pro` -- Mayor precision (default)
</ParamField>

<ParamField query="tariff_info" type="boolean" default="true">
  Si se debe incluir informacion arancelaria (impuestos, regulaciones) en la respuesta.
</ParamField>

<ParamField query="user_identifier" type="string">
  Identificador opcional del usuario que realiza la peticion. Se utiliza para tracking interno.
</ParamField>

### Body parameters (multipart/form-data)

<ParamField body="product_description" type="string">
  Descripcion del producto a clasificar. Mientras mas detallada sea la descripcion (material, uso, composicion, presentacion), mas preciso sera el resultado.
</ParamField>

<ParamField body="image_files" type="file[]">
  Imagenes de soporte del producto. Maximo 10 archivos. Formatos de imagen comunes soportados.
</ParamField>

<ParamField body="document_files" type="file[]">
  Documentos de soporte (fichas tecnicas, especificaciones PDF, etc.). Maximo 10 archivos.
</ParamField>

<ParamField body="streaming" type="boolean" default="false">
  Si se activa, la respuesta se envia como NDJSON streaming (`application/x-ndjson`) con actualizaciones de progreso en tiempo real.
</ParamField>

<ParamField body="classification_record_id" type="string">
  ID de un registro de clasificacion previo. Se usa para refinar una clasificacion existente proporcionando informacion adicional.
</ParamField>

<Note>
  Se debe proporcionar al menos uno de: `product_description`, `image_files` o `document_files`. Si no se envia ninguno, la peticion sera rechazada.
</Note>

### Ejemplo de request

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini",
      headers={"Authorization": "Bearer sk_tu_api_key"},
      params={
          "country_code": "MEX",
          "model": "pro",
          "tariff_info": "true"
      },
      data={
          "product_description": "Monitor LED de 27 pulgadas, resolucion 4K UHD, panel IPS, para computadora de escritorio"
      }
  )

  data = response.json()
  for hs in data["hscodes_array"]:
      print(f"Codigo HS: {hs['hscode_8digits']['code']}")
      print(f"Confianza: {hs['overall_confidence']}")
      print(f"Justificacion: {hs['justification']}")
  ```

  ```javascript JavaScript theme={null}
  const formData = new FormData();
  formData.append(
    "product_description",
    "Monitor LED de 27 pulgadas, resolucion 4K UHD, panel IPS, para computadora de escritorio"
  );

  const response = await fetch(
    "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini?country_code=MEX&model=pro&tariff_info=true",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_tu_api_key"
      },
      body: formData
    }
  );

  const data = await response.json();
  data.hscodes_array.forEach(hs => {
    console.log(`Codigo HS: ${hs.hscode_8digits.code}`);
    console.log(`Confianza: ${hs.overall_confidence}`);
    console.log(`Justificacion: ${hs.justification}`);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini?country_code=MEX&model=pro&tariff_info=true" \
    -H "Authorization: Bearer sk_tu_api_key" \
    -F "product_description=Monitor LED de 27 pulgadas, resolucion 4K UHD, panel IPS, para computadora de escritorio"
  ```
</CodeGroup>

### Ejemplo con archivos

<CodeGroup>
  ```python Python (con imagenes) theme={null}
  import requests

  response = requests.post(
      "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini",
      headers={"Authorization": "Bearer sk_tu_api_key"},
      params={"country_code": "MEX", "model": "pro"},
      data={"product_description": "Monitor LED 4K para computadora"},
      files=[
          ("image_files", ("foto_producto.jpg", open("foto_producto.jpg", "rb"), "image/jpeg")),
          ("document_files", ("ficha_tecnica.pdf", open("ficha_tecnica.pdf", "rb"), "application/pdf"))
      ]
  )
  ```

  ```bash cURL (con imagenes) theme={null}
  curl -X POST "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini?country_code=MEX&model=pro" \
    -H "Authorization: Bearer sk_tu_api_key" \
    -F "product_description=Monitor LED 4K para computadora" \
    -F "image_files=@foto_producto.jpg" \
    -F "document_files=@ficha_tecnica.pdf"
  ```
</CodeGroup>

## Response

### Respuesta estandar (sin streaming)

<ResponseField name="hscodes_array" type="array">
  Lista de codigos HS sugeridos, ordenados por relevancia. Cada elemento contiene:

  <Expandable title="Propiedades de cada codigo HS">
    <ResponseField name="hscode_2digits" type="object">
      Capitulo del Sistema Armonizado. Contiene `name` (nombre) y `code` (codigo).
    </ResponseField>

    <ResponseField name="hscode_4digits" type="object">
      Partida arancelaria. Contiene `name` y `code`.
    </ResponseField>

    <ResponseField name="hscode_6digits" type="object">
      Subpartida arancelaria. Contiene `name` y `code`.
    </ResponseField>

    <ResponseField name="hscode_8digits" type="object">
      Fraccion arancelaria (nivel nacional). Contiene `name` y `code`.
    </ResponseField>

    <ResponseField name="hscode_10digits" type="object">
      Nivel de 10 digitos cuando aplica. Contiene `name` y `code`.
    </ResponseField>

    <ResponseField name="overall_confidence" type="number">
      Nivel de confianza de 0.0 a 1.0 para esta sugerencia.
    </ResponseField>

    <ResponseField name="justification" type="string">
      Explicacion del razonamiento para esta clasificacion.
    </ResponseField>

    <ResponseField name="recommendations" type="string">
      Recomendaciones adicionales para mejorar la clasificacion.
    </ResponseField>

    <ResponseField name="tariff_info" type="object">
      Informacion arancelaria asociada (impuestos, regulaciones). Solo se incluye si `tariff_info=true`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary_classification" type="string">
  Resumen de la clasificacion del producto.
</ResponseField>

<ResponseField name="required_questions" type="string[]">
  Lista de preguntas que la IA necesita que respondas para mejorar la precision de la clasificacion. Si esta vacia, la clasificacion es suficientemente precisa.
</ResponseField>

<ResponseField name="classification_record_id" type="string">
  ID del registro de clasificacion guardado. Puedes usar este ID en futuras peticiones (campo `classification_record_id`) para refinar la clasificacion con informacion adicional.
</ResponseField>

### Ejemplo de respuesta exitosa

```json theme={null}
{
  "hscodes_array": [
    {
      "hscode_2digits": { "name": "Maquinas, aparatos y material electrico", "code": "85" },
      "hscode_4digits": { "name": "Monitores y proyectores", "code": "8528" },
      "hscode_6digits": { "name": "Otros monitores", "code": "8528.52" },
      "hscode_8digits": { "name": "Monitores de pantalla plana", "code": "8528.52.01" },
      "hscode_10digits": { "name": "", "code": "" },
      "overall_confidence": 0.88,
      "justification": "Producto electronico de visualizacion tipo monitor LED con tecnologia IPS para uso con computadora. Se clasifica en la partida 85.28 para monitores y proyectores.",
      "recommendations": "Confirmar si el monitor es capaz de recibir senal de television.",
      "tariff_info": {}
    }
  ],
  "summary_classification": "Monitor LED 4K de 27 pulgadas para computadora de escritorio",
  "required_questions": [],
  "classification_record_id": "6789abc123def"
}
```

### Respuesta en streaming (NDJSON)

Cuando `streaming=true`, la respuesta se envia como `application/x-ndjson`. Cada linea es un objeto JSON independiente:

```json theme={null}
{"status": "progress", "message": "Analizando producto...", "progress": 25, "current_hscode": ""}
{"status": "progress", "message": "Clasificando...", "progress": 50, "current_hscode": "8528"}
{"status": "progress", "message": "Generando detalles...", "progress": 75, "current_hscode": "8528.52.01"}
{"status": "final", "data": { "hscodes_array": [...], "summary_classification": "...", "required_questions": [], "classification_record_id": "..." }, "http_status_code": 200}
{"status": "record_saved", "classification_record_id": "6789abc123def"}
```

<CodeGroup>
  ```python Python (streaming) theme={null}
  import requests
  import json

  response = requests.post(
      "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini",
      headers={"Authorization": "Bearer sk_tu_api_key"},
      params={"country_code": "MEX", "model": "pro"},
      data={
          "product_description": "Monitor LED 4K",
          "streaming": "true"
      },
      stream=True
  )

  for line in response.iter_lines():
      if line:
          chunk = json.loads(line)
          if chunk["status"] == "progress":
              print(f"Progreso: {chunk['progress']}% - {chunk['message']}")
          elif chunk["status"] == "final":
              result = chunk["data"]
              print(f"Resultado: {result['hscodes_array'][0]['hscode_8digits']['code']}")
  ```
</CodeGroup>

## Interpretar el nivel de confianza

El campo `overall_confidence` es un valor de 0.0 a 1.0:

| Rango       | Interpretacion     | Recomendacion                                                             |
| ----------- | ------------------ | ------------------------------------------------------------------------- |
| 0.90 - 1.00 | Confianza alta     | Clasificacion confiable para la mayoria de los casos                      |
| 0.70 - 0.89 | Confianza media    | Revisar la justificacion. Considerar agregar mas detalle a la descripcion |
| 0.50 - 0.69 | Confianza baja     | Requiere revision manual. La descripcion puede ser ambigua                |
| 0.00 - 0.49 | Confianza muy baja | No usar sin validacion de un experto. Reformular la descripcion           |

<Tip>
  Para obtener mejores resultados, incluye en la descripcion: material de fabricacion, uso o destino, composicion, forma de presentacion, dimensiones y cualquier especificacion tecnica relevante. Tambien puedes adjuntar imagenes o fichas tecnicas para mayor precision.
</Tip>

## Concurrencia

El endpoint tiene un limite de concurrencia de **50 peticiones simultaneas por worker**. Si el servicio esta saturado, la peticion esperara hasta que haya capacidad disponible.

## Errores comunes

| Codigo | Causa                                                                      | Solucion                                                       |
| ------ | -------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `400`  | No se proporciono `product_description`, `image_files` ni `document_files` | Envia al menos uno de estos campos                             |
| `401`  | API key invalida o ausente                                                 | Revisa el header `Authorization`                               |
| `402`  | Creditos insuficientes                                                     | Recarga creditos en [app.camtomx.com](https://app.camtomx.com) |
| `403`  | Suscripcion no valida o pais no permitido                                  | Verifica tu suscripcion y el `country_code`                    |
| `500`  | Error interno del servidor                                                 | Reintenta con backoff exponencial                              |

Para la referencia completa de errores, consulta [codigos de error](/api/errors).