Ir para o conteúdo principal

Encontre sua próxima ferramenta

Documentação/API/Processamento de documentos em lote com a API
API

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.

TarefaUsePor 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 áudioUm job /media/process/ por arquivo1 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.

Guias relacionados