Batches

Un Batch es un grupo con nombre de uno o más documentos que usted procesa, consulta y cuyos resultados obtiene en conjunto. No crea un batch explícitamente: se crea implícitamente la primera vez que carga un documento con ese batch_name (consulte Upload a document).

Start processing a batch

Inicia la extracción en cada documento elegible que se encuentre actualmente en el batch (cualquier documento que no esté ya en estado processing o succeeded). Este es el endpoint que realmente consume créditos: 1 crédito por documento en cola si su cuenta está en el nivel de modelo Standard, que es el predeterminado con el que toda cuenta comienza. Si a su cuenta se le ha asignado Advanced o Premium en su lugar, cada documento cuesta 3 o 6 créditos respectivamente; el nivel cambia qué modelo ejecuta la extracción, no qué campos se devuelven ni cómo se estructura la respuesta, por lo que nada más del contrato de este endpoint cambia. No hay un parámetro tier en esta solicitud: el nivel de modelo es una configuración a nivel de cuenta que asigna el equipo de ImageToTable.ai, no algo que el llamante elige por batch. El nivel vigente en el momento en que se llama a este endpoint es el que se cobra, y permanece bloqueado para los documentos que ponga en cola aquí, incluso si el nivel de la cuenta cambia antes de que terminen: un batch dividido en múltiples llamadas process puede tener diferentes documentos facturados a distintos niveles si el nivel de la cuenta cambió entre ellas. Consulte Account Settings & API Behavior para la tabla completa de configuraciones, y Account usage para ver cómo se etiqueta una deducción no estándar en su libro de créditos.

Parámetros

quality es la única configuración de cuenta que la API permite anular por llamada; cualquier otra preferencia a nivel de cuenta (auto-anotación de bbox, política de retención) se lee de su cuenta y no se puede anular por solicitud. Consulte Configuración de la cuenta y comportamiento de la API para obtener el panorama completo, incluido por qué auto_annotate_bbox puede significar que esta llamada termine cobrándole también la anotación de bbox, aunque nunca haya llamado a ese endpoint.

El webhook_registered de la respuesta refleja solo esta llamada específica: es true si y solo si esta solicitud incluyó webhook_url, no si el lote tiene un webhook en absoluto. Un lote cuyo webhook se configuró antes mediante Registrar un webhook de lote (y no se repitió aquí) activará correctamente su callback al finalizar, pero este campo seguirá devolviendo false para esa llamada; no verifica si ya existe un BatchWebhook. No trate un false aquí como "no se activará ningún webhook para este lote".

Llamar a este endpoint nuevamente en un lote que ya procesó y del que fue notificado, después de cargar más documentos en él, reactiva automáticamente el webhook de ese lote si ya se había activado, de modo que la finalización de la nueva tanda también notifique. No se necesita ninguna llamada adicional para que esto ocurra; consulte la sección "Reprocesamiento de un lote" de la guía de Webhooks para conocer la semántica exacta (incluido qué sucede si dos tandas se superponen).

Posibles errores

• missing_api_key / invalid_api_key / plan_required — consulte Error Handling.
• batch_not_found — no existen documentos bajo este batch_name en su cuenta.
• invalid_parameter — valor incorrecto de quality/webhook_url/template_id, o no hay documentos en el lote actualmente elegibles para procesamiento (todos ya completados/en procesamiento, o el lote está vacío).
• template_not_found
• insufficient_credits — no hay suficientes créditos disponibles para cubrir los documentos en cola.

List batches

Devuelve una lista resumida, paginada y filtrable de sus lotes: el equivalente a "Files Filter" para consumidores de la API. Esto devuelve solo resúmenes (document_count, status agregado); use Get batch results para los datos completos por documento de un lote específico.

Parámetros

Errores posibles

• missing_api_key / invalid_api_key / plan_required — consulte Manejo de Errores.
• invalid_parameter — mode, limit, status o page_token no válidos.

Obtener estado del lote

Estado agregado ligero para un lote: recuentos por estado público más una marca all_done, útil para un bucle de sondeo económico que aún no necesite la carga completa de resultados.

Parámetros

Errores posibles

• missing_api_key / invalid_api_key / plan_required — consulte Manejo de Errores.
• batch_not_found

Obtener resultados del lote

La forma principal de recuperar los datos extraídos. Cada documento del lote se devuelve con sus line_items reorganizados: un arreglo de objetos {field_name: value}, uno por fila extraída. Los valores a nivel de campo son escalares simples de forma predeterminada (una cadena, un número, etc.).

Parámetros

?include=bbox lee solo resultados ya calculados — no llama a Activar anotación de bbox por usted. Si bbox nunca se activó para un documento (manual o mediante el ajuste auto_annotate_bbox de su cuenta), los campos de ese documento simplemente se devuelven con "bbox": null.

Los campos de solo ubicación son una tercera forma distinta. Algunos campos de plantilla piden al modelo localizar algo en lugar de transcribir texto (p. ej., "localice la foto del retrato"). Para esos campos, el valor completo es una ubicación — por lo tanto, en lugar de un escalar o el par {"value","bbox"} anterior, obtiene {"type": "image_region", "bbox": {...}, "image_url": "..."}, independientemente de si ?include=bbox se definió — la caja no es metadatos opcionales aquí, es el único contenido del campo. image_url apunta a un JPEG recortado listo para descargar (consulte Obtener la imagen de un documento) para no tener que recortar el original usted mismo a partir de cuatro números.

Cada objeto bbox — en cualquiera de sus formas — usa "unit": "normalized": las coordenadas son flotantes de 0 a 1 relativas al ancho/alto de la página, no píxeles ni una escala de 0 a 1000. Consulte la guía de Bounding Boxes para conocer la advertencia de precisión: estas coordenadas provienen directamente del modelo sin un paso de verificación a nivel de píxel, así que trátelas como "aproximadas" en lugar de exactas en documentos densos o complejos.

Errores posibles

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

Export a batch

Una descarga de conveniencia: results arriba es el formato canónico y estructurado en torno al cual se construye esta API; este endpoint existe para llevar los mismos datos a una hoja de cálculo sin escribir código de reestructuración usted mismo. Solo xlsx: v1 solo admite el modo tabla (extracción), y la exportación a Word (docx) en la aplicación principal es exclusivamente la salida nativa del modo page_word (un prompt y una forma de resultado completamente diferentes), que v1 no expone. No hay una opción de "datos de tabla como documento de Word" aquí. Una diferencia de comportamiento que vale la pena conocer: si la plantilla del lote tiene fusión de varias páginas configurada, este endpoint siempre la aplica — a diferencia de results, no hay un parámetro de consulta de exclusión aquí, ya que una descarga de hoja de cálculo no tiene una preocupación de compatibilidad con integraciones existentes que preservar.

Parámetros

La respuesta es una descarga de archivo (Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet), no JSON — no hay un ejemplo de respuesta JSON para este endpoint.

Posibles errores

• missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
• batch_not_found
• invalid_parameter (param: "format") — cualquier valor distinto de xlsx.

Eliminar un lote

Elimina permanentemente todos los documentos del lote. Cualquier documento que siga en estado queued se reembolsa antes de la eliminación. Esto también elimina el registro del webhook del lote (si existe) y cualquier trabajo de anotación de bbox vinculado a sus documentos.

Parámetros

Posibles errores

• missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
• batch_not_found — a diferencia de otros recursos, eliminar un batch_name que no le pertenece (o que no existe) devuelve un 404 aquí, no una operación silenciosa sin efecto.