DocTransform

Läufe

Wie ein Lauf erstellt wird, woran du erkennst, dass er fertig ist, und wie du ihn wiederholst, ohne doppelt zu zahlen.

Sofortige Antwort oder 202

POST /templates/{id}/runs wartet bis zu 30 Sekunden, bis der Lauf fertig ist. Wird er fertig, erhältst du 201 mit dem fertigen Lauf, und seine Ausgabe ist bereit zum Download. Nach 30 Sekunden erhältst du 202, einen Location-Header, der auf den Lauf zeigt, und einen Retry-After-Header, der sagt, wie lange du vor der Abfrage wartest.

Ein CSV-Upload kann delimiter und header_row neben file senden und überschreibt die erkannten Standardwerte nur für diesen Lauf:

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"

Wurde eine Spalte umbenannt, antwortet der Lauf mit TEMPLATE_COLUMNS_MISSING und missing_columns: jede Spalte, die die Vorlage liest, mit den Spalten der Datei zur Auswahl. Es wird nichts berechnet. Versuche es erneut mit column_mapping, einem JSON-Objekt {"Dateispalte": "Vorlagenspalte"}, nur für diesen einen Lauf; es wird nie gespeichert. Eine Spalte, die sich nur in Groß-/Kleinschreibung, Leerzeichen oder Unterstrichen unterscheidet, wird selbst zugeordnet und als Warnung COLUMN_MATCHED gemeldet.

Status abfragen

GET /runs/{id} antwortet mit dem Lauf und seinem Status: running, succeeded oder failed. Frage ihn ab und warte so lange, wie Retry-After angibt, bis er feststeht. Jedes Feld steht in der API-Referenz. Statt abzufragen, kannst du einen Webhook anlegen: DocTransform sagt dir, wenn ein Lauf fertig ist.

curl "https://doctransform.xyz/api/v1/runs/run_abc" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"

Ergebnis herunterladen

GET /runs/{id}/output lädt die Datei herunter. Die Ausgabe eines fertigen Laufs bleibt 30 Minuten verfügbar, oder 3 Tage, wenn ein Webhook den Lauf erhält; danach, oder bei einer unbekannten ID, antwortet er RUN_NOT_FOUND.

curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -o result.csv

Wenn eine Datei nicht laufen kann

Ein Lauf hat keinen laufenden Datensatz: Jede Datei, die er braucht, kommt mit der Anfrage. Eine Anfrage, die nicht laufen kann, wird sofort abgelehnt, nie als fehlgeschlagener Lauf zum Abfragen.

Nennt eine Vorlage das System, in das sie hochlädt, trägt der Lauf nach dem Erfolg ein destination_check: passed, rows_checked, rows_failing und je fehlschlagender Regel einen Eintrag in reasons mit rule_id, der Kopfzeile field, outcome, count und einer festen message. Es enthält nur Zahlen, nie einen Wert aus Ihrer Datei. Eine fehlgeschlagene Prüfung lässt den Lauf nicht scheitern: Status, Statuscode und Abrechnung sind die jedes erfolgreichen Laufs, ein Skript kann also vor dem Hochladen auf passed verzweigen. Es ist null, wenn die Vorlage kein System nennt und bis der Lauf erfolgreich ist.

Ein erfolgreicher Lauf liefert neben der Ausgabe, einer Datei oder dem ZIP der Teildateien, auch einen change_report: englische lines mit den geänderten Zeilen pro Spalte und die Zahlen in steps. Nur Zahlen und Kopfzeilen, nie ein Wert aus Ihrer Datei. null, bis der Lauf erfolgreich ist.

Jeder erfolgreiche Lauf speichert seine Zahlen an der Vorlage. Beim nächsten Lauf trägt jeder Schritt des change_report die letzten Zahlen in previous, zugeordnet über step_key; ein neuer oder geänderter Schritt hat stattdessen new_or_changed. Eine Zahl, die mindestens das Doppelte oder höchstens die Hälfte der letzten beträgt und mindestens 10 Zeilen abweicht, steht in swings und fügt warnings eine Warnung CHANGE_COUNT_SWING hinzu. Sie lässt einen Lauf nie scheitern. Ein Excel-Lauf erhält ein letztes Blatt Changes; ein CSV-, JSON- oder XML-Lauf liefert deine Datei unverändert, nicht gezippt wie die .zip der App, außer die Vorlage hat eine Dateiaufteilung.

Eine Vorlage mit Dateiaufteilung schreibt ihre Ausgabe als Teildateien. Ein Lauf, der zwei oder mehr schreibt, liefert ein application/zip mit dem Namen <name>.zip und einer Datei pro Teil; schreibt er nur einen Teil, kommt diese Datei einfach zurück. output.split_parts zählt die Dateien, null ohne Dateiaufteilung. Eine Aufteilung in mehr als 100 Teile lässt den Lauf mit FILE_SPLIT_TOO_MANY_PARTSscheitern, ohne Datei.

Eine Vorlage mit Datumsschritten braucht keinen zusätzlichen Parameter. In einem Schritt Zeit zwischen Daten gilt: ein leerer Start oder ein leeres Ende wird als das UTC-Datum gelesen, an dem der Lauf erstellt wurde; eine Wiederholung derselben Anfrage zählt also bis zum selben Tag. In einem Schritt Datumsteil gilt: Monats- und Wochentagsnamen erscheinen in der eigenen name_language des Schritts.

Eine Verbindungsdatei senden

Eine Vorlage mit einem Verbindungsschritt auf einer Datei, die bei jedem Lauf mitgeschickt wird, braucht diese Datei in der Anfrage. Sende sie als einen weiteren file-Teil: Es gibt keinen Feldnamen zu wählen und keine Reihenfolge einzuhalten. Der Lauf ordnet jeden Teil anhand der Passung seiner Kopfzeile der Hauptdatei oder einer Verbindungsdatei zu, die Teile können also in beliebiger Reihenfolge kommen:

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"
  • Eine Verbindungsdatei, die nicht gesendet wurde: JOIN_FILE_MISSING. Ein Teil, dem Spalten fehlen, die der Schritt braucht, auch eine Hauptdatei, die dort gesendet wurde, wo eine Verbindungsdatei hingehört: JOIN_FILE_COLUMNS_MISSING.
  • Zwei Teile, die gleich gut zur selben Datei passen und sich nicht unterscheiden lassen: RUN_FILES_AMBIGUOUS.
  • Eine Vorlage, die eine gespeicherte Referenztabelle verbindet, die es nicht mehr gibt, auch eine gelöschte: REFERENCE_TABLE_NOT_FOUND, mit dem Namen der Tabelle in der Meldung. Eine Spalte, die der Schritt liest und die die Tabelle nicht mehr hat: REFERENCE_TABLE_COLUMN_MISSING.

Ein Lauf, der gelingt, kann Verbindungseinträge in warnings tragen: JOIN_UNMATCHED_ROWS, wenn Zeilen keinen Treffer fanden, JOIN_REPEATED_KEYS, wenn die Tabelle einen Schlüssel wiederholt und jeweils die erste Zeile gilt, JOIN_CLOSE_MATCHES, wenn Zeilen einer ähnlichen Schreibweise zugeordnet wurden, und JOIN_CLOSE_MATCH_LIMIT, wenn das ähnliche Zuordnen an sein Limit kam. Jeder trägt Zahlen. Die wenigen Beispielwerte stehen nur in der 201-Antwort, die den Lauf gestartet hat: GET /runs/{id} und eine Wiederholung mit demselben Idempotency-Key antworten mit "sample": null und nur den Zahlen.

Der Lauf listet außerdem reference_tables: ID, Name, letzte Änderung und Zeilenzahl jeder gelesenen Tabelle, so wie sie beim Start waren. Eine Tabelle, die während des Laufs ersetzt wird, ändert ihn nicht.

Wiederholen mit Idempotency-Key

Sende einen Idempotency-Key-Header mit der Erstellungsanfrage. Eine Netzwerkwiederholung derselben Anfrage gibt den für diesen Schlüssel bereits gestarteten Lauf wieder, statt einen zweiten zu starten und zu berechnen:

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"

Wird ein Schlüssel mit einer anderen Anfrage wiederverwendet, antwortet IDEMPOTENCY_KEY_REUSED. Ein Lauf, der als RUN_INTERRUPTED oder RUN_TIMEOUT endet oder dessen ID RUN_NOT_FOUND antwortet, kann mit demselben Schlüssel erneut gesendet werden.