DocTransform

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

Quando 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 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’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.