Autenticacion API Camtom | API key y tokens

Configura tu API key para integrar clasificacion arancelaria y extraccion de documentos. Guia de autenticacion con ejemplos en Python y JS.

Todas las peticiones a la API de Camtom requieren un Bearer token en el header Authorization. Sin el, recibes un error 401 Unauthorized.

Existen dos mecanismos de autenticacion: API keys (para integraciones externas) y JWT tokens (para sesiones de la webapp).

Header de autenticacion

Incluye tu API key o JWT token en cada peticion:

Authorization: Bearer sk_tu_api_key

Python

import requests

headers = {"Authorization": "Bearer sk_tu_api_key"}

response = requests.post(
    "https://api.camtomx.com/api/v3/tariffpro/tariffpro-mini",
    headers=headers,
    params={"country_code": "MEX", "model": "pro"},
    data={"product_description": "Tornillo de acero inoxidable M8x40mm"}
)

Mecanismos de autenticacion

API Keys

Los tokens que comienzan con los prefijos sk_, st_, cmt_ o cm_ son tratados como API keys. El proceso de validacion es:

1. Se valida que la API key sea activa y que la organizacion tenga una suscripcion vigente
2. Se valida que la organizacion tenga suscripcion pro o enterprise, y que la suscripcion no este expirada

JWT Tokens

Los tokens que no coinciden con los prefijos de API key se tratan como JWT. Los JWT tokens son utilizados por la webapp de Camtom y tienen expiracion automatica.

Los JWT tokens son utilizados por la webapp de Camtom. Para integraciones via API, usa siempre una API key.

Obtener tu API key

1. Inicia sesion en app.camtomx.com
2. Ve a Settings (Configuracion) en el menu lateral
3. Selecciona la seccion API Keys
4. Haz clic en Crear nueva API key
5. Copia la key — solo se muestra una vez

Guarda tu API key en un lugar seguro al momento de crearla. Por razones de seguridad, no podras volver a verla despues. Si la pierdes, deberas generar una nueva.

Tipos de API key

Camtom usa prefijos para distinguir los tipos de key:

Prefijo	Tipo	Uso
sk_	Secret Key	Produccion. Acceso completo a la API. Se genera como sk_ + 64 caracteres hex. Nunca la expongas en frontend.
st_	Test Key	Desarrollo y pruebas.
cmt_	Camtom Key	Keys internas de Camtom para integraciones propias.
cm_	Compact Key	Version compacta para integraciones con restricciones de longitud.

Requisitos de suscripcion

Para usar la API con API keys, tu organizacion debe tener una suscripcion pro o enterprise activa. Las organizaciones con plan free tienen acceso limitado:

• Solo pueden usar country_code=WORLD para clasificaciones
• Intentar usar otros codigos de pais devuelve 403: “Your current plan only allows access to WORLD classifications.”

Sistema de creditos

La API de Camtom opera con un sistema de creditos basado en la suscripcion:

• Cada organizacion tiene limites de creditos definidos en su suscripcion
• Cada API key pertenece a una organizacion y comparte sus creditos
• Cada producto tiene limites de creditos definidos en tu suscripcion
• Cada llamada que consume creditos queda registrada

Endpoint	Consumo
TariffPro Mini	1 credito por clasificacion
CamtomDocs Extract	Segun paginas procesadas (ver campo billed_pages en la respuesta)

Cuando tus creditos se agotan, la API responde con un error 402 (CamtomDocs) o 403 indicando creditos insuficientes.

Consulta tu saldo de creditos en cualquier momento desde Settings > Billing en la plataforma.

Rutas exentas de autenticacion

Las siguientes rutas no requieren token de autenticacion:

• Peticiones OPTIONS (CORS preflight)
• /, /api/v2, /docs, /redoc, /openapi.json, /health, /favicon.ico
• Cualquier ruta que termine en /health
• Rutas publicas de ShareLink: /api/v3/sharelink/questions/*, /api/v3/sharelink/responses/*, /api/v3/operations-sharelink/info/*

Seguridad

Sigue estas practicas para proteger tu API key:

• Nunca incluyas tu API key en codigo frontend (JavaScript del navegador, apps moviles). Usa siempre un backend como intermediario.
• Usa variables de entorno para almacenar tus keys en lugar de hardcodearlas en el codigo.
• Rota tus keys periodicamente desde el panel de configuracion.
• Cancela keys comprometidas inmediatamente usando el endpoint PATCH /api/keys/cancel o desde la plataforma.

Python (.env)

# .env
CAMTOM_API_KEY=sk_tu_api_key

# app.py
import os
import requests

api_key = os.environ["CAMTOM_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}"}

Errores de autenticacion

Codigo	Causa	Solucion
401	Token ausente o invalido	Verifica que el header Authorization esta presente con formato Bearer <token>
401	API key revocada	Genera una nueva key desde el panel de configuracion
401	JWT expirado	Refresca el token usando /api/refresh-token
403	Suscripcion no es pro ni enterprise	Actualiza tu plan de suscripcion
403	Suscripcion expirada	Renueva tu suscripcion en app.camtomx.com
403	Pais no permitido en plan free	Usa country_code=WORLD o actualiza a plan pro

Para mas detalles sobre errores, consulta la referencia de codigos de error.