Läufe
Wie ein Lauf der öffentlichen API erstellt, abgefragt, wiederholt und idempotent behandelt wird.
Ein Lauf wendet eine Vorlage auf eine hochgeladene Datei an, serverseitig, und liefert das Ergebnis zurück.
Schnelle Läufe antworten sofort
POST /templates/{id}/runs wartet bis zu 30 Sekunden, bis der Lauf fertig ist. Ist er rechtzeitig fertig, bekommst du 201 mit dem fertigen Lauf — sein Ergebnis ist bereits zum Herunterladen bereit.
Langsamere Läufe: 202 und abfragen
Nach 30 Sekunden bekommst du 202, einen Location-Header, der auf den Lauf zeigt, und einen Retry-After-Header, der sagt, wie lange du warten sollst, bevor du GET /runs/{id} erneut abfragst.
Overrides
Ein CSV-Upload kann delimiter und header_row zusammen mit file senden und damit die erkannten Standardwerte nur für diesen Lauf überschreiben.
curl -X POST "https://doctransform.xyz/api/v1/templates/tmpl_123/runs" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-F "file=@/pfad/zu/deiner/datei.csv" \
-F "delimiter=;" \
-F "header_row=0"Wenn eine Datei nicht laufen kann
Fehlt der hochgeladenen Datei eine Spalte, die die Operationen der Vorlage brauchen, wird die Anfrage selbst mit 422 TEMPLATE_COLUMNS_MISSING abgelehnt — nicht als ein fertiger, aber fehlgeschlagener Lauf zum Abfragen.
Das Ergebnis herunterladen
Das Ergebnis eines fertigen Laufs bleibt 30 Minuten nach Abschluss herunterladbar, von jedem Worker aus. Danach, oder sobald es abgelaufen ist, antwortet GET /runs/{id}/output mit 404 RUN_NOT_FOUND.
Sicher wiederholen: Idempotency-Key
Sende einen Idempotency-Key-Header mit POST /templates/{id}/runs, und ein Netzwerk-Wiederholungsversuch derselben Anfrage spielt den für diesen Schlüssel bereits gestarteten oder fertigen Lauf ab, statt einen zweiten zu starten (und zu berechnen). Denselben Schlüssel mit einer anderen Anfrage wiederzuverwenden antwortet 409 IDEMPOTENCY_KEY_REUSED.
RUN_NOT_FOUND, RUN_INTERRUPTED, RUN_TIMEOUT → erneut senden
Ein Lauf, dessen Worker vor dem Abschluss neu gestartet ist, endet als RUN_INTERRUPTED; einer, der nach 10 Minuten noch läuft, endet als RUN_TIMEOUT; einer, dessen id unbekannt ist oder abgelaufen ist, antwortet mit RUN_NOT_FOUND. Sende in jedem Fall erneut mit demselben Idempotency-Key, um es erneut zu versuchen.
Siehe Fehler und Limits für jeden Statuscode, mit dem ein Lauf antworten kann.