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>

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.

Query parameters

country_code · 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)

model · string · default: "pro"

Tier del modelo de clasificacion.

Valores permitidos:

• fast — Mas rapido, menor precision
• pro — Mayor precision (default)

tariff_info · boolean · default: "true"

Si se debe incluir informacion arancelaria (impuestos, regulaciones) en la respuesta.

user_identifier · string

Identificador opcional del usuario que realiza la peticion. Se utiliza para tracking interno.

Body parameters (multipart/form-data)

product_description · string

Descripcion del producto a clasificar. Mientras mas detallada sea la descripcion (material, uso, composicion, presentacion), mas preciso sera el resultado.

image_files · file[]

Imagenes de soporte del producto. Maximo 10 archivos. Formatos de imagen comunes soportados.

document_files · file[]

Documentos de soporte (fichas tecnicas, especificaciones PDF, etc.). Maximo 10 archivos.

streaming · boolean · default: "false"

Si se activa, la respuesta se envia como NDJSON streaming (application/x-ndjson) con actualizaciones de progreso en tiempo real.

classification_record_id · string

ID de un registro de clasificacion previo. Se usa para refinar una clasificacion existente proporcionando informacion adicional.

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

Ejemplo de request

Python

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']}")

Ejemplo con archivos

Python (con imagenes)

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"))
    ]
)

Response

Respuesta estandar (sin streaming)

hscodes_array · array

Lista de codigos HS sugeridos, ordenados por relevancia. Cada elemento contiene:

Show Propiedades de cada codigo HS

hscode_2digits · object

Capitulo del Sistema Armonizado. Contiene name (nombre) y code (codigo).

hscode_4digits · object

Partida arancelaria. Contiene name y code.

hscode_6digits · object

Subpartida arancelaria. Contiene name y code.

hscode_8digits · object

Fraccion arancelaria (nivel nacional). Contiene name y code.

hscode_10digits · object

Nivel de 10 digitos cuando aplica. Contiene name y code.

overall_confidence · number

Nivel de confianza de 0.0 a 1.0 para esta sugerencia.

justification · string

Explicacion del razonamiento para esta clasificacion.

recommendations · string

Recomendaciones adicionales para mejorar la clasificacion.

tariff_info · object

Informacion arancelaria asociada (impuestos, regulaciones). Solo se incluye si tariff_info=true.

summary_classification · string

Resumen de la clasificacion del producto.

required_questions · 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.

classification_record_id · 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.

Ejemplo de respuesta exitosa

{
  "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:

{"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"}

Python (streaming)

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']}")

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

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.

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
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.