Início Rápido

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 primeiro.

Passo 1 — Obtenha sua chave de API

Sua chave de API está na página de configurações do perfil 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:

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 -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"

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

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 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:

{
  "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 salvo via template_id, ou — como aqui — declarar os campos desejados inline com fields para uma execução única:

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

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

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:

{
  "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). 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 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 em vez de consultar. O ciclo de vida completo é abordado no guia Async Task Model.

Quando terminar, busque os resultados reorganizados:

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

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

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:

{
  "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 para o ciclo de vida completo do status, Webhooks para ser notificado em vez de fazer polling, e Referência da API para a lista completa de parâmetros de cada endpoint.