API de fluxos de trabalho com várias etapas
Crie um fluxo de trabalho de documentos com várias etapas em uma única chamada de API, execute-o em um arquivo ou em centenas, acompanhe cada execução e baixe os resultados.
Resposta curta
Envie POST https://maxscanner.app/api/v1/workflows/ com uma lista de etapas, por exemplo [{"step":"word-to-pdf"},{"step":"compress-pdf"}]. O MaxScanner verifica se a cadeia pode ser executada na nuvem, salva, conecta à sua chave de API e retorna um automationId. Inicie com POST /api/v1/automations/{automationId}/runs/ e uma Idempotency-Key, acompanhe com GET /api/v1/automation-runs/{runId}/ e baixe cada resultado em /api/v1/documents/{documentId}/download/.
Início rápido
- 1GET /api/v1/workflow-steps/ para ver as etapas, o que cada uma aceita e gera e suas configurações.
- 2POST /api/v1/workflows/ com um nome e 1–10 etapas. Guarde workflow.automationId da resposta.
- 3Importe ou envie os arquivos e depois faça POST /api/v1/automations/{automationId}/runs/ com os documentId deles e uma Idempotency-Key.
- 4Consulte GET /api/v1/automation-runs/{runId}/ até o status ser completed, ou liste todas as execuções da automação.
- 5Baixe cada item de run.outputs com GET /api/v1/documents/{documentId}/download/.
Por que um fluxo de trabalho em vez de chamadas separadas
Um fluxo de trabalho mantém a cadeia do lado do MaxScanner: o resultado de uma etapa vai direto para a seguinte sem voltar ao seu servidor, cada execução é repetida em caso de falha e registrada, e os resultados chegam em Meus documentos. Você pode abrir um fluxo criado pela API em Painel → Fluxos de trabalho para conferir e mudar a cadeia depois sem reimplantar seu código: crie um fluxo novo e troque o automation id.
Etapas disponíveis
Estas etapas são executadas nos processadores em nuvem do MaxScanner, então um fluxo de trabalho feito delas pode rodar sem navegador.
| step | Entrada → saída | Configurações |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | Arquivo do Office → PDF | — |
| merge-pdf | 2 ou mais PDFs → um PDF (somente como primeira etapa) | — |
| compress-pdf | PDF → PDF menor | — |
| rotate-pdf | PDF → PDF | degrees: 90, 180 ou 270 |
| extract-pages | PDF → PDF | pages: "1,3-5" (contagem a partir de 1) |
| image-transform | JPG, PNG ou WebP → JPG, PNG, WebP ou AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG, PNG ou WebP → texto (inglês) | — |
Criar um fluxo de trabalho
As etapas são executadas na ordem em que você as lista e cada etapa precisa aceitar o que a anterior gera; se não combinarem, a resposta é 422 workflow_not_runnable com o motivo. Envie uma Idempotency-Key para que uma solicitação repetida retorne o mesmo fluxo de trabalho. Criar um fluxo de trabalho custa uma solicitação (um crédito nos planos pagos), e cada chave pode ter até 25 fluxos de trabalho ativos.
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" }
]
}'Execute em um arquivo ou em vários
As entradas são documentos que já estão na conta: importações pela API, uploads concluídos com /extension/upload/complete/, resultados anteriores e digitalizações do Android. Cada execução precisa de uma Idempotency-Key; repeti-la nunca inicia uma segunda execução. Use "mode": "together" (o padrão) quando os arquivos devem ir em uma única execução, como vários PDFs para merge-pdf. Use "mode": "each" para iniciar uma execução por arquivo, até 100 arquivos em uma chamada. Cada execução custa 3 créditos nos planos pagos e uma solicitação no plano Free; se o limite do plano for atingido no meio do caminho, a resposta informa quantos arquivos não foram iniciados.
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();Acompanhe as execuções e baixe os resultados
GET /api/v1/automation-runs/{runId}/ retorna o status (reserved, executing, suspended, completed, failed ou cancelled) e, depois de concluída, uma lista outputs com o documentId, nome do arquivo, tipo e tamanho de cada arquivo salvo. GET /api/v1/automations/{automationId}/runs/ lista as últimas 100 execuções com a contagem por status, a forma mais rápida de acompanhar uma chamada em lote. Consultar o status é gratuito.
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"Gerenciar fluxos de trabalho
Fluxos de trabalho criados no editor visual também podem ser executados pela API: abra Painel → Fluxos de trabalho → Versões → Executar pela API e escolha a chave. O editor também oferece etapas que precisam de uma pessoa, como assinatura, esperas e aprovações; essas ficam fora dos fluxos criados pela API.
- GET /api/v1/workflows/ lista todos os fluxos de trabalho que esta chave pode iniciar, com suas etapas
- GET /api/v1/workflows/{workflowId}/ retorna um deles
- DELETE /api/v1/workflows/{workflowId}/ desconecta o fluxo da chave; fluxos criados pela API são arquivados e execuções já iniciadas terminam
- Para mudar as etapas, crie um fluxo de trabalho novo e use o automationId dele no seu código
Perguntas frequentes
Preciso usar o editor visual?
Não. POST /api/v1/workflows/ cria o fluxo de trabalho a partir de JSON. O editor é opcional: serve para revisar o fluxo ou para etapas que não estão disponíveis na API.
Qual é a diferença entre "together" e "each"?
"together" inicia uma execução que recebe todas as entradas, o que merge-pdf precisa. "each" inicia uma execução separada para cada entrada, então um arquivo com problema não afeta os outros e os resultados chegam conforme cada arquivo termina.
Qual permissão a chave precisa ter?
"Executar fluxos de trabalho salvos" (workflows:run e workflows:read) para criar e executar fluxos, "Salvar documentos" para importar os arquivos de entrada e "Ler documentos" para baixar os resultados.
Uma execução de fluxo de trabalho envia um webhook quando termina?
Ainda não. Consulte a execução ou a lista de execuções; webhooks são enviados para jobs de processamento iniciados diretamente com /jobs, /pipeline, /pdf-job e /media/process.