Procesamiento de documentos en lote con la API
Convierte, comprime o aplica OCR a cientos de archivos: elige entre trabajos por lotes y ejecuciones de flujos en lote, mantente dentro de los límites del plan y reintenta solo lo que falló.
Respuesta breve
Para una conversión de un solo paso de hasta 20 archivos por llamada, usa POST /api/v1/jobs/batch/ con un array "jobs" y síguela con GET /api/v1/jobs/batch/{batchId}/. Para varios pasos por archivo, crea un flujo de trabajo e inícialo con "mode": "each" en hasta 100 documentos por llamada. Da a cada llamada una Idempotency-Key estable para que un reintento solo inicie lo que falta.
Elige la herramienta adecuada
En el plan Free cada llamada de procesamiento cuenta como una de las 10 solicitudes diarias, así que el trabajo en lote necesita un plan de pago o créditos comprados.
| Tarea | Usa | Por llamada |
|---|---|---|
| La misma conversión para muchos archivos (DOCX → PDF) | POST /jobs/batch/ | 1–20 archivos, 2 créditos por lote |
| Varios pasos por archivo (convertir, comprimir, girar) | Flujo de trabajo + ejecuciones con mode "each" | 1–100 documentos, 3 créditos por ejecución |
| Combinar muchos archivos en uno (unir) | Flujo de trabajo + ejecuciones con mode "together" | hasta 100 documentos en una ejecución |
| Vídeo y audio | Un trabajo /media/process/ por archivo | 1 archivo, 1 crédito |
Conversiones por lotes
Cada elemento admite los mismos campos que POST /jobs/: url o sourceKey, filename, format y, opcionalmente, inputFormat. El lote se valida completo (la respuesta indica el índice del primer elemento incorrecto) y cada elemento se convierte en su propio trabajo.
curl -X POST 'https://maxscanner.app/api/v1/jobs/batch/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "jobs": [
{ "url": "https://example.com/a.docx", "filename": "a.docx", "format": "pdf" },
{ "url": "https://example.com/b.xlsx", "filename": "b.xlsx", "format": "pdf" }
] }'
curl 'https://maxscanner.app/api/v1/jobs/batch/$BATCH_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"Ejecuciones de flujos de trabajo en lote
Primero importa o sube los archivos (cada importación devuelve un documentId) y después inicia una ejecución por documento en una sola llamada. Las ejecuciones entran en cola y se procesan en orden en procesadores compartidos, así que 100 archivos de Office tardan minutos, no segundos; consulta GET /api/v1/automations/{automationId}/runs/ cada 15–30 segundos y revisa los recuentos por estado.
import os, requests
KEY = os.environ["MAXSCANNER_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://maxscanner.app/api/v1"
doc_ids = [requests.post(f"{BASE}/documents/import/", headers=H, json={"url": u, "filename": u.rsplit("/", 1)[-1]}, timeout=60).json()["documentId"] for u in urls]
r = requests.post(f"{BASE}/automations/{automation_id}/runs/", headers={**H, "Idempotency-Key": "invoices-2026-11"},
json={"mode": "each", "inputs": [{"kind": "document", "documentId": d} for d in doc_ids]}, timeout=60)
print(r.status_code, r.json().get("notStarted"))Reintentar con seguridad
- Repite una llamada de ejecución en lote con la misma Idempotency-Key: las ejecuciones que ya existen se omiten (replayedCount) y solo se inician las que faltan
- Si aparece notStarted, el límite del plan detuvo la llamada; añade créditos o espera al reinicio y repite la misma solicitud
- Una ejecución fallida no afecta a las demás; inicia una ejecución nueva para ese documento con una Idempotency-Key nueva
- No mantengas más de unos cientos de ejecuciones en curso; espera a que suba counts.completed antes de enviar el siguiente centenar
Preguntas frecuentes
¿Hay un límite de ejecuciones en cola?
Cada llamada inicia como máximo 100 ejecuciones. No hay un límite de cola aparte, pero las ejecuciones comparten procesadores con otros clientes, así que las acumulaciones muy grandes terminan más despacio. Envía el trabajo en tandas de unos cientos.
¿Puedo obtener un ZIP con todos los resultados?
Desde la API, todavía no. Descarga cada resultado desde su documento o usa las herramientas ZIP del sitio web.