API de flujos de trabajo de varios pasos
Crea un flujo de trabajo de documentos de varios pasos con una sola llamada a la API, ejecútalo en un archivo o en cientos, sigue cada ejecución y descarga los resultados.
Respuesta breve
Envía POST https://maxscanner.app/api/v1/workflows/ con una lista de pasos, por ejemplo [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. MaxScanner comprueba que la cadena puede ejecutarse en la nube, la guarda, la conecta a tu clave de API y devuelve un automationId. Inícialo con POST /api/v1/automations/{automationId}/runs/ y una Idempotency-Key, sigue su progreso con GET /api/v1/automation-runs/{runId}/ y descarga cada resultado desde /api/v1/documents/{documentId}/download/.
Inicio rápido
- 1GET /api/v1/workflow-steps/ para ver los pasos, qué acepta y produce cada uno y sus ajustes.
- 2POST /api/v1/workflows/ con un nombre y 1–10 pasos. Guarda workflow.automationId de la respuesta.
- 3Importa o sube los archivos y después envía POST /api/v1/automations/{automationId}/runs/ con sus documentId y una Idempotency-Key.
- 4Consulta GET /api/v1/automation-runs/{runId}/ hasta que el estado sea completed, o lista todas las ejecuciones de la automatización.
- 5Descarga cada entrada de run.outputs con GET /api/v1/documents/{documentId}/download/.
Por qué un flujo de trabajo en lugar de llamadas sueltas
Un flujo de trabajo mantiene la cadena en el lado de MaxScanner: el resultado de un paso pasa directamente al siguiente sin volver a tu servidor, cada ejecución se reintenta y queda registrada, y los resultados llegan a Mis documentos. Puedes abrir un flujo creado por la API en Panel → Flujos de trabajo para revisarlo, y cambiar la cadena más adelante sin volver a desplegar tu código: crea un flujo nuevo y cambia el automation id.
Pasos disponibles
Estos pasos se ejecutan en los procesadores en la nube de MaxScanner, así que un flujo de trabajo formado por ellos puede ejecutarse sin navegador.
| step | Entrada → salida | Ajustes |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | Archivo de Office → PDF | — |
| merge-pdf | 2 o más PDF → un PDF (solo como primer paso) | — |
| compress-pdf | PDF → PDF más ligero | — |
| rotate-pdf | PDF → PDF | degrees: 90, 180 o 270 |
| extract-pages | PDF → PDF | pages: "1,3-5" (numeración desde 1) |
| image-transform | JPG, PNG o WebP → JPG, PNG, WebP o AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG, PNG o WebP → texto (inglés) | — |
Crear un flujo de trabajo
Los pasos se ejecutan en el orden en que los indicas y cada paso debe aceptar lo que produce el anterior; si no encajan, la respuesta es 422 workflow_not_runnable con el motivo. Envía una Idempotency-Key para que una solicitud reintentada devuelva el mismo flujo de trabajo. Crear un flujo de trabajo cuesta una solicitud (un crédito en los planes de pago) y cada clave puede tener hasta 25 flujos de trabajo activos.
curl -X POST 'https://maxscanner.app/api/v1/workflows/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: create-contract-flow-v1' \
-d '{
"name": "Contracts to small PDF",
"steps": [
{ "step": "word-to-pdf" },
{ "step": "compress-pdf" }
]
}'Ejecútalo en un archivo o en muchos
Las entradas son documentos que ya están en la cuenta: importaciones por API, subidas completadas con /extension/upload/complete/, resultados anteriores y escaneos de Android. Cada ejecución necesita una Idempotency-Key; repetirla nunca inicia una segunda ejecución. Usa "mode": "together" (el valor predeterminado) cuando los archivos deban ir en una sola ejecución, como varios PDF para merge-pdf. Usa "mode": "each" para iniciar una ejecución por archivo, hasta 100 archivos en una llamada. Cada ejecución cuesta 3 créditos en los planes de pago y una solicitud en el plan Free; si se alcanza el límite del plan a mitad de camino, la respuesta indica cuántos archivos no se iniciaron.
const res = await fetch(`https://maxscanner.app/api/v1/automations/${automationId}/runs/`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAXSCANNER_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'contracts-2026-11-11',
},
body: JSON.stringify({
mode: 'each', // one run per document
inputs: documentIds.map((documentId) => ({ kind: 'document', documentId })),
}),
});
const { runs, replayedCount, notStarted } = await res.json();Sigue las ejecuciones y descarga los resultados
GET /api/v1/automation-runs/{runId}/ devuelve el estado (reserved, executing, suspended, completed, failed o cancelled) y, una vez completada, una lista outputs con el documentId, el nombre de archivo, el tipo y el tamaño de cada archivo guardado. GET /api/v1/automations/{automationId}/runs/ lista las últimas 100 ejecuciones con un recuento por estado, la forma más rápida de seguir una llamada en lote. Consultar el estado es gratis.
curl 'https://maxscanner.app/api/v1/automation-runs/$RUN_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"
# then, for each output:
curl "https://maxscanner.app/api/v1/documents/$DOCUMENT_ID/download/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"Gestionar flujos de trabajo
Los flujos de trabajo creados en el editor visual también pueden ejecutarse desde la API: abre Panel → Flujos de trabajo → Versiones → Ejecutar desde la API y elige la clave. El editor también ofrece pasos que necesitan a una persona, como firmar, esperas y aprobaciones; esos quedan fuera de los flujos creados por la API.
- GET /api/v1/workflows/ lista todos los flujos de trabajo que esta clave puede iniciar, con sus pasos
- GET /api/v1/workflows/{workflowId}/ devuelve uno
- DELETE /api/v1/workflows/{workflowId}/ lo desconecta de la clave; los flujos creados por la API se archivan y las ejecuciones ya iniciadas terminan
- Para cambiar los pasos, crea un flujo de trabajo nuevo y usa su automationId en tu código
Preguntas frecuentes
¿Tengo que usar el editor visual?
No. POST /api/v1/workflows/ crea el flujo de trabajo a partir de JSON. El editor es opcional: sirve para revisarlo o para pasos que no están disponibles en la API.
¿Qué diferencia hay entre "together" y "each"?
"together" inicia una ejecución que recibe todas las entradas, algo que merge-pdf necesita. "each" inicia una ejecución distinta por entrada, así que un archivo defectuoso no afecta a los demás y los resultados llegan a medida que termina cada archivo.
¿Qué permiso necesita la clave?
"Ejecutar flujos de trabajo guardados" (workflows:run y workflows:read) para crear y ejecutar flujos, "Guardar documentos" para importar los archivos de entrada y "Leer documentos" para descargar los resultados.
¿Envía un webhook una ejecución de flujo de trabajo cuando termina?
Todavía no. Consulta la ejecución o la lista de ejecuciones; los webhooks se envían para trabajos de procesamiento iniciados directamente con /jobs, /pipeline, /pdf-job y /media/process.