# Referencia de la API de Plantillas y Campos

> Crea y gestiona Plantillas de extracción y sus Campos (las columnas que produce la extracción), explora plantillas predefinidas integradas y controla el orden de los campos de salida para la API v1 de ImageToTable.ai.

Una **Plantilla** es una lista guardada y reutilizable de **Campos** que deseas extraer de un documento — un campo por columna de salida. Pasa el `id` de una Plantilla a [Iniciar procesamiento de un lote](/developers/reference/batches#start-processing-a-batch) en lugar de volver a listar tus campos en cada llamada. También puedes crear una Plantilla a partir de un [preajuste](#list-presets) integrado, u omitir las Plantillas por completo y pasar campos ad-hoc `fields` directamente a `process` para una ejecución única.

## Listar plantillas

Devuelve tus plantillas guardadas, cada una con su lista de campos completa y ordenada incorporada.

`GET /api/v1/templates`

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| limit | consulta, opcional | entero | 1–100. Valor predeterminado: 50. |
| page_token | consulta, opcional | cadena | Cursor opaco de un next_page_token de respuesta anterior. Consulta Paginación . |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `invalid_parameter` — `limit` o `page_token` incorrectos.

## Crear una plantilla

Dos formas de crear una plantilla en un solo endpoint: desde cero (opcionalmente clonando los campos de otra plantilla mediante `base_template_id`), o desde un preset incorporado mediante `preset_id`.

`POST /api/v1/templates`

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| name | cuerpo (JSON) | string | Obligatorio a menos que se proporcione preset_id (en ese caso se usa el nombre del preset, desambiguado con un sufijo de marca de tiempo si ya tienes una plantilla con ese nombre). |
| preset_id | cuerpo (JSON) | string, opcional | Construye la plantilla (y sus campos) desde un preset incorporado — consulta Listar presets para IDs válidos. |
| base_template_id | cuerpo (JSON) | integer, opcional | Solo se usa cuando no se proporciona preset_id — clona los campos de esta plantilla existente en la nueva. |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `missing_parameter` (`param: "name"`) — no hay `name` ni `preset_id`.
- `invalid_parameter` (`param: "name"`) — ya existe una plantilla con ese nombre (solo en creación sin preset).
- `invalid_parameter` (`param: "preset_id"`) — ID de preset desconocido.
- `internal_error`

## Eliminar una plantilla

Elimina una plantilla y todos sus campos (en cascada, no se necesita una llamada de limpieza aparte). No afecta a los documentos que ya usaron esta plantilla en una llamada `process` anterior; sus resultados ya extraídos no se modifican.

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

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| id | ruta | entero | La plantilla a eliminar. |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulte [Manejo de errores](/developers/guides/errors).
- `template_not_found`
- `internal_error`

## Listar preajustes

Listas de campos predefinidas para tipos de documentos comunes (facturas, recibos, estados de cuenta bancarios y más): pase el `id` de un preajuste como `preset_id` a [Crear una plantilla](#create-a-template) para obtener una plantilla funcional sin tener que enumerar los campos manualmente. Los preajustes son configuración estática, no filas de base de datos; no hay forma de crear, editar o eliminar uno a través de la API.

`GET /api/v1/presets`

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| category | consulta, opcional | cadena | Filtrar por una categoría (ej. "Finanzas y Contabilidad" ). Omita para listar todas las categorías. |
| limit | consulta, opcional | entero | 1–100. Valor predeterminado 50. |
| page_token | consulta, opcional | cadena | Cursor opaco de next_page_token de una respuesta anterior. |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `invalid_parameter` — `limit` o `page_token` incorrectos.

## Listar y crear campos

`fields` es el nombre público v1 de lo que la interfaz del producto llama "reglas de coincidencia": un campo por columna de salida, en el orden en que la extracción los emitirá. `GET` devuelve todos los campos de la plantilla, ya ordenados por `sort_order`. `POST` añade un nuevo campo al final.

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

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| id | ruta | entero | La plantilla a la que pertenecen estos campos. |
| name | cuerpo (JSON), solo POST | cadena | Obligatorio. Debe ser único dentro de esta plantilla — consulta los errores a continuación. |
| format_requirement | cuerpo (JSON), solo POST | cadena, opcional | Indicación en texto libre sobre el formato esperado del valor (ej. "YYYY-MM-DD" , "Número" ). |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `template_not_found`
- `missing_parameter` (`param: "name"`) — solo POST.
- `duplicate_field_name` — ya existe un campo con este `name` en esta plantilla.
- `internal_error`

## Actualizar y eliminar un campo

`PUT` renombra un campo (y reemplaza su `format_requirement`) — es un reemplazo completo, no un parche parcial, así que incluye ambos valores aunque solo uno haya cambiado. `DELETE` lo elimina.

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

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| id | ruta | entero | La plantilla a la que pertenece este campo. |
| field_id | ruta | entero | El campo a actualizar o eliminar. |
| name | cuerpo (JSON), solo PUT | cadena | Obligatorio. Nuevo nombre. |
| format_requirement | cuerpo (JSON), solo PUT | cadena, opcional | Nueva sugerencia de formato — si se omite, se limpia a una cadena vacía, no se deja sin cambios. |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `template_not_found` — la plantilla no existe o no es tuya, o (con un mensaje que lo indica) el `field_id` no pertenece a esta plantilla.
- `missing_parameter` (`param: "name"`) — solo PUT.
- `duplicate_field_name` — solo PUT, al renombrar a un nombre que ya tiene otro campo en esta plantilla.
- `internal_error`

## Reordenar campos

Define explícitamente el orden de los campos, que determina el orden de las columnas de salida en `line_items` y en exportaciones a Excel/Word. Los IDs de la lista que no pertenezcan a esta plantilla se ignoran silenciosamente, sin rechazar toda la solicitud.

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

### Parámetros

| Nombre | Ubicación | Tipo | Descripción |
| --- | --- | --- | --- |
| id | ruta | entero | La plantilla a reordenar. |
| field_ids | cuerpo (JSON) | arreglo de enteros | Todos los IDs de campo de esta plantilla, en el orden en que deseas que aparezcan. Obligatorio. |

### Posibles errores

- `missing_api_key` / `invalid_api_key` / `plan_required` — consulta [Manejo de errores](/developers/guides/errors).
- `template_not_found`
- `invalid_parameter` (`param: "field_ids"`) — no es una lista de enteros.
- `internal_error`

## Code Examples

### Listar plantillas

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());
```

### Respuesta

```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
}
```

### Crear una plantilla — desde cero

POST /api/v1/templates

La primera de las dos formas — solo un `name`, sin campos aún. Agrega campos después con [Listar y crear campos](#list-and-create-fields), o clona los campos de otra plantilla en la misma llamada mediante `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());
```

### Respuesta

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

### Crear una plantilla — desde un preajuste

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());
```

### Respuesta

```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"
      }
    ]
  }
}
```

### Eliminar una plantilla

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);
```

### Respuesta

204 Sin contenido — cuerpo vacío.

### Listar ajustes preestablecidos

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());
```

### Respuesta

```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 / crear 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());
```

### Respuesta

```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"
  }
}
```

### Actualizar un 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());
```

### Respuesta

```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"
  }
}
```

### Eliminar un 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);
```

### Respuesta

204 Sin contenido — cuerpo vacío.

### 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());
```

### Respuesta

```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/es/developers/reference/templates-fields