Execuções
Como uma execução da API pública é criada, consultada, repetida e é idempotente.
Uma execução aplica um modelo a um arquivo enviado, no servidor, e devolve o resultado.
Execuções rápidas respondem na hora
POST /templates/{id}/runs espera até 30 segundos a execução terminar. Se terminar a tempo, você recebe 201 com a execução concluída — o resultado já está pronto para baixar.
Execuções mais lentas: 202 e consulta
Depois de 30 segundos você recebe 202, um cabeçalho Location apontando para a execução, e um cabeçalho Retry-After dizendo quanto esperar antes de consultar de novo GET /runs/{id}.
Overrides
Um envio CSV pode incluir delimiter e header_row junto com file, sobrescrevendo os valores detectados automaticamente só para aquela execução.
curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-F "file=@/caminho/para/seu/arquivo.csv" \
-F "delimiter=;" \
-F "header_row=0"Quando um arquivo não pode ser executado
Se ao arquivo enviado faltar uma coluna que as operações do modelo exigem, a própria solicitação é recusada com 422 TEMPLATE_COLUMNS_MISSING — não como uma execução concluída mas malsucedida para consultar.
Baixando o resultado
O resultado de uma execução concluída fica disponível para download por 30 minutos após terminar, de qualquer worker. Depois disso, ou quando expira, GET /runs/{id}/output responde 404 RUN_NOT_FOUND.
Repetindo com segurança: Idempotency-Key
Envie um cabeçalho Idempotency-Key com POST /templates/{id}/runs e uma nova tentativa de rede da mesma solicitação reproduz a execução já iniciada ou concluída para essa chave, em vez de iniciar (e cobrar) uma segunda. Reutilizar a mesma chave com uma solicitação diferente responde 409 IDEMPOTENCY_KEY_REUSED.
RUN_NOT_FOUND, RUN_INTERRUPTED, RUN_TIMEOUT → reenvie
Uma execução cujo worker reiniciou antes de terminar se resolve como RUN_INTERRUPTED; uma que ainda está rodando depois de 10 minutos se resolve como RUN_TIMEOUT; uma cujo id é desconhecido ou expirou responde RUN_NOT_FOUND. Em qualquer um dos casos, reenvie com a mesma Idempotency-Key para tentar de novo.
Veja Erros e limites para cada código de status com que uma execução pode responder.