Documentos

Um Documento é uma página processada individualmente — uma imagem enviada, ou uma página renderizada de um PDF enviado. Cada Documento pertence a um Lote (identificado por batch_name), que é a unidade que você realmente inicia o processamento. Enviar um PDF com várias páginas cria um Documento por página no mesmo lote — veja Fazer upload de um documento abaixo.

Fazer upload de um documento

Envia um único arquivo (imagem ou PDF) para um lote. Se batch_name for omitido, um será gerado automaticamente e retornado na resposta. O upload não inicia a extração — chame Iniciar processamento de um lote assim que você tiver enviado tudo o que deseja processar em conjunto. O campo remaining_batch_capacity da resposta informa quantos documentos adicionais este lote pode aceitar antes de atingir o tamanho máximo do seu plano (veja max_batch_size em Conta) — útil para decidir no lado do cliente se deve continuar adicionando a este lote ou iniciar um novo, sem uma consulta separada.

POST /api/v1/documents

Parâmetros

Nome	Localização	Tipo	Descrição
`file`	body (multipart)	file	Obrigatório, a menos que `url` seja fornecido. Uma imagem (JPEG/PNG/etc.) ou um PDF. PDFs são limitados a 30 páginas por upload e são divididos em um Documento por página.
`url`	body (multipart)	string, opcional	Alternativa a `file` — o servidor baixa o arquivo desta URL em vez de você precisar anexá-lo. Mutuamente exclusivo com `file`; forneça exatamente um. Deve ser uma URL pública `http://` ou `https://` (sem endereços localhost/rede privada); o download é limitado a 30MB com um tempo limite de leitura de 15 segundos.
`batch_name`	body (multipart)	string, opcional	Lote ao qual adicionar este documento. Omita para gerar automaticamente um novo nome de lote (retornado na resposta). Reutilize o mesmo valor em vários uploads para construir um lote antes de processá-lo.
`template_id`	body (multipart)	integer, opcional	Um ID de Modelo pertencente à sua conta para pré-associar a este documento. Não é obrigatório — você também pode passar um modelo (ou campos ad-hoc) ao chamar `process`.
`password`	body (multipart)	string, opcional	Apenas PDF. Tentado primeiro se o arquivo estiver protegido por senha. Se omitido, ou se não desbloquear o arquivo, recorre a quaisquer senhas já salvas nas configurações de Email Inbox da sua conta — este campo não exige que você tenha o Email Inbox configurado, é apenas uma alternativa por chamada a ele.
`Idempotency-Key`	header, opcional	string	Seguro para repetir. Consulte Idempotência.

Uploads de PDF retornam um array, não um único ID. Fazer upload de um PDF renderiza cada página como seu próprio Documento e o document_id da resposta se torna um array JSON (uma string por página, na ordem das páginas), além de um campo page_count. Um upload de imagem única retorna uma string escalar. Código cliente que assume que document_id é sempre uma string falhará em um upload de PDF — verifique se o arquivo que você está enviando é um PDF e ramifique com base na forma da resposta, ou sempre envie imagens e nunca dependa do caso escalar. Consulte os dois exemplos de resposta à direita.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
missing_parameter — nem file nem url foram enviados.
invalid_parameter (param: "file") — imagem ou PDF inválido/corrompido, PDF protegido por senha que não pôde ser desbloqueado (nem o campo password nem nenhuma senha salva do Email Inbox funcionaram), ou PDF com mais de 30 páginas.
invalid_parameter (param: "url") — tanto file quanto url foram enviados, a URL não resolve para um endereço público, o download falhou ou expirou, ou o arquivo baixado excede 30MB.
invalid_parameter (param: "batch_name") — o lote já atingiu o tamanho máximo do seu plano.
invalid_parameter (param: "template_id") ou template_not_found.
rate_limit_exceeded — muitos documentos não processados (na fila) já existem na conta; processe ou exclua alguns primeiro.

Obter um documento

Recupera o status atual de um único documento e, após a extração bem-sucedida, seus line_items remodelados. Este é o equivalente para um único documento de Obter resultados do lote — mesmas regras de remodelagem, mas sem a opção ?include=bbox (disponível apenas no endpoint de resultados em nível de lote).

GET /api/v1/documents/{document_id}

Parâmetros

Nome	Localização	Tipo	Descrição
`document_id`	path	string	O ID do documento retornado por `POST /documents` (ou uma entrada desse array, para uma página de PDF).

status é sempre um dos valores queued, processing, succeeded, failed, canceled — consulte o guia Modelo Assíncrono para a máquina de estados. completed_at é definido quando o documento atinge um estado terminal (succeeded, failed ou canceled) e permanece null antes disso.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
document_not_found — nenhum Documento com este ID em sua conta.

Obter a imagem de um Documento

Retorna a imagem da página de um Documento — a página completa por padrão, ou um recorte normalizado dela com ?crop=. É isso que alimenta image_url em campos de localização pura (consulte Obter resultados do lote), mas você também pode chamá-lo diretamente com suas próprias coordenadas.

GET /api/v1/documents/{document_id}/image

Parâmetros

Nome	Localização	Tipo	Descrição
`document_id`	path	string	O ID do Documento.
`crop`	query, opcional	string	`"x1,y1,x2,y2"` — quatro floats entre 0 e 1, mesma convenção de coordenadas normalizadas de todo objeto `bbox` em outras partes da API. Omita para obter a imagem de página completa e sem recorte.

A resposta são os bytes brutos da imagem (Content-Type: image/jpeg), não JSON — não há exemplo de resposta JSON à direita para este endpoint, apenas a requisição.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
document_not_found — nenhum Documento com este ID, ou o arquivo de imagem original não está mais disponível (ex.: ultrapassou a janela de retenção de exclusão automática da sua conta).
invalid_parameter (param: "crop") — valor crop malformado, coordenadas fora de 0–1, ou uma região de recorte vazia após o ajuste aos limites da imagem.

Acionar anotação de bbox

Inicia explicitamente o job opcional e pago de segunda passagem que localiza onde cada valor de campo extraído está fisicamente na página. Esta é uma ação faturada separada da extração em si — consulte o guia Bounding Boxes antes de integrar isso, especialmente a nota sobre a configuração auto_annotate_bbox da sua conta que pode acionar (e cobrar) este mesmo job automaticamente sem que você nunca chame este endpoint.

POST /api/v1/documents/{document_id}/bbox

Parâmetros

Nome	Localização	Tipo	Descrição
`document_id`	path	string	Deve ser um documento já `succeeded` com dados extraídos — você não pode anotar um documento que ainda não concluiu a extração.
`Idempotency-Key`	header, opcional	string	Recomendado — esta ação gasta créditos. Consulte Idempotência.

Retorna 202 quando um novo job de bbox acaba de ser enfileirado, ou 200 quando um job de bbox para este documento já está em execução (already_running: true) — significando que você já chamou este mesmo endpoint para este documento uma vez antes e aquele job de bbox anterior ainda não terminou. Isso não tem relação com a conclusão da extração do próprio documento — bbox só pode ser acionado em um documento que já está succeeded (veja "Erros possíveis" abaixo), então quando você pode chamar este endpoint, a extração já está concluída. already_running é puramente sobre um segundo job de bbox para o mesmo documento, não sobre o job de extração. De qualquer forma (202 ou 200), nada novo é iniciado ou cobrado no caminho 200 — consulte Obter anotação de bbox com o group_batch_id retornado para obter o resultado.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
document_not_found — nenhum documento com este ID em sua conta.
insufficient_credits — créditos insuficientes para executar esta passagem de anotação.
invalid_parameter — o documento não está em um estado válido para isso (ainda processando) ou não possui dados extraídos para localizar caixas.

Obter anotação bbox

Consulta o status e obtém os resultados do trabalho de anotação bbox mais recente acionado para um documento. Se nenhum trabalho foi acionado para este documento, exists é false e status/group_batch_id são null — esta é uma resposta normal e comum (a maioria dos documentos nunca tem bbox acionado), não um erro.

GET /api/v1/documents/{document_id}/bbox

Parâmetros

Nome	Localização	Tipo	Descrição
`document_id`	path	string	O ID do documento.

rows mapeia um índice de linha (como string, ex. "0") para um mapa de nome de campo → objeto bbox normalizado (ou null se a localização daquele campo não foi encontrada na página). status usa o mesmo conjunto fechado de 5 valores de enumeração usado em toda a API.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
document_not_found — nenhum documento com este ID em sua conta.

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, files={"file": open("invoice.jpg", "rb")}, data={"batch_name": "july-invoices"}, ) print(response.json())

import { readFile } from "node:fs/promises"; const formData = new FormData(); formData.append("file", new Blob([await readFile("invoice.jpg")]), "invoice.jpg"); formData.append("batch_name", "july-invoices"); const response = await fetch("https://imagetotable.ai/api/v1/documents", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, body: formData, }); console.log(await response.json());

curl -X POST https://imagetotable.ai/api/v1/documents \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "url=https://imagetotable.ai/static/samples/invoice.webp" \ -F "batch_name=july-invoices"

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, data={ "url": "https://imagetotable.ai/static/samples/invoice.webp", "batch_name": "july-invoices", }, ) print(response.json())

{ "document_id": [ "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p1", "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p2" ], "batch_name": "july-invoices", "page_count": 2, "remaining_batch_capacity": 198 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "batch_name": "july-invoices", "filename": "invoice_042.jpg", "status": "succeeded", "created_at": "2026-07-16T09:12:03+00:00", "started_at": "2026-07-16T09:12:05+00:00", "completed_at": "2026-07-16T09:12:14+00:00", "line_items": [ { "invoice_number": "INV-1042", "invoice_date": "2026-07-01", "total_amount": "1,204.50" } ] }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) with open("page.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("page.jpg", Buffer.from(await response.arrayBuffer()));

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"crop": "0.10,0.08,0.42,0.30"}, ) with open("crop.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const url = new URL("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image"); url.searchParams.set("crop", "0.10,0.08,0.42,0.30"); const response = await fetch(url, { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("crop.jpg", Buffer.from(await response.arrayBuffer()));

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json());

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "exists": true, "status": "succeeded", "group_batch_id": "bx_8a3c2e1f", "rows": { "0": { "invoice_number": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}, "total_amount": null } } }