Integración API para procesamiento de documentos con Camtom Docs

¿Por qué integrar la API de Docs?

La API de Camtom Docs permite automatizar el procesamiento de documentos aduanales desde tu propio sistema: ERP, TMS, WMS o cualquier aplicación personalizada. En lugar de cargar documentos manualmente en la interfaz web, puedes enviarlos programáticamente y recibir los datos extraídos en formato JSON listo para consumir. Agencias aduanales que procesan cientos de operaciones diarias pueden reducir su tiempo de captura en un 80% integrando la API directamente en su flujo de trabajo.

Requisitos previos

• Plan Pro o superior de Camtom (la API no está disponible en planes Free o Basic).
• API Key generada desde la sección de Desarrolladores en tu cuenta Camtom.
• Conocimiento básico de APIs REST, HTTP y JSON.
• Un entorno de desarrollo con capacidad para realizar llamadas HTTP (Node.js, Python, cURL, etc.).

Paso 1: Obtener tu API Key

Accede a tu cuenta Camtom, ve a Configuración > Desarrolladores > API Keys. Haz clic en 'Generar nueva API Key'. Asigna un nombre descriptivo (ejemplo: 'Integración ERP Producción') y selecciona los permisos: 'docs:read' para consultar documentos, 'docs:write' para cargar y procesar, 'docs:delete' para eliminar. Copia la API Key inmediatamente; no se mostrará de nuevo.

Paso 2: Autenticación

Todas las llamadas a la API requieren autenticación via header HTTP. Incluye tu API Key en cada request con el header 'Authorization: Bearer {tu-api-key}'. La API utiliza HTTPS exclusivamente; las llamadas HTTP sin SSL serán rechazadas. El endpoint base es: https://api.camtomx.com/v1/.

Paso 3: Cargar un documento

Usa el endpoint POST /v1/documents/upload para cargar un documento. El request debe ser multipart/form-data con el archivo en el campo 'file' y opcionalmente un campo 'type' que indique el tipo de documento ('invoice', 'packing-list', 'pedimento', 'bl', 'certificate'). Si no especificas el tipo, el sistema lo detectará automáticamente. La respuesta incluye un 'documentId' que necesitarás para consultar el resultado.

Paso 4: Consultar el estado de procesamiento

El procesamiento es asíncrono. Usa GET /v1/documents/{documentId}/status para consultar el estado. Los estados posibles son: 'queued' (en cola), 'processing' (procesando), 'completed' (completado), 'failed' (error). El tiempo promedio de procesamiento es de 3-10 segundos dependiendo del tipo y tamaño del documento. Puedes implementar polling cada 2 segundos o configurar un webhook para recibir notificación cuando el procesamiento termine.

Paso 5: Obtener los datos extraídos

Una vez que el estado es 'completed', usa GET /v1/documents/{documentId}/data para obtener los datos extraídos en formato JSON. La respuesta incluye todos los campos detectados, organizados por sección, con el valor extraído y el nivel de confianza de cada campo. Los campos con confianza menor al 80% incluyen una bandera 'reviewRequired: true'.

Paso 6: Configurar webhooks

Para evitar polling, configura un webhook en POST /v1/webhooks. Especifica la URL de tu servidor donde recibirás las notificaciones y los eventos que te interesan: 'document.processed', 'document.failed', 'document.reviewed'. Camtom enviará un POST a tu URL con el payload del evento firmado con HMAC-SHA256 usando tu webhook secret.

Límites de la API

• Rate limit: 100 requests por minuto por API Key.
• Tamaño máximo de archivo: 25 MB por documento.
• Formatos soportados: PDF, JPG, PNG, TIFF.
• Documentos por lote: hasta 50 documentos en una sola llamada batch.
• Retención de datos: los documentos procesados se retienen 90 días; después se eliminan automáticamente.
• Cada documento procesado consume entre 1 y 3 CU según el tipo y complejidad.

Manejo de errores

La API retorna códigos HTTP estándar: 200 (éxito), 201 (creado), 400 (request inválido), 401 (no autorizado), 403 (sin permisos), 404 (no encontrado), 429 (rate limit excedido), 500 (error interno). Cada respuesta de error incluye un campo 'error' con un código máquina y un campo 'message' con una descripción legible. Implementa reintentos con backoff exponencial para errores 429 y 500.

Ejemplo completo de integración

Un flujo típico de integración consiste en: (1) recibir un documento por email o desde tu ERP, (2) cargar el documento via POST /v1/documents/upload, (3) recibir la notificación via webhook cuando el procesamiento termine, (4) obtener los datos con GET /v1/documents/{id}/data, (5) mapear los datos al formato de tu sistema interno, y (6) validar contra tus reglas de negocio antes de insertarlos en tu base de datos.