DocTransform

Referência da API

Cada endpoint da API pública, com sua requisição e uma resposta de exemplo.

URL base
https://doctransform.xyz/api/v1
Autenticação
Authorization: Bearer · Como obter uma chave de API
Versionamento
Uma única versão, na URL base. O que retirarmos continua funcionando por pelo menos 12 meses depois de ser marcado com os cabeçalhos Deprecation e Sunset.
Respostas
Ignore qualquer campo que não reconheça: adicionamos campos sem aviso prévio.
OpenAPI 3.1
· doctransform.xyz/api/v1/openapi.json

Modelos

Listar modelos

GET/templates

Retorna os modelos da sua conta. Use o id de um modelo para criar uma execução.

Permissão templates:read

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

O objeto Template

Um modelo salvo que uma execução pode aplicar.

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

Atributos

  • descriptionstringopcionalanulável

    What the Template does, when its owner wrote one.

  • idstringobrigatório

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

  • namestringopcionalanulável

    The name the Template was saved under.

  • output_formatstringopcionalanulável

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

Execuções

Criar uma execução

POST/templates/{template_id}/runs

Executa um modelo sobre um arquivo, mais um arquivo para cada arquivo de união que o modelo lê, associados por cabeçalho, não por ordem. Responde 201 com a execução concluída se terminar em cerca de 30 segundos; senão, responde 202 enquanto ela continua. Envie uma Idempotency-Key e uma nova tentativa nunca é cobrada duas vezes. Uma execução concluída gasta uma exportação da sua cota mensal; uma recusada, com falha ou repetida não gasta nenhuma.

Permissão 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"
Resposta201
{
  "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
    }
  ]
}

Parâmetros de rota

  • template_idstringobrigatório

    The id of the Template to run.

Cabeçalhos

  • Idempotency-Keystringopcional

    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_mappingstringopcional

    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.

  • delimiterstringopcional

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

  • filefileobrigatório

    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_rowintegeropcional

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

Retorna Um objeto Run

Erros (33)

Ver todos os códigos de erro e os limites

Consultar uma execução

GET/runs/{run_id}

Retorna o estado de uma execução. Consulte até que seja succeeded ou failed.

Permissão runs:read

GET/runs/{run_id}
curl "https://doctransform.xyz/api/v1/runs/{run_id}" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Resposta200
{
  "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
    }
  ]
}

Baixar o resultado

GET/runs/{run_id}/output

Baixa o arquivo produzido por uma execução concluída.

Permissão 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"
Resposta200

Arquivo binário. O Content-Type segue o formato de saída do modelo.

Baixar o resultado por um link

GET/runs/{run_id}/download

Descarrega o ficheiro de uma execução terminada a partir de uma ligação pré-assinada. Não precisa de chave de API: a ligação é pública por desenho e expira, por isso partilhe-a só com quem deve ter o ficheiro.

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

Arquivo binário. O Content-Type segue o formato de saída do modelo.

Parâmetros de rota

  • run_idstringobrigatório

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

Retorna O arquivo de saída

Erros (7)

Ver todos os códigos de erro e os limites

O objeto Run

Uma execução: seu status, seus horários e, quando existe, seu arquivo de saída.

Exemplo
{
  "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
    }
  ]
}

Atributos

  • change_reportobjectopcionalanulável

    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-timeopcionalanulável

    When the Run finished; null while it is running.

  • created_atstringdate-timeobrigatório

    When the Run was accepted.

  • destination_checkobjectopcionalanulável

    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.

  • errorobjectopcionalanulável

    Why the Run failed; null unless it did.

  • expires_atstringdate-timeopcionalanulável

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

  • idstringobrigatório

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

  • outputobjectopcionalanulável

    The output file; null until the Run succeeds.

  • reference_tablesarrayopcional

    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_writtenintegeropcionalanulável

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

  • statusrunning | succeeded | failedobrigatório

    Where the Run is now.

  • template_idstringobrigatório

    The Template the Run applied.

  • truncatedbooleanopcional

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

  • warningsarrayopcional

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

Eventos de webhook

O que o seu receptor recebe quando uma execução termina. O DocTransform envia cada evento como um POST com corpo JSON para o URL de um webhook adicionado na sua conta. Todos os eventos têm a mesma forma, descrita no fim deste grupo.

Guia de webhooks

Uma execução teve sucesso

POSTrun.succeeded

Enviado quando uma execução termina e o seu ficheiro de saída está pronto. O corpo leva uma ligação de download que não precisa de chave de API até expirar.

Corpo enviado para o seu 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
  }
}

Uma execução falhou

POSTrun.failed

Enviado quando uma execução termina sem ficheiro de saída. O corpo diz o motivo com um código fixo e uma frase simples.

Corpo enviado para o seu 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."
    }
  }
}

Um evento de teste

POSTwebhook.test

Enviado apenas quando carrega em Enviar evento de teste na sua conta, para verificar o seu receptor. Descreve uma execução inventada e a sua ligação não funciona.

Corpo enviado para o seu 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
  }
}

O corpo do evento

O que cada evento de webhook leva: o que aconteceu, quando e os detalhes da execução. Nunca uma linha, uma célula ou um nome de ficheiro.

Exemplo
{
  "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
  }
}

Atributos

  • dataobjectobrigatório

    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-timeobrigatório

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

  • typestringobrigatório

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

Tabelas de referência

Listar tabelas de referência

GET/reference-tables

Retorna as tabelas de referência da sua conta: nome, colunas, número de linhas, última alteração e os modelos que usam cada uma. Nunca uma linha.

Permissão reference_tables:read

GET/reference-tables
curl "https://doctransform.xyz/api/v1/reference-tables" \
  -H "Authorization: Bearer $DOCTRANSFORM_API_KEY"
Resposta200
{
  "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"
        }
      ]
    }
  ]
}

Substituir as linhas de uma tabela de referência

PUT/reference-tables/{table_id}/rows

Troca todas as linhas de uma tabela pelas do arquivo enviado, tudo ou nada. Um arquivo que remove uma coluna lida por um modelo recebe 409 REFERENCE_TABLE_COLUMN_IN_USE e não substitui nada.

Permissão 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"
Resposta200
{
  "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
    }
  ]
}

O objeto Reference Table

Uma tabela de referência salva: suas colunas e seu tamanho, nunca uma linha.

Exemplo
{
  "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"
    }
  ]
}

Atributos

  • columnsarrayobrigatório

    The table's column names, in order.

  • idstringobrigatório

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

  • namestringobrigatório

    The name the table was saved under.

  • rowsintegerobrigatório

    How many rows the table holds.

  • updated_atstringdate-timeobrigatório

    When the table's rows last changed.

  • used_byarrayobrigatório

    The Templates with a Join Step on this table.