Ejecuciones
Cómo se crea, se consulta, se reintenta y es idempotente una ejecución de la API pública.
Una ejecución aplica una plantilla a un archivo subido, en el servidor, y devuelve el resultado en la misma respuesta o por descarga.
Las ejecuciones rápidas responden al instante
POST /templates/{id}/runs espera hasta 30 segundos a que la ejecución termine. Si termina a tiempo, obtienes 201 con la ejecución terminada — su resultado ya está listo para descargar.
Ejecuciones más lentas: 202 y consulta
Pasados los 30 segundos obtienes 202, una cabecera Location que apunta a la ejecución, y una cabecera Retry-After que indica cuánto esperar antes de volver a consultar GET /runs/{id}.
Overrides
Una subida CSV puede enviar delimiter y header_row junto a file, sobrescribiendo los valores detectados automáticamente solo para esa ejecución.
curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-F "file=@/ruta/a/tu/archivo.csv" \
-F "delimiter=;" \
-F "header_row=0"Cuando un archivo no puede ejecutarse
Si al archivo subido le falta una columna que las operaciones de la plantilla requieren, la propia solicitud se rechaza con 422 TEMPLATE_COLUMNS_MISSING — no como una ejecución terminada pero fallida que haya que consultar.
Descargar el resultado
El resultado de una ejecución terminada se puede descargar durante 30 minutos después de completarse, desde cualquier worker. Pasado ese tiempo, o si ya expiró, GET /runs/{id}/output responde 404 RUN_NOT_FOUND.
Reintentar con seguridad: Idempotency-Key
Envía una cabecera Idempotency-Key con POST /templates/{id}/runs y un reintento de red de la misma solicitud reproduce la ejecución ya iniciada o terminada para esa clave, en lugar de iniciar (y cobrar) una segunda. Reutilizar la misma clave con una solicitud distinta responde 409 IDEMPOTENCY_KEY_REUSED.
RUN_NOT_FOUND, RUN_INTERRUPTED, RUN_TIMEOUT → reenviar
Una ejecución cuyo worker se reinició antes de terminar se resuelve como RUN_INTERRUPTED; una que sigue en marcha pasados 10 minutos se resuelve como RUN_TIMEOUT; una cuyo id es desconocido o expiró responde RUN_NOT_FOUND. En cualquiera de los tres casos, reenvía la solicitud con la misma Idempotency-Key para intentarlo de nuevo.
Consulta Errores y límites para cada código de estado con el que puede responder una ejecución.