Saltar al contenido principal

Encuentra tu próxima herramienta

Documentación/API/Procesamiento de documentos en lote con la API
API

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.

TareaUsaPor 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 audioUn trabajo /media/process/ por archivo1 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.

Guías relacionadas