Documentos

Un Documento es una página procesada individual: una imagen cargada, o una página renderizada a partir de un PDF cargado. Cada Documento pertenece a un Lote (identificado por batch_name), que es la unidad que realmente se inicia para procesar. Cargar un PDF de varias páginas crea un Documento por página en el mismo lote; consulte Cargar un documento a continuación.

Cargar un documento

Carga un único archivo (imagen o PDF) en un lote. Si se omite batch_name, se genera automáticamente uno y se devuelve en la respuesta. La carga no inicia la extracción; llame a Iniciar procesamiento de un lote una vez que haya cargado todo lo que desea procesar junto. El remaining_batch_capacity de la respuesta le indica cuántos documentos más puede aceptar este lote antes de alcanzar el tamaño máximo de lote de su plan (consulte Cuenta max_batch_size), útil para decidir del lado del cliente si seguir añadiendo a este lote o iniciar uno nuevo, sin necesidad de una consulta adicional.

POST /api/v1/documents

Parámetros

Nombre	Ubicación	Tipo	Descripción
`file`	cuerpo (multipart)	archivo	Obligatorio a menos que se proporcione `url`. Una imagen (JPEG/PNG/etc.) o un PDF. Los PDF están limitados a 30 páginas por carga y se dividen en un Documento por página.
`url`	cuerpo (multipart)	cadena, opcional	Alternativa a `file` — el servidor descarga el archivo desde esta URL en lugar de que usted lo adjunte. Mutuamente excluyente con `file`; pase exactamente uno. Debe ser una URL pública `http://` o `https://` (sin direcciones localhost/red privada); la descarga está limitada a 30 MB con un tiempo de espera de lectura de 15 segundos.
`batch_name`	cuerpo (multipart)	cadena, opcional	Lote al que agregar este documento. Omita para generar automáticamente un nuevo nombre de lote (devuelto en la respuesta). Reutilice el mismo valor en varias cargas para acumular un lote antes de procesarlo.
`template_id`	cuerpo (multipart)	entero, opcional	Un ID de Plantilla perteneciente a su cuenta para preasociar con este documento. No es obligatorio — también puede pasar una plantilla (o campos ad-hoc) cuando llame a `process`.
`password`	cuerpo (multipart)	cadena, opcional	Solo para PDF. Se prueba primero si el archivo está protegido por contraseña. Si se omite, o si no desbloquea el archivo, recurre a las contraseñas guardadas en la configuración de Email Inbox de su cuenta — este campo no requiere que tenga configurado Email Inbox, es solo una alternativa por llamada.
`Idempotency-Key`	encabezado, opcional	cadena	Seguro de reintentar. Consulte Idempotencia.

Las cargas de PDF devuelven un arreglo, no un solo ID. Al cargar un PDF, cada página se convierte en su propio Documento y el document_id de la respuesta se convierte en un arreglo JSON (una cadena por página, en orden de página), más un campo page_count. Una carga de imagen única devuelve una cadena escalar. El código cliente que asume que document_id siempre es una cadena fallará con una carga de PDF — verifique si el archivo que envía es un PDF y bifurque según la forma de la respuesta, o envíe siempre imágenes y nunca dependa del caso escalar. Consulte los dos ejemplos de respuesta a la derecha.

Posibles errores

missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
missing_parameter — no se envió ni file ni url.
invalid_parameter (param: "file") — imagen o PDF inválido o corrupto, PDF protegido con contraseña que no pudo desbloquearse (no funcionó ni el campo password ni ninguna contraseña guardada de Email Inbox), o PDF que supera el límite de 30 páginas.
invalid_parameter (param: "url") — se enviaron tanto file como url, la URL no resuelve a una dirección pública, la descarga falló o expiró, o el archivo descargado supera los 30 MB.
invalid_parameter (param: "batch_name") — el lote ya alcanzó el tamaño máximo de lote de su plan.
invalid_parameter (param: "template_id") o template_not_found.
rate_limit_exceeded — ya hay demasiados documentos no procesados (en cola) en la cuenta; procese o elimine algunos primero.

Obtener un documento

Obtiene el estado actual de un solo documento y, una vez que la extracción se haya completado con éxito, sus line_items reestructurados. Es el equivalente para un solo documento de Obtener resultados del lote — mismas reglas de reestructuración, pero sin la opción ?include=bbox (disponible solo en el endpoint de resultados a nivel de lote).

GET /api/v1/documents/{document_id}

Parámetros

Nombre	Ubicación	Tipo	Descripción
`document_id`	ruta	string	El ID del documento devuelto por `POST /documents` (o una entrada de ese arreglo, para una página de PDF).

status siempre es uno de queued, processing, succeeded, failed, canceled — consulte la guía del Modelo asíncrono para conocer la máquina de estados. completed_at se establece cuando el documento alcanza un estado terminal (succeeded, failed o canceled) y permanece null antes de eso.

Posibles errores

missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
document_not_found — no existe un documento con este ID en su cuenta.

Obtener la imagen de un documento

Devuelve la imagen de la página detrás de un documento — la página completa por defecto, o un recorte normalizado de la misma con ?crop=. Esto es lo que alimenta image_url en los campos de ubicación pura (consulte Obtener resultados del lote), pero también puede llamarlo directamente con sus propias coordenadas.

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

Parámetros

Nombre	Ubicación	Tipo	Descripción
`document_id`	ruta	string	El ID del documento.
`crop`	consulta, opcional	string	`"x1,y1,x2,y2"` — cuatro flotantes entre 0 y 1, misma convención de coordenadas normalizadas que cualquier objeto `bbox` en la API. Omítalo para obtener la imagen de página completa sin recortar.

La respuesta son los bytes de la imagen sin procesar (Content-Type: image/jpeg), no JSON — no hay ejemplo de respuesta JSON a la derecha para este endpoint, solo la solicitud.

Posibles errores

missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
document_not_found — no existe un documento con este ID, o el archivo de imagen original ya no está disponible (p. ej., ha superado la ventana de retención de eliminación automática de su cuenta).
invalid_parameter (param: "crop") — valor de crop mal formado, coordenadas fuera del rango 0–1, o una región de recorte que queda vacía después de ajustarse a los límites de la imagen.

Activar anotación de bbox

Inicia explícitamente el trabajo opcional (de pago) de segunda pasada que localiza dónde se encuentra físicamente en la página el valor de cada campo extraído. Esta es una acción facturable independiente de la extracción; consulte la guía Bounding Boxes antes de integrarla, especialmente la nota sobre la configuración auto_annotate_bbox de su cuenta, que podría activar (y facturar) este mismo trabajo automáticamente sin que usted llame a este endpoint.

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

Parámetros

Nombre	Ubicación	Tipo	Descripción
`document_id`	ruta	string	Debe ser un documento `succeeded` con datos extraídos; no se puede anotar un documento cuya extracción aún no haya finalizado.
`Idempotency-Key`	encabezado, opcional	string	Recomendado: esta acción consume créditos. Consulte Idempotencia.

Devuelve 202 cuando se acaba de encolar un nuevo trabajo de bbox, o 200 cuando ya se estaba ejecutando un trabajo de bbox para este documento (already_running: true), lo que significa que ya llamó a este mismo endpoint para este documento anteriormente y ese trabajo de bbox aún no ha finalizado. Esto no está relacionado con si la extracción del documento ya finalizó; bbox solo se puede activar en un documento que ya esté succeeded (consulte "Posibles errores" más abajo), por lo que cuando pueda llamar a este endpoint, la extracción ya estará completa. already_running se refiere exclusivamente a un segundo trabajo de bbox para el mismo documento, no al trabajo de extracción. En cualquier caso (202 o 200), no se inicia ni se cobra nada nuevo en la ruta 200; consulte Obtener anotación de bbox con el group_batch_id devuelto para obtener el resultado.

Posibles errores

missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
document_not_found — no hay ningún documento con este ID en su cuenta.
insufficient_credits — no tiene suficientes créditos para ejecutar esta pasada de anotación.
invalid_parameter — el documento aún no está en un estado válido para esto (todavía se está procesando) o no tiene datos extraídos para ubicar los cuadros.

Obtener anotación bbox

Consulta el estado y obtiene los resultados del trabajo de anotación bbox más reciente activado para un documento. Si nunca se ha activado un trabajo para este documento, exists es false y status/group_batch_id son null — esta es una respuesta normal y común (la mayoría de los documentos nunca tienen bbox activado), no un error.

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

Parámetros

Nombre	Ubicación	Tipo	Descripción
`document_id`	ruta	string	El ID del documento.

rows asigna un índice de fila (como cadena, p. ej. "0") a un mapa de nombre de campo → objeto bbox normalizado (o null si no se encontró la ubicación de ese campo en la página). status utiliza la misma enumeración cerrada de 5 valores que en el resto de la API.

Posibles errores

missing_api_key / invalid_api_key / plan_required — consulte Manejo de errores.
document_not_found — no hay ningún documento con este ID en su cuenta.

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 } } }