Processamento de documentos em lote com a API
Converta, comprima ou aplique OCR em centenas de arquivos: escolha entre jobs em lote e execuções de fluxos em lote, respeite os limites do plano e repita apenas o que falhou.
Resposta curta
Para uma conversão de uma etapa com até 20 arquivos por chamada, use POST /api/v1/jobs/batch/ com um array "jobs" e acompanhe com GET /api/v1/jobs/batch/{batchId}/. Para várias etapas por arquivo, crie um fluxo de trabalho e inicie-o com "mode": "each" em até 100 documentos por chamada. Dê a cada chamada uma Idempotency-Key estável para que uma nova tentativa inicie apenas o que falta.
Escolha a ferramenta certa
No plano Free cada chamada de processamento conta como uma das 10 solicitações diárias, então o trabalho em lote exige um plano pago ou créditos comprados.
| Tarefa | Use | Por chamada |
|---|---|---|
| A mesma conversão para muitos arquivos (DOCX → PDF) | POST /jobs/batch/ | 1–20 arquivos, 2 créditos por lote |
| Várias etapas por arquivo (converter, comprimir, girar) | Fluxo de trabalho + execuções com mode "each" | 1–100 documentos, 3 créditos por execução |
| Combinar muitos arquivos em um (mesclar) | Fluxo de trabalho + execuções com mode "together" | até 100 documentos em uma execução |
| Vídeo e áudio | Um job /media/process/ por arquivo | 1 arquivo, 1 crédito |
Conversões em lote
Cada item aceita os mesmos campos que POST /jobs/: url ou sourceKey, filename, format e, opcionalmente, inputFormat. O lote é validado por inteiro (a resposta indica o índice do primeiro item inválido) e cada item vira um job próprio.
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"Execuções de fluxos de trabalho em lote
Primeiro importe ou envie os arquivos (cada importação retorna um documentId) e depois inicie uma execução por documento em uma única chamada. As execuções entram na fila e são processadas em ordem em processadores compartilhados, então 100 arquivos do Office levam minutos, não segundos; consulte GET /api/v1/automations/{automationId}/runs/ a cada 15–30 segundos e veja a contagem por status.
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"))Repita com segurança
- Repita uma chamada de execução em lote com a mesma Idempotency-Key: execuções que já existem são ignoradas (replayedCount) e só as que faltam são iniciadas
- Se notStarted aparecer, o limite do plano interrompeu a chamada; adicione créditos ou espere a renovação e repita a mesma solicitação
- Uma execução com falha não afeta as outras; inicie uma nova execução para esse documento com uma nova Idempotency-Key
- Mantenha no máximo algumas centenas de execuções em andamento; espere counts.completed aumentar antes de enviar a próxima centena
Perguntas frequentes
Existe limite de execuções na fila?
Cada chamada inicia no máximo 100 execuções. Não há um limite separado de fila, mas as execuções compartilham processadores com outros clientes, então acúmulos muito grandes terminam mais devagar. Envie o trabalho em lotes de algumas centenas.
Posso receber um ZIP com todos os resultados?
Pela API, ainda não. Baixe cada resultado do respectivo documento ou use as ferramentas de ZIP do site.