DocTransform

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.csv

Quand 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 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é.