API de clasificación arancelaria: guía para devs

¿Por qué integrar clasificación arancelaria vía API?

La clasificación arancelaria es el cuello de botella silencioso de muchas operaciones de comercio exterior. Cada producto que se importa o exporta necesita un código arancelario correcto, y asignarlo manualmente consume tiempo, requiere experiencia especializada y es propenso a errores. Para empresas que manejan cientos o miles de SKUs, el problema se multiplica exponencialmente.

Una API de clasificación arancelaria permite automatizar este proceso directamente desde tu sistema — ya sea un ERP, una plataforma de e-commerce, un WMS o cualquier aplicación que gestione productos. En lugar de que un especialista clasifique cada producto manualmente, tu sistema envía la descripción del producto a la API y recibe la fracción arancelaria sugerida en milisegundos.

Arquitectura de la API de Camtom

La API de Camtom es una API REST estándar que utiliza JSON como formato de intercambio. Está diseñada siguiendo los principios de simplicidad y predictibilidad: URLs descriptivas, métodos HTTP semánticos, códigos de estado estándar y mensajes de error estructurados. La API está disponible en HTTPS y soporta versioning mediante headers para garantizar compatibilidad hacia atrás.

• POST /v1/classify — Clasificación arancelaria. Envía la descripción del producto y recibe la fracción arancelaria sugerida, nivel de confianza, regulaciones asociadas y notas explicativas.
• GET /v1/tariff/{code} — Consulta de fracción. Devuelve toda la información asociada a una fracción arancelaria: arancel, IVA, regulaciones no arancelarias, NOMs aplicables y tratados de libre comercio.
• POST /v1/classify/batch — Clasificación por lotes. Permite enviar hasta 100 productos en una sola petición para procesamiento masivo.
• GET /v1/regulations/{code} — Regulaciones por fracción. Devuelve las regulaciones y restricciones no arancelarias asociadas a una fracción específica.
• GET /v1/health — Estado del servicio. Endpoint de monitoreo para verificar disponibilidad y latencia.

Autenticación y seguridad

La autenticación se realiza mediante API keys que se envían en el header Authorization con el esquema Bearer. Cada API key está asociada a una organización y tiene permisos configurables. Las keys se generan desde el panel de Camtom y pueden revocarse en cualquier momento. Toda la comunicación se realiza sobre TLS 1.2+ y las API keys nunca deben incluirse en código frontend o repositorios públicos.

Rate limits y planes

Los rate limits dependen del plan contratado. El plan Basic permite 100 clasificaciones por mes, Pro permite 600, Growth sube a 1,800 y Scale llega a 6,000. Para volúmenes superiores, el plan Enterprise ofrece límites personalizados. Los rate limits se aplican por API key con ventanas de 1 minuto, y la API devuelve headers estándar (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) para que tu sistema pueda gestionar el consumo proactivamente.

Casos de uso: ERP, e-commerce y WMS

• ERP (SAP, Oracle, Dynamics): Clasificación automática al dar de alta nuevos materiales. Cuando un usuario crea un nuevo artículo en el maestro de materiales, el ERP consulta la API y pre-llena la fracción arancelaria.
• E-commerce (Shopify, WooCommerce, Magento): Clasificación al importar catálogos de proveedores internacionales. El sistema clasifica cada SKU antes de listar el producto, asegurando que los costos de importación se reflejen en el precio final.
• WMS (Manhattan, Blue Yonder): Validación de clasificación al recibir mercancía. El WMS verifica que la fracción arancelaria del producto coincida con la declarada en el pedimento.
• TMS (sistemas de transporte): Determinación automática de regulaciones y permisos requeridos antes de coordinar el transporte internacional.
• Plataformas propias: Cualquier sistema interno que gestione operaciones de comercio exterior puede integrarse para eliminar la clasificación manual.

Ejemplo de integración rápida

Integrar la API de Camtom es sencillo. Con unas pocas líneas de código puedes enviar la descripción de un producto y recibir la clasificación sugerida. Los SDKs oficiales están disponibles para Python, Node.js y Java, y simplifican aún más la integración al manejar autenticación, reintentos y paginación automáticamente. Para otros lenguajes, cualquier cliente HTTP funciona con la API REST estándar.

“La mejor clasificación arancelaria es la que sucede sin que nadie tenga que pensar en ella. Cuando tu sistema clasifica automáticamente, tu equipo se enfoca en lo que realmente importa.”

— Equipo Camtom