# Referência da API de Templates e Campos

> Crie e gerencie Templates de extração e seus Campos (as colunas que a extração produz), navegue por modelos predefinidos integrados e controle a ordem dos campos de saída para a API v1 do ImageToTable.ai.

Um **Template** é uma lista salva e reutilizável de **Campos** que você deseja extrair de um documento — um campo por coluna de saída. Passe o `id` de um Template para [Iniciar o processamento de um lote](/developers/reference/batches#start-processing-a-batch) em vez de listar seus campos novamente a cada chamada. Você também pode criar um Template a partir de um [modelo predefinido](#list-presets) ou ignorar Templates completamente e passar `fields` avulsos diretamente para `process` para uma execução única.

## Listar templates

Retorna seus templates salvos, cada um com sua lista completa e ordenada de campos incorporada.

`GET /api/v1/templates`

### Parâmetros

| Nome | Local | Tipo | Descrição |
| --- | --- | --- | --- |
| limit | query, opcional | inteiro | 1–100. Padrão 50. |
| page_token | query, opcional | string | Cursor opaco de um next_page_token de resposta anterior. Consulte Paginação . |

### Possíveis erros

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `invalid_parameter` — `limit` ou `page_token` inválidos.

## Criar um modelo

Duas formas de criar um modelo em um único endpoint: do zero (opcionalmente clonando campos de outro modelo via `base_template_id`) ou a partir de um preset interno via `preset_id`.

`POST /api/v1/templates`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| name | corpo (JSON) | string | Obrigatório, a menos que preset_id seja informado (neste caso, usa o nome do preset, desambiguado com um sufixo de timestamp se você já tiver um modelo com esse nome). |
| preset_id | corpo (JSON) | string, opcional | Construir o modelo (e seus campos) a partir de um preset interno — veja Listar presets para IDs válidos. |
| base_template_id | corpo (JSON) | inteiro, opcional | Usado apenas quando preset_id não é informado — clona os campos deste modelo existente para o novo. |

### Possíveis erros

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `missing_parameter` (`param: "name"`) — sem `name` e sem `preset_id`.
- `invalid_parameter` (`param: "name"`) — já existe um modelo com este nome (apenas no caminho de criação sem preset).
- `invalid_parameter` (`param: "preset_id"`) — ID de preset desconhecido.
- `internal_error`

## Excluir um modelo

Exclui um modelo e todos os seus campos (em cascata — não é necessário chamada de limpeza separada). Não afeta documentos que já usaram este modelo em uma chamada `process` anterior; os resultados já extraídos permanecem intactos.

`DELETE /api/v1/templates/{id}`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| id | path | integer | O modelo a ser excluído. |

### Erros possíveis

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `template_not_found`
- `internal_error`

## Listar predefinições

Listas de campos integradas para tipos comuns de documentos (faturas, recibos, extratos bancários e mais) — passe o `id` de uma predefinição como `preset_id` para [Criar um modelo](#create-a-template) e obtenha um modelo funcional sem precisar listar campos manualmente. As predefinições são configurações estáticas, não linhas de banco de dados — não há como criar, editar ou excluir uma pela API.

`GET /api/v1/presets`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| category | query, opcional | string | Filtrar por uma categoria (ex.: "Finanças e Contabilidade" ). Omita para listar todas as categorias. |
| limit | query, opcional | integer | 1–100. Padrão 50. |
| page_token | query, opcional | string | Cursor opaco de um next_page_token de resposta anterior. |

### Possíveis erros

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `invalid_parameter` — `limit` ou `page_token` inválidos.

## Listar e criar campos

`fields` é o nome público da v1 para o que a interface do produto chama de "regras de correspondência" — um campo por coluna de saída, na ordem em que a extração os emitirá. `GET` retorna todos os campos do modelo, já ordenados por `sort_order`. `POST` adiciona um novo campo ao final.

`GET POST /api/v1/templates/{id}/fields`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| id | path | integer | O modelo ao qual estes campos pertencem. |
| name | body (JSON), apenas POST | string | Obrigatório. Deve ser único neste modelo — veja erros abaixo. |
| format_requirement | body (JSON), apenas POST | string, opcional | Dica em texto livre sobre o formato esperado do valor (ex.: "YYYY-MM-DD" , "Número" ). |

### Possíveis erros

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `template_not_found`
- `missing_parameter` (`param: "name"`) — apenas POST.
- `duplicate_field_name` — já existe um campo com este `name` neste modelo.
- `internal_error`

## Atualizar e excluir um campo

`PUT` renomeia um campo (e substitui seu `format_requirement`) — é uma substituição completa, não uma atualização parcial, então inclua ambos os valores mesmo que apenas um tenha mudado. `DELETE` o remove.

`PUT DELETE /api/v1/templates/{id}/fields/{field_id}`

### Parâmetros

| Nome | Local | Tipo | Descrição |
| --- | --- | --- | --- |
| id | path | integer | O template ao qual este campo pertence. |
| field_id | path | integer | O campo a ser atualizado ou excluído. |
| name | body (JSON), apenas PUT | string | Obrigatório. Novo nome. |
| format_requirement | body (JSON), apenas PUT | string, opcional | Nova dica de formato — omita e será limpo para uma string vazia, não mantido inalterado. |

### Erros possíveis

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `template_not_found` — o template não existe/não é seu, ou (com uma mensagem observando isso) o `field_id` não está neste template.
- `missing_parameter` (`param: "name"`) — apenas PUT.
- `duplicate_field_name` — apenas PUT, renomeando para um nome que outro campo neste template já possui.
- `internal_error`

## Reordenar campos

Define explicitamente a ordem dos campos, que determina a ordem das colunas de saída em `line_items` e em exportações para Excel/Word. IDs na lista que não pertencem a este modelo são ignorados silenciosamente, em vez de rejeitar toda a solicitação.

`PATCH /api/v1/templates/{id}/fields/order`

### Parâmetros

| Nome | Localização | Tipo | Descrição |
| --- | --- | --- | --- |
| id | path | integer | O modelo a ser reordenado. |
| field_ids | body (JSON) | array of integers | Todos os IDs de campo deste modelo, na ordem desejada. Obrigatório. |

### Erros possíveis

- `missing_api_key` / `invalid_api_key` / `plan_required` — veja [Tratamento de Erros](/developers/guides/errors).
- `template_not_found`
- `invalid_parameter` (`param: "field_ids"`) — não é uma lista de inteiros.
- `internal_error`

## Code Examples

### Listar modelos

GET /api/v1/templates

**cURL**

```bash
curl https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Resposta

```json
{
  "data": [
    {
      "id": 42,
      "name": "Invoice Template",
      "created_at": "2026-06-01T10:00:00+00:00",
      "fields": [
        {
          "id": 101,
          "name": "invoice_number",
          "format_requirement": "",
          "sort_order": 1,
          "template_id": 42,
          "created_at": "2026-06-01T10:00:00+00:00"
        },
        {
          "id": 102,
          "name": "invoice_date",
          "format_requirement": "YYYY-MM-DD",
          "sort_order": 2,
          "template_id": 42,
          "created_at": "2026-06-01T10:00:00+00:00"
        }
      ]
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### Criar um modelo — do zero

POST /api/v1/templates

A primeira das duas formas — apenas um `name`, sem campos ainda. Adicione campos depois com [Listar e criar campos](#list-and-create-fields), ou clone os campos de outro modelo na mesma chamada via `base_template_id`.

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Invoice Template"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "My Invoice Template"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "My Invoice Template" }),
});
console.log(await response.json());
```

### Resposta

```json
{
  "template": {
    "id": 44,
    "name": "My Invoice Template",
    "created_at": "2026-07-16T09:00:00+00:00",
    "fields": []
  }
}
```

### Criar um modelo — a partir de um preset

POST /api/v1/templates

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset_id": "finance_invoice_general"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"preset_id": "finance_invoice_general"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ preset_id: "finance_invoice_general" }),
});
console.log(await response.json());
```

### Resposta

```json
{
  "template": {
    "id": 43,
    "name": "Invoice",
    "created_at": "2026-07-16T09:00:00+00:00",
    "fields": [
      {
        "id": 201,
        "name": "Merchant Name",
        "format_requirement": "String",
        "sort_order": 1,
        "template_id": 43,
        "created_at": "2026-07-16T09:00:00+00:00"
      }
    ]
  }
}
```

### Excluir um modelo

DELETE /api/v1/templates/{id}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/templates/43 \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://imagetotable.ai/api/v1/templates/43",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.status_code)
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/43", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(response.status);
```

### Resposta

204 Sem Conteúdo — corpo vazio.

### Listar predefinições

GET /api/v1/presets

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/presets?category=Finance%20%26%20Accounting" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/presets",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"category": "Finance & Accounting"},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/presets");
url.searchParams.set("category", "Finance & Accounting");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### Resposta

```json
{
  "data": [
    {
      "id": "finance_invoice_general",
      "category": "Finance & Accounting",
      "name": "Invoice",
      "fields": [
        {"name": "Invoice Number", "format_requirement": "DocumentNumber"},
        {"name": "Invoice Date", "format_requirement": "YYYY-MM-DD"},
        {"name": "Total Amount", "format_requirement": "Number"}
      ]
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### Listar / criar campos

POST /api/v1/templates/{id}/fields

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/templates/42/fields \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vendor_name", "format_requirement": "String"}'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/templates/42/fields",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "vendor_name", "format_requirement": "String"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "vendor_name", format_requirement: "String" }),
});
console.log(await response.json());
```

### Resposta

```json
{
  "field": {
    "id": 103,
    "name": "vendor_name",
    "format_requirement": "String",
    "sort_order": 103,
    "template_id": 42,
    "created_at": "2026-07-16T09:05:00+00:00"
  }
}
```

### Atualizar um campo

PUT /api/v1/templates/{id}/fields/{field_id}

**cURL**

```bash
curl -X PUT https://imagetotable.ai/api/v1/templates/42/fields/103 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "vendor_name", "format_requirement": "Company name, no suffix"}'
```

**Python**

```python
import os
import requests

response = requests.put(
    "https://imagetotable.ai/api/v1/templates/42/fields/103",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"name": "vendor_name", "format_requirement": "Company name, no suffix"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/103", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "vendor_name", format_requirement: "Company name, no suffix" }),
});
console.log(await response.json());
```

### Resposta

```json
{
  "field": {
    "id": 103,
    "name": "vendor_name",
    "format_requirement": "Company name, no suffix",
    "sort_order": 103,
    "template_id": 42,
    "created_at": "2026-07-16T09:05:00+00:00"
  }
}
```

### Excluir um campo

DELETE /api/v1/templates/{id}/fields/{field_id}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/templates/42/fields/103 \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.delete(
    "https://imagetotable.ai/api/v1/templates/42/fields/103",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.status_code)
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/103", {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(response.status);
```

### Resposta

204 No Content — corpo vazio.

### Reordenar campos

PATCH /api/v1/templates/{id}/fields/order

**cURL**

```bash
curl -X PATCH https://imagetotable.ai/api/v1/templates/42/fields/order \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_ids": [102, 101, 103]}'
```

**Python**

```python
import os
import requests

response = requests.patch(
    "https://imagetotable.ai/api/v1/templates/42/fields/order",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"field_ids": [102, 101, 103]},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/templates/42/fields/order", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ field_ids: [102, 101, 103] }),
});
console.log(await response.json());
```

### Resposta

```json
{
  "data": [
    {"id": 102, "name": "invoice_date", "format_requirement": "YYYY-MM-DD", "sort_order": 1, "template_id": 42, "created_at": "2026-06-01T10:00:00+00:00"},
    {"id": 101, "name": "invoice_number", "format_requirement": "", "sort_order": 2, "template_id": 42, "created_at": "2026-06-01T10:00:00+00:00"},
    {"id": 103, "name": "vendor_name", "format_requirement": "Company name, no suffix", "sort_order": 3, "template_id": 42, "created_at": "2026-07-16T09:05:00+00:00"}
  ],
  "has_more": false,
  "next_page_token": null
}
```

---

Source: https://imagetotable.ai/pt/developers/reference/templates-fields