Ejecuciones
Cómo se crea una ejecución, cómo sabes que terminó y cómo reintentarla sin cobrarla dos veces.
Respuesta inmediata o 202
POST /templates/{id}/runs espera hasta 30 segundos a que termine la ejecución. Si termina, recibes 201 con la ejecución terminada y su salida lista para descargar. Pasados los 30 segundos recibes 202, una cabecera Location que apunta a la ejecución y una cabecera Retry-After que indica cuánto esperar antes de consultar.
Una subida CSV puede enviar delimiter y header_row junto a file, y sustituye los valores detectados 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=@/path/to/your/file.csv" \
-F "delimiter=;" \
-F "header_row=0"Si se renombró una columna, la ejecución responde TEMPLATE_COLUMNS_MISSING con missing_columns: cada columna que lee la plantilla, con las columnas del archivo para elegir. No se cobra nada. Reintenta con column_mapping, un objeto JSON {"columna del archivo": "columna de la plantilla"}, solo para esa ejecución; nunca se guarda. Una columna que solo difiere en mayúsculas, espacios o guiones bajos se asigna sola y se informa como aviso COLUMN_MATCHED.
Consultar el estado
GET /runs/{id} devuelve la ejecución con su estado: running, succeeded o failed. Consúltala, esperando lo que indique Retry-After, hasta que se resuelva. Cada campo está en la Referencia de la API. Mejor aún: un webhook te avisa.
curl "https://doctransform.xyz/api/v1/runs/run_abc" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY"Descargar el resultado
GET /runs/{id}/output descarga el archivo. La salida de una ejecución terminada sigue disponible 30 minutos, o 3 días si un webhook recibe la ejecución; después, o con un id desconocido, responde RUN_NOT_FOUND.
curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-o result.csvCuando un archivo no puede ejecutarse
Una ejecución no tiene ningún Dataset en curso: cada archivo que necesita llega en la petición. Una petición que no puede ejecutarse se rechaza de entrada, nunca es una ejecución fallida que consultar.
- Un archivo al que le falta una columna que la plantilla necesita: TEMPLATE_COLUMNS_MISSING.
- Varias partes
filea una plantilla sin paso Append: TEMPLATE_TAKES_ONE_FILE. Más partes de las que permite tu plan: FILE_COUNT_LIMIT_EXCEEDED. - Un archivo que es la propia salida de esta plantilla: TEMPLATE_OUTPUT_AS_SOURCE. No se cobra nada.
- Una ejecución correcta aún puede llevar una lista
warnings, con una entrada APPEND_LOCALE_DISAGREEMENT por cada parte cuyos números se leen distinto con sus propios separadores. No se convierte nada. - Una plantilla con hoja Summary añade un aviso cuando la hoja no puede escribirse porque la plantilla no es Excel: SUMMARY_SHEET_NOT_WRITTEN. Añade otro cuando la hoja tiene casi tantas filas como los datos: SUMMARY_SHEET_ONE_GROUP_PER_ROW. Una hoja Summary que no puede construirse hace fallar la ejecución con SUMMARY_SHEET_BROKEN. Esa ejecución fallida no se cobra.
Una plantilla que nombra el sistema al que sube añade a la ejecución, una vez correcta, un destination_check: passed, rows_checked, rows_failing y una entrada de reasons por cada regla que falla, con su rule_id, la cabecera field, outcome, count y un message fijo. Solo lleva recuentos, nunca un valor de su archivo. Una comprobación que falla no hace fallar la ejecución: el estado, el código de estado y el cobro son los de cualquier ejecución correcta, así que un script puede decidir según passed antes de subir. Es null si la plantilla no nombra ningún sistema y hasta que la ejecución sea correcta.
Una ejecución correcta devuelve un archivo o el ZIP de partes y un change_report: lines en inglés con las filas cambiadas por columna y los recuentos en steps. Solo recuentos y cabeceras, nunca un valor de su archivo. null hasta que la ejecución sea correcta.
Cada ejecución correcta guarda sus recuentos en la plantilla. En la siguiente, cada paso del change_report trae los recuentos anteriores en previous, emparejados por step_key; un paso nuevo o editado lleva new_or_changed. Un recuento de al menos el doble o como máximo la mitad del anterior, con 10 filas o más de diferencia, aparece en swings y añade un aviso CHANGE_COUNT_SWING a warnings. Nunca hace fallar la ejecución. Excel: pestaña Changes al final; CSV, JSON y XML: tu archivo tal cual, sin .zip.
Una ejecución de una plantilla con división en archivos que escribe dos o más partes devuelve un application/zip llamado <nombre>.zip con un archivo por parte; con una sola, devuelve ese archivo. output.split_parts cuenta los archivos, null sin división. Una división en más de 100 partes hace fallar la ejecución con FILE_SPLIT_TOO_MANY_PARTSy no escribe ningún archivo.
Una plantilla con pasos de fecha no necesita ningún parámetro extra. En un paso Tiempo entre fechas, un inicio o un fin vacío se lee como la fecha UTC en que se creó la ejecución, así que repetir la misma petición cuenta hasta el mismo día. En un paso Parte de fecha, los nombres de mes y de día de la semana salen en el name_language propio del paso.
Enviar un archivo de unión
Una plantilla con un paso de unión sobre un archivo que se envía con cada ejecución necesita ese archivo en la solicitud. Envíalo como una parte file más: no hay un nombre de campo que elegir ni un orden que respetar. La ejecución asigna cada parte al archivo principal o a un archivo de unión según el ajuste de su encabezado, así que las partes pueden llegar en cualquier orden:
curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-F "file=@/path/to/orders.csv" \
-F "file=@/path/to/catalog.csv"- Un archivo de unión que no se envió: JOIN_FILE_MISSING. Una parte a la que le faltan columnas que el paso necesita, incluido un archivo principal enviado donde va un archivo de unión: JOIN_FILE_COLUMNS_MISSING.
- Dos partes que encajan igual de bien con el mismo archivo y no se pueden distinguir: RUN_FILES_AMBIGUOUS.
- Una plantilla que une una tabla de referencia guardada que ya no existe, también si fue eliminada: REFERENCE_TABLE_NOT_FOUND, con el nombre de la tabla en el mensaje. Una columna que el paso lee y que la tabla ya no tiene: REFERENCE_TABLE_COLUMN_MISSING.
Una ejecución que termina bien puede llevar avisos de unión en warnings: JOIN_UNMATCHED_ROWS cuando filas no encontraron pareja, JOIN_REPEATED_KEYS cuando la tabla repite una clave y se usa su primera fila, JOIN_CLOSE_MATCHES cuando filas se emparejaron con una grafía parecida y JOIN_CLOSE_MATCH_LIMIT cuando la búsqueda de grafías parecidas se detuvo en su límite. Cada uno lleva recuentos. Los pocos valores de ejemplo vienen solo en la respuesta 201 que inició la ejecución: GET /runs/{id} y una repetición con la misma Idempotency-Key responden "sample": null con los recuentos solamente.
La ejecución también lista reference_tables: id, nombre, última modificación y número de filas de cada tabla leída, tal como estaban al empezar. Una tabla reemplazada mientras la ejecución sigue no la cambia.
Reintentar con Idempotency-Key
Envía una cabecera Idempotency-Key con la petición de crear. Un reintento de red de la misma petición devuelve la ejecución ya iniciada para esa clave, en lugar de iniciar, y cobrar, una segunda:
curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-H "Idempotency-Key: 3f2b9c1e-7a54-4d0e-9b61-0c8d5e2a41f7" \
-F "file=@/path/to/your/file.csv"Reutilizar una clave con una petición distinta responde IDEMPOTENCY_KEY_REUSED. Una ejecución que termina como RUN_INTERRUPTED o RUN_TIMEOUT, o cuyo id responde RUN_NOT_FOUND, se puede reenviar con la misma clave.