Ir para o conteúdo principal

Encontre sua próxima ferramenta

Documentação/API/API de fluxos de trabalho com várias etapas
API

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

  1. 1GET /api/v1/workflow-steps/ para ver as etapas, o que cada uma aceita e gera e suas configurações.
  2. 2POST /api/v1/workflows/ com um nome e 1–10 etapas. Guarde workflow.automationId da resposta.
  3. 3Importe ou envie os arquivos e depois faça POST /api/v1/automations/{automationId}/runs/ com os documentId deles e uma Idempotency-Key.
  4. 4Consulte GET /api/v1/automation-runs/{runId}/ até o status ser completed, ou liste todas as execuções da automação.
  5. 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.

stepEntrada → saídaConfigurações
word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdfArquivo do Office → PDF—
merge-pdf2 ou mais PDFs → um PDF (somente como primeira etapa)—
compress-pdfPDF → PDF menor—
rotate-pdfPDF → PDFdegrees: 90, 180 ou 270
extract-pagesPDF → PDFpages: "1,3-5" (contagem a partir de 1)
image-transformJPG, PNG ou WebP → JPG, PNG, WebP ou AVIFformat, quality, maxWidth, maxHeight, width, height, targetBytes
image-ocrJPG, 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.

Guias relacionados