Lotes

Um lote é um grupo nomeado de um ou mais Documentos que você processa, consulta e obtém resultados em conjunto. Você não cria um lote explicitamente — ele é criado implicitamente na primeira vez que você envia um documento com esse batch_name (consulte Enviar um documento).

Iniciar processamento de um lote

Inicia a extração em todos os documentos elegíveis atualmente no lote (qualquer um que ainda não esteja processing ou succeeded). Este é o endpoint que realmente consome créditos — um por documento na fila.

POST /api/v1/batches/{batch_name}/process

Parâmetros

Nome	Local	Tipo	Descrição
`batch_name`	path	string	O lote a ser processado.
`template_id`	body (JSON)	integer, opcional	Um modelo salvo a ser aplicado. Tem prioridade sobre `fields` se ambos forem fornecidos.
`fields`	body (JSON)	array, opcional	Lista de campos ad-hoc apenas para esta execução — `[{"name": "...", "format_requirement": "..."}]` ou um array simples de strings de nome. Ignorado se `template_id` for fornecido. Omita ambos para deixar o modelo inferir as colunas por conta própria.
`quality`	body (JSON)	string, opcional	`"fast"` ou `"high"`. Omita para usar a configuração `thinking_type` da sua conta — consulte Configurações da Conta e Comportamento da API.
`webhook_url`	body (JSON)	string, opcional	Registra (ou atualiza) o callback de conclusão deste lote na mesma chamada — equivalente a também chamar Registrar um webhook de lote. Deve ser `http://` ou `https://`.
`Idempotency-Key`	header, opcional	string	Fortemente recomendado — este endpoint deduz créditos. Consulte Idempotência.

quality é a única configuração da conta que a API permite sobrescrever por chamada — todas as outras preferências de nível de conta (anotação automática de bbox, política de retenção) são lidas da sua conta e não podem ser sobrescritas por requisição. Consulte Configurações da Conta e Comportamento da API para o panorama completo, incluindo por que auto_annotate_bbox pode fazer com que esta chamada também cobre pela anotação de bbox, mesmo que você nunca tenha chamado aquele endpoint.

O campo webhook_registered da resposta reflete apenas esta chamada específica — ele é true se e somente se esta requisição incluiu webhook_url, e não se o lote tem um webhook ou não. Um lote cujo webhook foi configurado anteriormente via Registrar um webhook de lote (e não repetido aqui) disparará corretamente seu callback ao ser concluído, mas este campo ainda retorna false para aquela chamada — ele não verifica se um BatchWebhook já existe. Não trate um false aqui como "nenhum webhook será disparado para este lote."

Chamar este endpoint novamente em um lote que você já processou e foi notificado — após fazer upload de mais documentos nele — rearma automaticamente o webhook desse lote se ele já tiver sido disparado, para que a conclusão da nova leva também notifique. Nenhuma chamada extra é necessária para que isso aconteça; consulte a seção "Reprocessando um lote" do guia de Webhooks para a semântica exata (incluindo o que acontece se duas levas se sobrepuserem).

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
batch_not_found — não existem documentos sob este batch_name na sua conta.
invalid_parameter — valor inválido de quality/webhook_url/template_id, ou nenhum documento no lote está atualmente elegível para processamento (todos já concluídos/em processamento, ou o lote está vazio).
template_not_found
insufficient_credits — créditos disponíveis insuficientes para cobrir os documentos sendo enfileirados.

Listar lotes

Retorna uma lista paginada e filtrável de resumos dos seus lotes — o equivalente ao "Files Filter" para consumidores da API. Retorna apenas resumos (document_count, status agregado); use Obter resultados do lote para obter os dados completos por documento de um lote específico.

GET /api/v1/batches

Parâmetros

Nome	Localização	Tipo	Descrição
`source`	query, opcional	string	Um dos valores: `direct`, `collect`, `email_inbox`, `api` (enviado via `POST /documents`, diferente de `direct` que é o web app principal) ou `share` (um alias que cobre tanto `collect` quanto `email_inbox`). Omita para todas as origens.
`q`	query, opcional	string	Correspondência de substring sem diferenciação de maiúsculas/minúsculas nos nomes de arquivos dentro do lote.
`date_from`	query, opcional	string (`YYYY-MM-DD`)	Limite inferior inclusivo para o horário de upload.
`date_to`	query, opcional	string (`YYYY-MM-DD`)	Limite superior inclusivo para o horário de upload (final do dia).
`status`	query, opcional	string	Lista separada por vírgulas de status públicos (`queued,processing,succeeded,failed,canceled`) para filtrar.
`template_id`	query, opcional	integer	Apenas lotes que usaram este modelo.
`mode`	query, opcional	string	O único valor aceito nesta versão é `"table"` (o único modo que v1 suporta atualmente). Reservado para futuros modos de extração.
`limit`	query, opcional	integer	1–100. Padrão 20.
`page_token`	query, opcional	string	Cursor opaco de um `next_page_token` de resposta anterior. Veja Paginação.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
invalid_parameter — mode, limit, status ou page_token inválidos.

Obter status do lote

Status agregado leve de um lote — contagens por status público mais uma flag all_done, útil para um loop de polling barato que ainda não precisa do payload completo de resultados.

GET /api/v1/batches/{batch_name}

Parâmetros

Nome	Localização	Tipo	Descrição
`batch_name`	path	string	O lote a verificar.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
batch_not_found

Obter resultados do lote

A principal forma de recuperar dados extraídos. Cada documento no lote é retornado com seus line_items remodelados — um array de objetos {field_name: value}, um por linha extraída. Por padrão, os valores dos campos são escalares simples (string, número, etc.).

GET /api/v1/batches/{batch_name}/results

Parâmetros

Nome	Localização	Tipo	Descrição
`batch_name`	path	string	O lote para buscar resultados.
`include`	query, opcional	string	`"bbox"` — quando definido, cada valor de campo se torna `{"value": ..., "bbox": {...}\|null}` em vez de um escalar simples, e cada documento recebe um campo `bbox_status`. Veja abaixo — isso nunca dispara um novo job de bbox, apenas retorna o que já foi computado.

?include=bbox lê apenas resultados retroalimentados — ele não chama Disparar anotação de bbox por você. Se o bbox nunca foi disparado para um documento (manualmente ou pela configuração auto_annotate_bbox da sua conta), os campos desse documento simplesmente retornam com "bbox": null.

Campos de localização pura são um terceiro formato distinto. Alguns campos de modelo pedem ao modelo para localizar algo em vez de transcrever texto (ex.: "localize a foto do retrato"). Para esses campos, o valor inteiro é uma localização — então, em vez de um escalar ou do par {"value","bbox"} acima, você recebe {"type": "image_region", "bbox": {...}, "image_url": "..."}, independentemente de ?include=bbox estar definido — a caixa não é metadado opcional aqui, é o único conteúdo do campo. image_url aponta para um JPEG recortado pronto para download (veja Obter imagem de um documento) para que você não precise recortar o original a partir de quatro números.

Cada objeto bbox — em qualquer formato — usa "unit": "normalized": as coordenadas são floats de 0 a 1 relativos à largura/altura da página, não pixels nem uma escala de 0 a 1000. Consulte o guia Bounding Boxes para a ressalva de precisão — essas coordenadas vêm diretamente do modelo sem uma verificação de precisão em nível de pixel, portanto, trate-as como "aproximadas" em vez de exatas em documentos densos ou complexos.

Erros possíveis

missing_api_key / invalid_api_key / plan_required — consulte Error Handling.
batch_not_found

Exportar um lote

Um download de conveniência — results acima é o formato canônico e estruturado para o qual esta API foi projetada; este endpoint existe para extrair os mesmos dados para uma planilha sem que você precise escrever código de remodelação por conta própria. Apenas xlsx — v1 suporta apenas o modo tabela (extração), e a exportação para Word (docx) no aplicativo principal é exclusivamente a saída nativa do modo page_word (um prompt e formato de resultado totalmente diferentes), que v1 não expõe. Não há opção de "dados de tabela como um documento Word" aqui.

GET /api/v1/batches/{batch_name}/export

Parâmetros

Nome	Localização	Tipo	Descrição
`batch_name`	path	string	O lote a ser exportado.
`format`	query, opcional	string	Apenas `xlsx` (o padrão) é aceito.

A resposta é um download de arquivo (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), não JSON — não há exemplo de resposta JSON para este endpoint.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
batch_not_found
invalid_parameter (param: "format") — qualquer valor diferente de xlsx.

Excluir um lote

Exclui permanentemente todos os documentos do lote. Qualquer documento ainda queued é reembolsado antes da exclusão. Isso também remove o registro de webhook do lote (se houver) e quaisquer jobs de anotação de bbox vinculados aos seus documentos.

DELETE /api/v1/batches/{batch_name}

Parâmetros

Nome	Localização	Tipo	Descrição
`batch_name`	path	string	O lote a ser excluído.

Possíveis erros

missing_api_key / invalid_api_key / plan_required — consulte Tratamento de Erros.
batch_not_found — diferente de outros recursos, excluir um batch_name que não é seu (ou que não existe) retorna 404 aqui, não um no-op silencioso.