Esecuzioni
Come si crea un'esecuzione, come sai che è terminata e come ritentarla senza addebitarla due volte.
Risposta immediata o 202
POST /templates/{id}/runs aspetta fino a 30 secondi che l’esecuzione finisca. Se finisce, ricevi 201 con l’esecuzione terminata e il suo output pronto da scaricare. Oltre i 30 secondi ricevi 202, un’intestazione Location che punta all’esecuzione e un’intestazione Retry-After che dice quanto attendere prima di interrogare.
Un caricamento CSV può inviare delimiter e header_row insieme a file, sostituendo i valori rilevati solo per quell’esecuzione:
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"Se una colonna è stata rinominata, l’esecuzione risponde TEMPLATE_COLUMNS_MISSING con missing_columns: ogni colonna letta dal modello, con le colonne del file tra cui scegliere. Non viene addebitato nulla. Riprova con column_mapping, un oggetto JSON {"colonna del file": "colonna del modello"}, solo per quell’esecuzione; non viene mai salvato. Una colonna che differisce solo per maiuscole, spazi o trattini bassi viene abbinata da sola e segnalata come avviso COLUMN_MATCHED.
Controllare lo stato
GET /runs/{id} risponde con l’esecuzione e il suo stato: running, succeeded o failed. Interrogala, aspettando quanto indica Retry-After, finché non si stabilizza. Ogni campo è nel Riferimento API. Invece di interrogare, aggiungi un webhook: DocTransform ti avvisa quando un’esecuzione finisce.
curl "https://doctransform.xyz/api/v1/runs/run_abc" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY"Scaricare il risultato
GET /runs/{id}/output scarica il file. L’output di un’esecuzione terminata resta disponibile 30 minuti, oppure 3 giorni quando un webhook riceve l’esecuzione; dopo, o per un id sconosciuto, risponde RUN_NOT_FOUND.
curl "https://doctransform.xyz/api/v1/runs/run_abc/output" \
-H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
-o result.csvQuando un file non può essere eseguito
Un’esecuzione non ha alcun dataset in corso: ogni file di cui ha bisogno arriva con la richiesta. Una richiesta che non può essere eseguita viene rifiutata subito, mai un’esecuzione fallita da interrogare.
- Un file a cui manca una colonna necessaria al modello: TEMPLATE_COLUMNS_MISSING.
- Più parti
filea un modello senza passaggio Append: TEMPLATE_TAKES_ONE_FILE. Più parti di quante ne consenta il tuo piano: FILE_COUNT_LIMIT_EXCEEDED. - Un file che è l’output stesso di questo modello: TEMPLATE_OUTPUT_AS_SOURCE. Non viene addebitato nulla.
- Un’esecuzione riuscita può comunque portare un elenco
warnings, con una voce APPEND_LOCALE_DISAGREEMENT per ogni parte i cui numeri si leggono diversamente con i propri separatori. Nulla viene convertito. - Un modello con foglio Summary aggiunge un avviso quando il foglio non può essere scritto perché il modello non è Excel: SUMMARY_SHEET_NOT_WRITTEN. Ne aggiunge un altro quando il foglio ha quasi tante righe quanto i dati: SUMMARY_SHEET_ONE_GROUP_PER_ROW. Un foglio Summary che non può essere costruito fa fallire l’esecuzione con SUMMARY_SHEET_BROKEN. Quella esecuzione fallita non viene addebitata.
Un modello che indica il sistema a cui carica aggiunge all’esecuzione riuscita un destination_check: passed, rows_checked, rows_failing e una voce di reasons per ogni regola che fallisce, con il suo rule_id, l’intestazione field, outcome, count e un message fisso. Contiene solo conteggi, mai un valore del tuo file. Un controllo che fallisce non fa fallire l’esecuzione: stato, codice di stato e addebito sono quelli di ogni esecuzione riuscita, quindi uno script può decidere su passed prima di caricare. Vale null se il modello non indica alcun sistema e finché l’esecuzione non riesce.
Un’esecuzione riuscita restituisce anche, accanto all’output, un file o lo ZIP delle parti, un change_report: lines in inglese con le righe modificate per colonna e i conteggi in steps. Solo conteggi e intestazioni, mai un valore del tuo file. null finché l’esecuzione non riesce.
Ogni esecuzione riuscita conserva i suoi conteggi sul modello. Alla successiva, ogni passaggio del change_report porta i conteggi precedenti in previous, abbinati da step_key; un passaggio nuovo o modificato ha new_or_changed. Un conteggio almeno doppio o al massimo la metà del precedente, con 10 righe o più di scarto, compare in swings e aggiunge un avviso CHANGE_COUNT_SWING a warnings. Non fa mai fallire l’esecuzione. Un’esecuzione Excel ottiene una scheda Changes finale; una CSV, JSON o XML restituisce il tuo file così com’è, senza lo .zip dell’app, a meno che il modello abbia una divisione in file.
Un modello con divisione in file scrive il suo output in parti. Un’esecuzione che ne scrive due o più restituisce un application/zip chiamato <nome>.zip con un file per parte; se ne scrive una sola, restituisce quel file così com’è. output.split_parts conta i file, null senza divisione. Una divisione in più di 100 parti fa fallire l’esecuzione con FILE_SPLIT_TOO_MANY_PARTSe non scrive alcun file.
Un modello con passaggi di data non richiede alcun parametro in più. In un passaggio Tempo tra date, un inizio o una fine vuota si legge come la data UTC in cui è stata creata l’esecuzione, così rieseguire la stessa richiesta conta fino allo stesso giorno. In un passaggio Parte di data, i nomi di mese e giorno della settimana escono nel name_language proprio del passaggio.
Inviare un file di unione
Un modello con un passaggio di unione su un file inviato a ogni esecuzione ha bisogno di quel file nella richiesta. Invialo come una parte file in più: non c’è un nome di campo da scegliere né un ordine da rispettare. L’esecuzione assegna ogni parte al file principale o a un file di unione in base a quanto combacia la sua intestazione, quindi le parti possono arrivare in qualsiasi ordine:
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 file di unione non inviato: JOIN_FILE_MISSING. Una parte a cui mancano colonne che il passaggio richiede, compreso un file principale inviato dove va un file di unione: JOIN_FILE_COLUMNS_MISSING.
- Due parti che combaciano ugualmente bene con lo stesso file e non si distinguono: RUN_FILES_AMBIGUOUS.
- Un modello che unisce una tabella di riferimento salvata che non esiste più, anche se eliminata: REFERENCE_TABLE_NOT_FOUND, con il nome della tabella nel messaggio. Una colonna che il passaggio legge e che la tabella non ha più: REFERENCE_TABLE_COLUMN_MISSING.
Un’esecuzione riuscita può portare avvisi di unione in warnings: JOIN_UNMATCHED_ROWS quando righe non hanno trovato corrispondenza, JOIN_REPEATED_KEYS quando la tabella ripete una chiave e si usa la sua prima riga, JOIN_CLOSE_MATCHES quando righe sono state abbinate a una scrittura simile e JOIN_CLOSE_MATCH_LIMIT quando la ricerca di scritture simili si è fermata al suo limite. Ognuno porta dei conteggi. I pochi valori di esempio sono solo nella risposta 201 che ha avviato l’esecuzione: GET /runs/{id} e una ripetizione con la stessa Idempotency-Key rispondono "sample": null con i soli conteggi.
L’esecuzione elenca anche reference_tables: id, nome, ultima modifica e numero di righe di ogni tabella letta, com’erano all’avvio. Una tabella sostituita mentre l’esecuzione è in corso non la modifica.
Riprovare con Idempotency-Key
Invia un’intestazione Idempotency-Key con la richiesta di creazione. Un nuovo tentativo di rete della stessa richiesta restituisce l’esecuzione già avviata per quella chiave, invece di avviarne, e addebitarne, una seconda:
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"Riusare una chiave con una richiesta diversa risponde IDEMPOTENCY_KEY_REUSED. Un’esecuzione che si chiude come RUN_INTERRUPTED o RUN_TIMEOUT, o il cui id risponde RUN_NOT_FOUND, può essere reinviata con la stessa chiave.