DocTransform

Riferimento API

Ogni endpoint dell'API pubblica, con la sua richiesta e una risposta di esempio.

URL di base
https://doctransform.xyz/api/v1
Autenticazione
Authorization: Bearer · Come ottenere una chiave API
Versionamento
Una sola versione, nell'URL di base. Ciò che ritiriamo continua a funzionare per almeno 12 mesi dopo averlo contrassegnato con le intestazioni Deprecation e Sunset.
Risposte
Ignora qualsiasi campo che non riconosci: aggiungiamo campi senza preavviso.
OpenAPI 3.1
· doctransform.xyz/api/v1/openapi.json

Modelli

Elencare i modelli

GET/templates

Restituisce i modelli del tuo account. Usa l'id di un modello per creare un'esecuzione.

Permesso templates:read

GET/templates
curl "https://doctransform.xyz/api/v1/templates" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Risposta200
{
  "data": [
    {
      "description": "Cleans the billing export and keeps the paid invoices.",
      "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "name": "Monthly invoices",
      "output_format": "csv"
    }
  ]
}

L'oggetto Template

Un modello salvato che un'esecuzione può applicare.

Esempio
{
  "description": "Cleans the billing export and keeps the paid invoices.",
  "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
  "name": "Monthly invoices",
  "output_format": "csv"
}

Attributi

  • descriptionstringfacoltativopuò essere nullo

    What the Template does, when its owner wrote one.

  • idstringobbligatorio

    The Template's id; send it to create a Run.

  • namestringfacoltativopuò essere nullo

    The name the Template was saved under.

  • output_formatstringfacoltativopuò essere nullo

    The file format a Run of this Template writes. A Template's Summary sheet is written only when this is xlsx.

Esecuzioni

Creare un'esecuzione

POST/templates/{template_id}/runs

Esegue un modello su un file, più un file per ogni file di unione che il modello legge, assegnati per intestazione, non per ordine. Risponde 201 con l'esecuzione terminata se finisce in circa 30 secondi, altrimenti 202 mentre prosegue. Invia una Idempotency-Key e un nuovo tentativo non viene mai addebitato due volte. Un’esecuzione completata consuma un’esportazione della tua quota mensile; una rifiutata, fallita o riproposta non ne consuma nessuna.

Permesso runs:write

POST/templates/{template_id}/runs
curl -X POST "https://doctransform.xyz/api/v1/templates/{template_id}/runs" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -F "file=@/path/to/your/file.csv"
Risposta201
{
  "change_report": {
    "columns_in": 3,
    "columns_out": 3,
    "lines": [
      "Step 1 · Mark as empty: Emptied 212 rows in Phone."
    ],
    "previous": null,
    "previous_counted_at": "2026-03-02T09:15:00Z",
    "rows_in": 4,
    "rows_out": 4,
    "steps": [
      {
        "columns": [
          "Phone"
        ],
        "columns_added": [
          "Phone"
        ],
        "columns_removed": [
          "Phone"
        ],
        "counted": true,
        "kind": "mark_empty",
        "made_columns": null,
        "new_or_changed": false,
        "number": 1,
        "previous": {
          "rows_after": 1204,
          "rows_before": 1204,
          "rows_changed": [
            {
              "column": "Phone",
              "rows": 200
            }
          ],
          "unread_rows": null
        },
        "rows_after": 1204,
        "rows_before": 1204,
        "rows_changed": [
          {
            "column": "Phone",
            "rows": 212
          }
        ],
        "step_key": "3f2a9c01b7d4e856-1",
        "swings": [
          {
            "column": "Phone",
            "count": 40,
            "count_name": "rows_changed",
            "previous": 12
          }
        ],
        "title": "Mark as empty",
        "unread_columns": [
          "Phone"
        ],
        "unread_rows": null
      }
    ]
  },
  "completed_at": "2026-10-07T14:02:19Z",
  "created_at": "2026-10-07T14:02:11Z",
  "destination_check": {
    "destination_id": "hubspot_contacts",
    "passed": false,
    "reasons": [
      {
        "count": 12,
        "field": "Email",
        "message": "The email address is incomplete.",
        "outcome": "rejected",
        "rule_id": "email_format"
      }
    ],
    "rows_checked": 1204,
    "rows_failing": 12
  },
  "error": null,
  "expires_at": "2026-10-07T14:32:19Z",
  "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
  "output": {
    "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
    "mime_type": "text/csv",
    "name": "invoices.csv",
    "size_bytes": 48213,
    "split_parts": 12
  },
  "reference_tables": [
    {
      "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
      "name": "Product catalog",
      "rows": 1204,
      "updated_at": "2026-10-07T13:58:40+00:00"
    }
  ],
  "rows_written": 1204,
  "status": "succeeded",
  "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
  "truncated": false,
  "warnings": [
    {
      "code": "APPEND_LOCALE_DISAGREEMENT",
      "column": "Invoice total",
      "count": 12,
      "expected_source_file": "January",
      "message": "12 values in this part read differently from the first file.",
      "part": 2,
      "step": 2,
      "output_rows": 500,
      "summary_rows": 480,
      "file_column": "invoice_total",
      "how": "normalised",
      "sample": [
        [
          "SKU-1042"
        ]
      ],
      "rows": 12,
      "values": 3,
      "checked": 4000,
      "left": 250,
      "count_name": "rows_changed",
      "previous": 12
    }
  ]
}

Parametri di percorso

  • template_idstringobbligatorio

    The id of the Template to run.

Intestazioni

  • Idempotency-Keystringfacoltativo

    Replays the Run already started or finished for this key rather than starting a second one; a different request with the same key answers 409 IDEMPOTENCY_KEY_REUSED.

Corpo (multipart/form-data)

  • column_mappingstringfacoltativo

    For this Run only, never saved: a JSON object {file column: Template column} that settles a column the file renamed. Send it after a 422 TEMPLATE_COLUMNS_MISSING names the candidates. Ignored for a Template with an Append Step.

  • delimiterstringfacoltativo

    The one character that separates the columns of a delimited text file. The delimiter is detected when omitted.

  • filefileobbligatorio

    The file to run: .csv, .txt, .xls, .xlsx, .yaml, .yml, .json, within your plan's size and row limits. Send the part once, or repeat it to append several files, in order, when the Template has an Append Step. When the Template has a Join Step on a file sent with each Run, send one more part for each Join File: parts are matched to the main file and to each Join File by header fit, not by order. A Run has no running Dataset: every file comes in the request.

  • header_rowintegerfacoltativo

    Which row holds the column names, 0-based. The header is detected when omitted.

Restituisce Un oggetto Run

Errori (33)

Vedi tutti i codici di errore e i limiti

Consultare un'esecuzione

GET/runs/{run_id}

Restituisce lo stato di un'esecuzione. Interroga finché non è succeeded o failed.

Permesso runs:read

GET/runs/{run_id}
curl "https://doctransform.xyz/api/v1/runs/{run_id}" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Risposta200
{
  "change_report": {
    "columns_in": 3,
    "columns_out": 3,
    "lines": [
      "Step 1 · Mark as empty: Emptied 212 rows in Phone."
    ],
    "previous": null,
    "previous_counted_at": "2026-03-02T09:15:00Z",
    "rows_in": 4,
    "rows_out": 4,
    "steps": [
      {
        "columns": [
          "Phone"
        ],
        "columns_added": [
          "Phone"
        ],
        "columns_removed": [
          "Phone"
        ],
        "counted": true,
        "kind": "mark_empty",
        "made_columns": null,
        "new_or_changed": false,
        "number": 1,
        "previous": {
          "rows_after": 1204,
          "rows_before": 1204,
          "rows_changed": [
            {
              "column": "Phone",
              "rows": 200
            }
          ],
          "unread_rows": null
        },
        "rows_after": 1204,
        "rows_before": 1204,
        "rows_changed": [
          {
            "column": "Phone",
            "rows": 212
          }
        ],
        "step_key": "3f2a9c01b7d4e856-1",
        "swings": [
          {
            "column": "Phone",
            "count": 40,
            "count_name": "rows_changed",
            "previous": 12
          }
        ],
        "title": "Mark as empty",
        "unread_columns": [
          "Phone"
        ],
        "unread_rows": null
      }
    ]
  },
  "completed_at": "2026-10-07T14:02:19Z",
  "created_at": "2026-10-07T14:02:11Z",
  "destination_check": {
    "destination_id": "hubspot_contacts",
    "passed": false,
    "reasons": [
      {
        "count": 12,
        "field": "Email",
        "message": "The email address is incomplete.",
        "outcome": "rejected",
        "rule_id": "email_format"
      }
    ],
    "rows_checked": 1204,
    "rows_failing": 12
  },
  "error": null,
  "expires_at": "2026-10-07T14:32:19Z",
  "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
  "output": {
    "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
    "mime_type": "text/csv",
    "name": "invoices.csv",
    "size_bytes": 48213,
    "split_parts": 12
  },
  "reference_tables": [
    {
      "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
      "name": "Product catalog",
      "rows": 1204,
      "updated_at": "2026-10-07T13:58:40+00:00"
    }
  ],
  "rows_written": 1204,
  "status": "succeeded",
  "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
  "truncated": false,
  "warnings": [
    {
      "code": "APPEND_LOCALE_DISAGREEMENT",
      "column": "Invoice total",
      "count": 12,
      "expected_source_file": "January",
      "message": "12 values in this part read differently from the first file.",
      "part": 2,
      "step": 2,
      "output_rows": 500,
      "summary_rows": 480,
      "file_column": "invoice_total",
      "how": "normalised",
      "sample": [
        [
          "SKU-1042"
        ]
      ],
      "rows": 12,
      "values": 3,
      "checked": 4000,
      "left": 250,
      "count_name": "rows_changed",
      "previous": 12
    }
  ]
}

Scaricare il risultato

GET/runs/{run_id}/output

Scarica il file prodotto da un'esecuzione terminata.

Permesso runs:read

GET/runs/{run_id}/output
curl -o output "https://doctransform.xyz/api/v1/runs/{run_id}/output" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Risposta200

File binario. Il Content-Type segue il formato di output del modello.

Parametri di percorso

  • run_idstringobbligatorio

    The id of the Run, as returned when it was created.

Restituisce Il file di output

Errori (11)

Vedi tutti i codici di errore e i limiti

Scaricare il risultato da un link

GET/runs/{run_id}/download

Scarica il file di un Run terminato da un link prefirmato. Nessuna chiave API necessaria: il link è pubblico per scelta e scade, quindi condividilo solo con chi deve avere il file.

GET/runs/{run_id}/download
curl -o output "https://doctransform.xyz/api/v1/runs/{run_id}/download"
Risposta200

File binario. Il Content-Type segue il formato di output del modello.

Parametri di percorso

  • run_idstringobbligatorio

    The id of the Run, as returned when it was created.

Restituisce Il file di output

Errori (7)

Vedi tutti i codici di errore e i limiti

L'oggetto Run

Un'esecuzione: il suo stato, i suoi orari e, quando c'è, il suo file di output.

Esempio
{
  "change_report": {
    "columns_in": 3,
    "columns_out": 3,
    "lines": [
      "Step 1 · Mark as empty: Emptied 212 rows in Phone."
    ],
    "previous": null,
    "previous_counted_at": "2026-03-02T09:15:00Z",
    "rows_in": 4,
    "rows_out": 4,
    "steps": [
      {
        "columns": [
          "Phone"
        ],
        "columns_added": [
          "Phone"
        ],
        "columns_removed": [
          "Phone"
        ],
        "counted": true,
        "kind": "mark_empty",
        "made_columns": null,
        "new_or_changed": false,
        "number": 1,
        "previous": {
          "rows_after": 1204,
          "rows_before": 1204,
          "rows_changed": [
            {
              "column": "Phone",
              "rows": 200
            }
          ],
          "unread_rows": null
        },
        "rows_after": 1204,
        "rows_before": 1204,
        "rows_changed": [
          {
            "column": "Phone",
            "rows": 212
          }
        ],
        "step_key": "3f2a9c01b7d4e856-1",
        "swings": [
          {
            "column": "Phone",
            "count": 40,
            "count_name": "rows_changed",
            "previous": 12
          }
        ],
        "title": "Mark as empty",
        "unread_columns": [
          "Phone"
        ],
        "unread_rows": null
      }
    ]
  },
  "completed_at": "2026-10-07T14:02:19Z",
  "created_at": "2026-10-07T14:02:11Z",
  "destination_check": {
    "destination_id": "hubspot_contacts",
    "passed": false,
    "reasons": [
      {
        "count": 12,
        "field": "Email",
        "message": "The email address is incomplete.",
        "outcome": "rejected",
        "rule_id": "email_format"
      }
    ],
    "rows_checked": 1204,
    "rows_failing": 12
  },
  "error": null,
  "expires_at": "2026-10-07T14:32:19Z",
  "id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
  "output": {
    "download_url": "/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/output",
    "mime_type": "text/csv",
    "name": "invoices.csv",
    "size_bytes": 48213,
    "split_parts": 12
  },
  "reference_tables": [
    {
      "id": "7d1c9a52-3b0e-4c57-8f21-6a94e0b5d3c8",
      "name": "Product catalog",
      "rows": 1204,
      "updated_at": "2026-10-07T13:58:40+00:00"
    }
  ],
  "rows_written": 1204,
  "status": "succeeded",
  "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
  "truncated": false,
  "warnings": [
    {
      "code": "APPEND_LOCALE_DISAGREEMENT",
      "column": "Invoice total",
      "count": 12,
      "expected_source_file": "January",
      "message": "12 values in this part read differently from the first file.",
      "part": 2,
      "step": 2,
      "output_rows": 500,
      "summary_rows": 480,
      "file_column": "invoice_total",
      "how": "normalised",
      "sample": [
        [
          "SKU-1042"
        ]
      ],
      "rows": 12,
      "values": 3,
      "checked": 4000,
      "left": 250,
      "count_name": "rows_changed",
      "previous": 12
    }
  ]
}

Attributi

  • change_reportobjectfacoltativopuò essere nullo

    What each step did to the file, in counts and English lines only: no cell and no value read from a row. Null until the Run succeeds.

  • completed_atstringdate-timefacoltativopuò essere nullo

    When the Run finished; null while it is running.

  • created_atstringdate-timeobbligatorio

    When the Run was accepted.

  • destination_checkobjectfacoltativopuò essere nullo

    Whether the output file passes the system the Template uploads to, counts only. Null when the Template names no system and until the Run succeeds.

  • errorobjectfacoltativopuò essere nullo

    Why the Run failed; null unless it did.

  • expires_atstringdate-timefacoltativopuò essere nullo

    30 minutes after the Run finished, or 3 days when a Webhook receives it; null while it is running.

  • idstringobbligatorio

    The Run's id, run_ followed by 32 hex digits.

  • outputobjectfacoltativopuò essere nullo

    The output file; null until the Run succeeds.

  • reference_tablesarrayfacoltativo

    The Reference Tables the Run's Join Steps read, as they were when the Run started: id, name, last change and row count. No cell.

  • rows_writtenintegerfacoltativopuò essere nullo

    Rows in the output file; null until the Run succeeds.

  • statusrunning | succeeded | failedobbligatorio

    Where the Run is now.

  • template_idstringobbligatorio

    The Template the Run applied.

  • truncatedbooleanfacoltativo

    True when the output was cut at the plan's row limit.

  • warningsarrayfacoltativo

    Warnings the Run succeeded despite; empty when there are none.

Eventi webhook

Ciò che riceve il tuo ricevitore quando un Run finisce. DocTransform invia ogni evento come POST con corpo JSON all'URL di un webhook aggiunto nel tuo account. Tutti gli eventi hanno la stessa forma, descritta alla fine di questo gruppo.

Guida ai webhook

Un Run è riuscito

POSTrun.succeeded

Inviato quando un Run finisce e il suo file di output è pronto. Il corpo contiene un link di download che non richiede chiave API fino alla scadenza.

Corpo inviato al tuo URL
{
  "type": "run.succeeded",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-30T10:15:00Z",
    "error": null
  }
}

Un Run è fallito

POSTrun.failed

Inviato quando un Run finisce senza file di output. Il corpo ne dice il motivo con un codice fisso e una frase semplice.

Corpo inviato al tuo URL
{
  "type": "run.failed",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "failed",
    "download_url": null,
    "expires_at": null,
    "error": {
      "code": "PIPELINE_FAILED",
      "message": "The pipeline failed while running the Template."
    }
  }
}

Un evento di prova

POSTwebhook.test

Inviato solo quando premi Invia evento di prova nel tuo account, per controllare il tuo ricevitore. Descrive un Run inventato e il suo link non funziona.

Corpo inviato al tuo URL
{
  "type": "webhook.test",
  "timestamp": "2026-09-27T10:15:00+00:00",
  "data": {
    "run_id": "run_test",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_test/download?expires=1790590500&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-28T10:15:00+00:00",
    "error": null
  }
}

Il corpo dell'evento

Ciò che porta ogni evento webhook: cosa è successo, quando e i dettagli del Run. Mai una riga, una cella o un nome di file.

Esempio
{
  "type": "run.succeeded",
  "timestamp": "2026-09-27T10:15:00Z",
  "data": {
    "run_id": "run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58",
    "template_id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
    "status": "succeeded",
    "download_url": "https://doctransform.xyz/api/v1/runs/run_3f9a1c7e5b2d4e8a9c0b6d1f7e2a4c58/download?expires=1790763300&signature=0000000000000000000000000000000000000000000000000000000000000000",
    "expires_at": "2026-09-30T10:15:00Z",
    "error": null
  }
}

Attributi

  • dataobjectobbligatorio

    The details of the event. It names the Run and the Template by id and never carries a row, a cell, a column name or a file name.

  • timestampstringdate-timeobbligatorio

    When the event was created, as a UTC date and time.

  • typestringobbligatorio

    What happened: run.succeeded, run.failed, or webhook.test for the test event you send from your account.

Tabelle di riferimento

Elencare le tabelle di riferimento

GET/reference-tables

Restituisce le tabelle di riferimento del tuo account: nome, colonne, numero di righe, ultima modifica e i modelli che le usano. Mai una riga.

Permesso reference_tables:read

GET/reference-tables
curl "https://doctransform.xyz/api/v1/reference-tables" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Risposta200
{
  "data": [
    {
      "columns": [
        "SKU",
        "Category",
        "Brand"
      ],
      "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
      "name": "Catalog",
      "rows": 1840,
      "updated_at": "2026-10-06T22:15:40Z",
      "used_by": [
        {
          "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
          "name": "Monthly invoices"
        }
      ]
    }
  ]
}

Sostituire le righe di una tabella di riferimento

PUT/reference-tables/{table_id}/rows

Scambia tutte le righe di una tabella con quelle del file inviato, tutto o niente. Un file che toglie una colonna letta da un modello riceve 409 REFERENCE_TABLE_COLUMN_IN_USE e non sostituisce nulla.

Permesso reference_tables:write

PUT/reference-tables/{table_id}/rows
curl -X PUT "https://doctransform.xyz/api/v1/reference-tables/{table_id}/rows" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY" \
  -F "file=@/path/to/your/file.csv"
Risposta200
{
  "columns": [
    "SKU",
    "Category",
    "Brand"
  ],
  "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
  "name": "Catalog",
  "rows": 1840,
  "updated_at": "2026-10-06T22:15:40Z",
  "warnings": [
    {
      "code": "JOIN_REPEATED_KEYS",
      "columns": [
        "SKU"
      ],
      "count": 3
    }
  ]
}

L'oggetto Reference Table

Una tabella di riferimento salvata: le sue colonne e la sua dimensione, mai una riga.

Esempio
{
  "columns": [
    "SKU",
    "Category",
    "Brand"
  ],
  "id": "rt_8d1f0c2a4b6e4a9fb3c7e5d2a1f09b64",
  "name": "Catalog",
  "rows": 1840,
  "updated_at": "2026-10-06T22:15:40Z",
  "used_by": [
    {
      "id": "b3b8e6c4-5f2a-4d7e-9a1c-2e8f6d0a7b34",
      "name": "Monthly invoices"
    }
  ]
}

Attributi

  • columnsarrayobbligatorio

    The table's column names, in order.

  • idstringobbligatorio

    The table's id; send it to replace its rows.

  • namestringobbligatorio

    The name the table was saved under.

  • rowsintegerobbligatorio

    How many rows the table holds.

  • updated_atstringdate-timeobbligatorio

    When the table's rows last changed.

  • used_byarrayobbligatorio

    The Templates with a Join Step on this table.