# Inicio rápido de la API — Resultados en 5 minutos

> Un recorrido completo de cinco minutos por la API v1 de ImageToTable.ai: obtén tu clave, sube una factura, inicia el procesamiento y recupera el JSON extraído.

Este tutorial recorre todo el ciclo: obtener una clave, subir un documento, iniciar el procesamiento y recuperar los resultados, usando una factura como ejemplo. Si aún no has instalado `curl` o configurado una variable de entorno para tu clave, consulta [Configuración del entorno](/developers/environment-setup) primero.

## Paso 1 — Obtén tu clave de API

Tu clave de API está en la [página de configuración de tu perfil](/profile/), en la sección API Key. La API v1 requiere un plan de pago (Básico o superior); las claves del plan Gratuito pasan la verificación de autenticación, pero cada llamada posterior devuelve un error `plan_required`. Las claves generadas a partir de ahora tienen el formato `itt_live_<64 caracteres hexadecimales>`; exporta la tuya como variable de entorno para no tenerla hardcodeada en un script:

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## Paso 2 — Sube un documento

`POST /api/v1/documents` acepta un `file` (multipart) o una `url` que el servidor descarga por ti; pasa exactamente uno. `batch_name` es opcional; si lo omites, la API genera uno automáticamente (se devuelve en la respuesta) y todos los documentos que quieras procesar juntos deben compartir el mismo `batch_name`. Este ejemplo usa `url` con una factura de muestra real alojada en nuestro propio sitio, por lo que se puede ejecutar tal cual, sin necesidad de un archivo local:

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())
```

**Javascript**

```javascript
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

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

¿Tienes un archivo local? Reemplaza `url` por un campo multipart `file`; consulta [Subir un documento](/developers/reference/documents#upload-a-document) en la Referencia para ver la lista completa de parámetros, incluidos `batch_name`, `template_id` y `password`.

La respuesta devuelve el ID del nuevo documento y el lote en el que se asignó — guarda `batch_name`, lo necesitarás en los siguientes dos pasos:

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}
```

Subir un PDF de varias páginas en lugar de una imagen funciona igual, excepto que `document_id` se devuelve como un *array* — un documento por página — ya que cada página se procesa de forma independiente.

## Paso 3 — Iniciar el procesamiento

`POST /api/v1/batches/{batch_name}/process` inicia la extracción. Puedes apuntarlo a una [Plantilla](/developers/reference/templates-fields) guardada mediante `template_id`, o — como aquí — declarar los campos que deseas en línea con `fields` para una ejecución única:

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());
```

Esto descuenta créditos de inmediato (un documento por llamada) y encola el/los documento(s) para procesamiento en segundo plano:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}
```

Omite por completo `fields` y `template_id` y la API inferirá nombres de columna razonables por su cuenta. `quality` también es opcional — si lo omites, el procesamiento usará la configuración de velocidad/calidad de tu cuenta (consulta [Configuración de la Cuenta y Comportamiento de la API](/developers/guides/account-settings)). `webhook_registered: false` aquí solo significa que esta llamada en particular no incluyó `webhook_url` — no significa que no haya ningún webhook registrado para este lote; consulta la [referencia de Lotes](/developers/reference/batches#start-processing-a-batch) si estás registrando uno por separado mediante `PUT .../webhook`.

## Paso 4 — Consulta y obtén tus resultados

El procesamiento es asíncrono: consulta `GET /api/v1/batches/{batch_name}` hasta que `all_done` sea `true` (unos segundos para un solo documento), o registra un [webhook](/developers/guides/webhooks) en lugar de consultar. El ciclo de vida completo se explica en la guía del [Modelo de Tarea Asíncrona](/developers/guides/async-model).

Una vez finalizado, obtén los resultados reorganizados:

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/260716-4K9P/results \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

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

El JSON de respuesta nunca cambia según el idioma: su estructura no varía según el cliente que envió la solicitud:

```json
{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}
```

`completed_at` se establece cuando un documento (o, a nivel de lote, todos los documentos del lote) alcanza un estado terminal: `succeeded`, `failed` o `canceled`. Permanece `null` mientras esté en `queued` o `processing`, y a nivel de lote también permanece `null` hasta que *todos* los documentos del lote hayan finalizado, incluso si algunos terminaron antes.

## Próximos pasos

A partir de aquí: lee [Modelo de tarea asíncrona](/developers/guides/async-model) para conocer el ciclo de vida completo del estado, [Webhooks](/developers/guides/webhooks) para recibir notificaciones en lugar de consultar, y [Referencia de la API](/developers/reference/) para la lista completa de parámetros de cada endpoint.

---

Source: https://imagetotable.ai/es/developers/quickstart