Exécutions
Comment une exécution est créée, comment savoir qu'elle est terminée et comment la relancer sans la facturer deux fois.
Réponse immédiate ou 202
POST /templates/{id}/runs attend jusqu’à 30 secondes que l’exécution se termine. Si elle se termine, vous recevez 201 avec l’exécution terminée et sa sortie prête à télécharger. Au-delà de 30 secondes, vous recevez 202, un en-tête Location qui pointe vers l’exécution et un en-tête Retry-After qui indique combien attendre avant d’interroger.
Un envoi CSV peut transmettre delimiter et header_row avec file, et remplace les valeurs détectées pour cette seule exécution :
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 une colonne a été renommée, l’exécution répond TEMPLATE_COLUMNS_MISSING avec missing_columns : chaque colonne que lit le modèle, avec les colonnes du fichier à choisir. Rien n’est facturé. Réessaie avec column_mapping, un objet JSON {"colonne du fichier": "colonne du modèle"}, pour cette seule exécution ; il n’est jamais enregistré. Une colonne qui ne diffère que par la casse, les espaces ou les tirets bas est associée toute seule et signalée par un avertissement COLUMN_MATCHED.
Consulter le statut
GET /runs/{id} répond avec l’exécution et son statut : running, succeeded ou failed. Interrogez-la en attendant ce que dit Retry-After, jusqu’à ce qu’elle se fixe. Chaque champ est dans la Référence de l’API. Au lieu d’interroger, ajoutez un webhook : DocTransform vous prévient quand une exécution se termine.
curl "https://doctransform.xyz/api/v1/runs/run_abc" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY"Télécharger le résultat
GET /runs/{id}/output télécharge le fichier. La sortie d’une exécution terminée reste disponible 30 minutes, ou 3 jours quand un webhook reçoit l’exécution ; ensuite, ou pour un id inconnu, il répond RUN_NOT_FOUND.
curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-o result.csvQuand un fichier ne peut pas s’exécuter
Une exécution n’a pas de jeu de données en cours : chaque fichier dont elle a besoin arrive avec la requête. Une requête qui ne peut pas s’exécuter est refusée d’emblée, jamais une exécution échouée à interroger.
- Un fichier auquel manque une colonne dont le modèle a besoin : TEMPLATE_COLUMNS_MISSING.
- Plusieurs parties
filevers un modèle sans étape Append : TEMPLATE_TAKES_ONE_FILE. Plus de parties que votre forfait n’en permet : FILE_COUNT_LIMIT_EXCEEDED. - Un fichier qui est la propre sortie de ce modèle : TEMPLATE_OUTPUT_AS_SOURCE. Rien n’est facturé.
- Une exécution réussie peut quand même porter une liste
warnings, avec une entrée APPEND_LOCALE_DISAGREEMENT par partie dont les nombres se lisent autrement avec ses propres séparateurs. Rien n’est converti. - Un modèle avec une feuille Summary ajoute un avertissement quand elle ne peut pas être écrite car le modèle n’est pas Excel : SUMMARY_SHEET_NOT_WRITTEN. Il en ajoute un autre quand elle a presque autant de lignes que les données : SUMMARY_SHEET_ONE_GROUP_PER_ROW. Une feuille Summary impossible à construire fait échouer l’exécution avec SUMMARY_SHEET_BROKEN. Ce Run reste gratuit.
Un modèle qui nomme le système où il charge ajoute à l’exécution réussie un destination_check : passed, rows_checked, rows_failing et une entrée de reasons par règle en échec, avec son rule_id, l’en-tête field, outcome, count et un message fixe. Il ne contient que des nombres, jamais une valeur de votre fichier. Un contrôle en échec ne fait pas échouer l’exécution : le statut, le code de statut et la facturation sont ceux de toute exécution réussie, un script peut donc se brancher sur passed avant de charger. Il vaut null quand le modèle ne nomme aucun système et tant que l’exécution n’a pas réussi.
Une exécution réussie renvoie un fichier ou le ZIP des parties et un change_report : des lines en anglais et les nombres dans steps. Nombres et en-têtes seulement. null avant le premier succès.
Chaque exécution réussie garde ses nombres ; ensuite, chaque étape du change_report porte les anciens nombres dans previous, ou new_or_changed si elle est nouvelle. Un nombre au moins double ou moitié de l’ancien, et d’au moins 10 lignes d’écart, figure dans swings et ajoute un avertissement CHANGE_COUNT_SWING à warnings, sans la faire échouer. Excel : onglet Changes ; CSV, JSON, XML : votre fichier, sans .zip.
Une exécution d’un modèle avec division en fichiers qui écrit deux parties ou plus renvoie un application/zip nommé <nom>.zip, un par partie ; pour une seule, ce fichier. output.split_parts compte les fichiers, null sans division. Une division en plus de 100 parties fait échouer l’exécution avec FILE_SPLIT_TOO_MANY_PARTSet n’écrit aucun fichier.
Un modèle avec des étapes de date n’a besoin d’aucun paramètre en plus. Dans une étape Temps entre deux dates, un début ou une fin vide se lit comme la date UTC de création de l’exécution, donc rejouer la même requête compte jusqu’au même jour. Dans une étape Partie de date, les noms de mois et de jour de la semaine sortent dans le name_language propre à l’étape.
Envoyer un fichier de jonction
Un modèle avec une étape de jonction sur un fichier envoyé à chaque exécution a besoin de ce fichier dans la requête. Envoyez-le comme une partie file de plus : il n’y a pas de nom de champ à choisir ni d’ordre à respecter. L’exécution associe chaque partie au fichier principal ou à un fichier de jonction selon l’adéquation de son en-tête, donc les parties peuvent arriver dans n’importe quel ordre :
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 fichier de jonction qui n’a pas été envoyé : JOIN_FILE_MISSING. Une partie à laquelle il manque des colonnes dont l’étape a besoin, y compris un fichier principal envoyé là où va un fichier de jonction : JOIN_FILE_COLUMNS_MISSING.
- Deux parties qui correspondent aussi bien au même fichier et qu’on ne peut pas distinguer : RUN_FILES_AMBIGUOUS.
- Un modèle qui joint une table de référence enregistrée qui n’existe plus, supprimée comprise : REFERENCE_TABLE_NOT_FOUND, avec le nom de la table dans le message. Une colonne que l’étape lit et que la table n’a plus : REFERENCE_TABLE_COLUMN_MISSING.
Une exécution réussie peut porter des entrées de jonction dans warnings : JOIN_UNMATCHED_ROWS quand des lignes n’ont pas trouvé de correspondance, JOIN_REPEATED_KEYS quand la table répète une clé et que sa première ligne est utilisée, JOIN_CLOSE_MATCHES quand des lignes ont été associées à une orthographe proche et JOIN_CLOSE_MATCH_LIMIT quand la recherche d’orthographes proches s’est arrêtée à sa limite. Chacune porte des comptes. Les quelques valeurs d’exemple ne figurent que dans la réponse 201 qui a lancé l’exécution : GET /runs/{id} et un rejeu avec la même Idempotency-Key répondent "sample": null avec les seuls comptes.
L’exécution liste aussi reference_tables : l’id, le nom, la dernière modification et le nombre de lignes de chaque table lue, tels qu’ils étaient au démarrage. Une table remplacée pendant l’exécution ne la modifie pas.
Relancer avec Idempotency-Key
Envoyez un en-tête Idempotency-Key avec la requête de création. Une nouvelle tentative réseau de la même requête renvoie l’exécution déjà lancée pour cette clé, au lieu d’en lancer, et d’en facturer, une seconde :
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"Réutiliser une clé avec une requête différente répond IDEMPOTENCY_KEY_REUSED. Une exécution qui se termine en RUN_INTERRUPTED ou RUN_TIMEOUT, ou dont l’id répond RUN_NOT_FOUND, peut être renvoyée avec la même clé.