Batches

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

Iniciar o processamento de um batch

Inicia a extração em todos os documentos elegíveis atualmente no batch (qualquer um que ainda não esteja processing ou succeeded). Este é o endpoint que efetivamente gasta créditos — 1 crédito por documento na fila se sua conta estiver no Standard Model Tier, o padrão com o qual toda conta começa. Se sua conta tiver sido atribuída a Advanced ou Premium, cada documento custa 3 ou 6 créditos, respectivamente — o nível muda qual modelo executa a extração, não quais campos retornam ou como a resposta é estruturada, então nada mais sobre o contrato deste endpoint muda. Não há parâmetro tier nesta solicitação: o Model Tier é uma configuração de nível de conta atribuída pela equipe do ImageToTable.ai, não algo que o chamador escolhe por batch. O nível em vigor no momento em que este endpoint é chamado é o que será cobrado, e ele permanece bloqueado para os documentos que ele coloca na fila aqui, mesmo que o nível da conta mude antes de terminarem — um batch dividido em várias chamadas de process pode ter documentos diferentes cobrados em níveis diferentes se o nível da conta mudou entre elas. Veja Configurações da Conta & Comportamento da API para a tabela completa de configurações, e Uso da conta para saber como uma dedução não-Standard é rotulada no seu extrato de créditos.

Parâmetros

quality é a única configuração da conta que a API permite substituir 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 substituídas por solicitação. Consulte Configurações da Conta & Comportamento da API para o panorama completo, incluindo por que auto_annotate_bbox pode fazer com que esta chamada acabe cobrando você também pela anotação de bbox, mesmo que você nunca tenha chamado esse endpoint.

O webhook_registered da resposta reflete apenas esta chamada específica — é true se e somente se esta solicitação incluiu webhook_url, não se o lote tem um webhook de forma geral. Um lote cujo webhook foi configurado anteriormente via Registrar um webhook de lote (e não repetido aqui) disparará corretamente seu callback na conclusão, mas este campo ainda retorna false para essa 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 enviar mais documentos para ele — 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 Error Handling.
• batch_not_found — não há 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 que estão sendo enfileirados.

Listar lotes

Retorna uma lista resumida, paginada e filtrável dos seus lotes — o equivalente a "Files Filter" para consumidores de API. Isso retorna apenas resumos (document_count, status agregado); use Get batch results para obter os dados completos por documento de um lote específico.

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Error Handling.
• invalid_parameter — mode, limit, status ou page_token inválidos.

Obter status do lote

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

Parâmetros

Erros possíveis

• missing_api_key / invalid_api_key / plan_required — consulte Error Handling.
• batch_not_found

Obter resultados do lote

A principal forma de recuperar dados extraídos. Cada documento no lote é retornado com seus line_items reformatados — uma matriz de objetos {field_name: value}, um por linha extraída. Valores em nível de campo são escalares simples por padrão (uma string, número, etc.).

Parâmetros

?include=bbox lê apenas resultados preenchidos retroativamente — não chama Trigger bbox annotation por você. Se bbox nunca foi acionado para um documento (manualmente ou via 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 que o modelo localize 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 busca (veja Get a document's image) 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 e não uma escala de 0–1000. Consulte o guia Bounding Boxes para a ressalva de precisão — essas coordenadas vêm diretamente do modelo sem etapa de verificação em nível de pixel, então 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 em torno do qual esta API é construída; este endpoint existe para extrair os mesmos dados para uma planilha sem escrever código de reformatação você mesmo. Apenas xlsx — v1 só suporta o modo tabela (extract), e a exportação Word (docx) no aplicativo principal é exclusivamente a saída nativa do modo page_word (um prompt e formato de resultado completamente diferentes), que v1 não expõe. Não há opção de "dados de tabela como documento Word" aqui. Uma diferença comportamental que vale saber: se o modelo do lote tiver mesclagem de várias páginas configurada, este endpoint sempre a aplica — ao contrário de results, não há parâmetro de consulta para desativar aqui, pois um download de planilha não tem preocupação de compatibilidade com integrações existentes a preservar.

Parâmetros

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

Erros possíveis

• 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 trabalhos de anotação de bbox vinculados aos seus documentos.

Parâmetros

Erros possíveis

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