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 sobre la que realmente se inicia el procesamiento. 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, PDF, Word o texto plano) en un lote. Si se omite batch_name, se genera uno automáticamente 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 campo 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.), un PDF, un documento de Word (solo `.docx` — el formato binario heredado `.doc` no es compatible; guárdelo como `.docx` primero) o un archivo de texto plano (`.txt`). Los PDF están limitados a 50 páginas por carga y se dividen en un Documento por página; los archivos `.docx`/`.txt` se convierten primero a PDF en el servidor y luego siguen esa misma división 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`; proporcione 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. Omítalo 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 propiedad de su cuenta para asociar previamente 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 PDF. Se intenta primero si el archivo está protegido por contraseña. Si se omite, o si no desbloquea el archivo, recurre a cualquier contraseña ya guardada 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 (y Word/texto convertidos) 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 .docx/.txt que se convierta en más de una página se comporta de manera idéntica, ya que se divide por la misma ruta de código una vez que la conversión produce bytes de PDF. Una carga de una sola imagen devuelve una cadena escalar. El código cliente que asume que document_id siempre es una cadena fallará en una carga de varias páginas; verifique si el archivo que envía podría producir más de una página 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/a o corrupto/a, un PDF protegido por contraseña que no pudo desbloquearse (ni el campo password ni ninguna contraseña guardada del Email Inbox funcionó), un PDF que supera el límite de 50 páginas, o un archivo .docx/.txt que no pudo convertirse (incluyendo un archivo .doc heredado — no compatible, guárdelo como .docx primero).
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 haya sido exitosa, sus line_items reorganizados. Es el equivalente de un solo documento de Obtener resultados del lote — mismas reglas de reorganizació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 la máquina de estados. completed_at se establece una vez que 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 hay ningún documento con este ID en su cuenta.

Obtener la imagen de un documento

Devuelve la imagen de página de un documento: la página completa por defecto, un recorte normalizado de la misma con ?crop=, o una miniatura pregenerada más pequeña con ?size=thumb para una carga más rápida en listas/cuadrículas. ?crop= alimenta image_url en campos de solo ubicación (consulte Obtener resultados de 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 el resto de la API. Omita para obtener la imagen de página completa sin recortar.
`size`	consulta, opcional	string	Pase `thumb` para obtener una versión pregenerada más pequeña en lugar de la página a resolución completa. Se ignora si también se proporciona `crop`. Vuelve a la imagen completa si no se generó ninguna miniatura para este documento (las imágenes pequeñas no siempre merecen una miniatura) — nunca es un error.

La respuesta son los bytes de 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 (por ejemplo, superó el período 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 bbox

Inicia explícitamente el trabajo opcional, de pago, de segunda pasada que localiza dónde se encuentra físicamente cada valor de campo extraído en la página. Esta es una acción facturable independiente de la extracción en sí; consulte la guía de 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 con estado `succeeded` y datos extraídos; no se puede anotar un Documento que aún no haya finalizado la extracción.
`Idempotency-Key`	encabezado, opcional	string	Recomendado: esta acción consume créditos. Consulte Clave de idempotencia.

Devuelve 202 cuando se acaba de encolar un nuevo trabajo bbox, o 200 cuando ya se está ejecutando un trabajo bbox para este Documento (already_running: true), lo que significa que ya llamó a este mismo endpoint para este Documento anteriormente y ese trabajo bbox anterior aún no ha finalizado. Esto no está relacionado con si la extracción del Documento en sí ha finalizado; bbox solo se puede activar en un Documento que ya esté en estado 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 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 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 } } }