# Início Rápido da API — Obtenha Resultados em 5 Minutos

> Um passo a passo completo de ponta a ponta da API v1 do ImageToTable.ai: obtenha sua chave, envie uma fatura, inicie o processamento e recupere o JSON extraído.

Este guia percorre todo o ciclo — obtenha uma chave, envie um documento, inicie o processamento e receba os resultados — usando uma fatura como exemplo. Se você ainda não instalou o `curl` ou configurou uma variável de ambiente para sua chave, veja [Configuração de Ambiente](/developers/environment-setup) primeiro.

## Passo 1 — Obtenha sua chave de API

Sua chave de API está na [página de configurações do perfil](/profile/) da sua conta, em Chave de API. A API v1 exige um plano pago (Básico ou superior) — chaves de planos Gratuitos são aceitas na verificação de autenticação, mas toda chamada subsequente retorna um erro `plan_required`. As chaves geradas daqui em diante terão o formato `itt_live_<64 caracteres hexadecimais>`; exporte a sua como variável de ambiente para não deixá-la fixa no código de um script:

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

## Passo 2 — Envie um documento

`POST /api/v1/documents` aceita um `file` (multipart) ou uma `url` que o servidor baixa para você — informe exatamente um deles. `batch_name` é opcional — se omitido, a API gera um para você (retornado na resposta) e todo documento que você quiser processar em conjunto deve compartilhar o mesmo `batch_name`. Este exemplo usa `url` com uma fatura de amostra real hospedada em nosso próprio site, então pode ser executado exatamente como está, sem necessidade de arquivo 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());
```

Tem um arquivo local? Substitua `url` por um campo `file` multipart — veja [Enviar um documento](/developers/reference/documents#upload-a-document) na Referência para a lista completa de parâmetros, incluindo `batch_name`, `template_id` e `password`.

A resposta retorna o ID do novo documento e o lote em que ele foi inserido — salve `batch_name`, você precisará dele nas próximas duas etapas:

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

Enviar um PDF de várias páginas em vez de uma imagem funciona da mesma forma, exceto que `document_id` retorna como um *array* — um documento por página — já que cada página é processada de forma independente.

## Etapa 3 — Iniciar o processamento

`POST /api/v1/batches/{batch_name}/process` inicia a extração. Você pode apontá-lo para um [Template](/developers/reference/templates-fields) salvo via `template_id`, ou — como aqui — declarar os campos desejados inline com `fields` para uma execução ú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());
```

Isso deduz créditos imediatamente (um documento deduzido por chamada) e coloca o(s) documento(s) na fila para processamento em segundo plano:

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

Remova completamente `fields` e `template_id` e a API infere nomes de coluna razoáveis por conta própria. `quality` também é opcional — omita-o e o processamento usa a configuração de velocidade/qualidade da sua conta (veja [Configurações da Conta e Comportamento da API](/developers/guides/account-settings)). `webhook_registered: false` aqui significa apenas que esta chamada específica não incluiu `webhook_url` — não significa que nenhum webhook está registrado para este lote; consulte a [referência de Lotes](/developers/reference/batches#start-processing-a-batch) se você estiver registrando um separadamente via `PUT .../webhook`.

## Etapa 4 — Consulte e obtenha seus resultados

O processamento é assíncrono — consulte `GET /api/v1/batches/{batch_name}` até que `all_done` seja `true` (alguns segundos para um único documento) ou registre um [webhook](/developers/guides/webhooks) em vez de consultar. O ciclo de vida completo é abordado no guia [Async Task Model](/developers/guides/async-model).

Quando terminar, busque os 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());
```

O JSON de resposta nunca é separado por guias de idioma — a estrutura não muda com base em qual cliente enviou a requisição:

```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` é definido quando um documento (ou, no nível do lote, todos os documentos do lote) atinge um estado terminal — `succeeded`, `failed` ou `canceled`. Permanece `null` enquanto ainda estiver `queued` ou `processing`, e no nível do lote também permanece `null` até que *todos* os documentos do lote tenham terminado, mesmo que alguns deles tenham terminado antes.

## Próximos passos

A partir daqui: leia [Modelo de Tarefa Assíncrona](/developers/guides/async-model) para o ciclo de vida completo do status, [Webhooks](/developers/guides/webhooks) para ser notificado em vez de fazer polling, e [Referência da API](/developers/reference/) para a lista completa de parâmetros de cada endpoint.

---

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