Documentos

Um Documento é uma única página processada — 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 de 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, PDF, Word ou texto simples) 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	Local	Tipo	Descrição
`file`	corpo (multipart)	arquivo	Obrigatório, a menos que `url` seja fornecido. Uma imagem (JPEG/PNG/etc.), um PDF, um Documento do Word (`.docx` apenas — o formato binário legado `.doc` não é suportado, salve como `.docx` primeiro) ou um arquivo de texto simples (`.txt`). PDFs têm limite de 50 páginas por upload e são divididos em um Documento por página; `.docx`/`.txt` são convertidos para PDF no servidor primeiro e depois seguem a mesma divisão por página.
`url`	corpo (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 `http://` ou `https://` pública (sem endereços localhost/rede privada); o download é limitado a 30MB com um tempo limite de leitura de 15 segundos.
`batch_name`	corpo (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`	corpo (multipart)	inteiro, 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 avulsos) ao chamar `process`.
`password`	corpo (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`	cabeçalho, opcional	string	Seguro para repetir. Consulte Idempotência.

Uploads de PDF (e Word/texto convertidos) 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 .docx/.txt que converte para mais de uma página se comporta de forma idêntica, pois é dividido pelo mesmo caminho de código assim que a conversão produz bytes de PDF. Um upload de imagem única retorna uma string escalar. O código do cliente que assume que document_id é sempre uma string falhará em um upload de várias páginas — verifique se o arquivo que você está enviando pode produzir mais de uma página e ramifique com base na forma da resposta, ou sempre envie imagens e nunca confie no caso escalar. Veja 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 funcionou), PDF com mais de 50 páginas, ou arquivo .docx/.txt que falhou ao converter (incluindo arquivo .doc legado — não suportado, salve como .docx primeiro).
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

Busca 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 do 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.

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.

Obter a imagem de um Documento

Retorna a imagem da página por trás de um Documento — a página completa por padrão, um recorte normalizado dela com ?crop=, ou uma miniatura pré-gerada menor com ?size=thumb para carregamento mais rápido em listas/grades. ?crop= 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 da página completa, sem recorte.
`size`	query, opcional	string	Informe `thumb` para obter uma versão pré-gerada menor em vez da página em resolução total. Ignorado se `crop` também for fornecido. Retorna à imagem completa se nenhuma miniatura foi gerada para este Documento (imagens pequenas nem sempre valem a miniatura) — nunca é um erro.

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 (por exemplo, ultrapassou a janela de retenção de exclusão automática da sua conta).
invalid_parameter (param: "crop") — valor de crop malformado, coordenadas fora de 0–1, ou uma região de corte que fica vazia após ser limitada 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 faturável 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	Local	Tipo	Descrição
`document_id`	path	string	Deve ser um Documento com status `succeeded` e 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 consome 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á estava em execução (already_running: true) — ou seja, você já chamou este mesmo endpoint para este Documento antes e aquele job de bbox anterior ainda não terminou. Isso não está relacionado ao fato de a extração do próprio Documento ter sido concluída — o 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á foi concluída. already_running é puramente sobre um segundo job de bbox para o mesmo Documento, não sobre o job de extração. Em ambos os casos (202 ou 200), nada de 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 } } }