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 (`.docx` solamente — el formato binario heredado `.doc` no es compatible; guárdelo como `.docx` primero), o un archivo de texto plano (`.txt`). Los PDF tienen un límite de 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 necesite adjuntarlo. Mutuamente excluyente con `file`; proporcione exactamente uno. Debe ser una URL pública `http://` o `https://` (sin direcciones localhost/red privada); la descarga tiene un límite de 30MB con un tiempo de espera de lectura de 15 segundos.
`batch_name`	cuerpo (multipart)	cadena, opcional	Lote al que agregar este documento, hasta 50 caracteres. Omita para generar automáticamente un nuevo nombre de lote (devuelto en la respuesta). Reutilice el mismo valor en varias cargas para crear un lote antes de procesarlo.
`template_id`	cuerpo (multipart)	entero, opcional	Un ID de plantilla perteneciente a su cuenta para asociarlo 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, se recurre a cualquier contraseña ya guardada en la configuración de Email Inbox de su cuenta — este campo no requiere que tenga Email Inbox configurado; es solo una alternativa por llamada.
`Idempotency-Key`	encabezado, opcional	cadena	Seguro de reintentar. Ver Clave de idempotencia.

Las cargas de PDF (y de Word/texto convertidos) devuelven un arreglo, no un ID único. 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), además de un campo page_count — una carga .docx/.txt que se convierte en más de una página se comporta de manera idéntica, ya que se divide por exactamente el mismo camino de código una vez que la conversión produce bytes de PDF. Una carga de imagen única devuelve una cadena escalar. El código de cliente que asume que document_id siempre es una cadena fallará en una carga de varias páginas — verifique si el archivo que está enviando podría producir más de una página y decida según la forma de la respuesta, o envíe siempre imágenes y no 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/corrupto, un PDF protegido con contraseña que no se pudo desbloquear (ni el campo password ni ninguna contraseña guardada de Email Inbox funcionó), un PDF que supera el límite de 50 páginas, o un archivo .docx/.txt que no se pudo convertir (incluido 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 30MB.
invalid_parameter (param: "batch_name") — el lote ya alcanzó el tamaño máximo de lote de su plan, o el nombre supera los 50 caracteres.
invalid_parameter (param: "template_id") o template_not_found.
rate_limit_exceeded — ya hay demasiados documentos sin procesar (en cola) en la cuenta; procese o elimine algunos primero.

Obtener un documento

Obtenga el estado actual de un solo documento y, una vez que la extracción haya tenido éxito, sus line_items reformateados. Este es el equivalente de un solo documento de Obtener resultados del lote — mismas reglas de reformateo, pero sin la opción ?include=bbox (esa solo está 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 array, para una página de PDF).

status siempre es uno de queued, processing, succeeded, failed, canceled — consulte la guía 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 } } }

Primeros pasos

Guías

Referencia de la API

Más

Documentos

Cargar un documento

Parámetros

Posibles errores

Obtener un documento

Parámetros

Posibles errores

Obtener la imagen de un documento

Parámetros

Posibles errores

Activar anotación bbox

Parámetros

Posibles errores

Obtener anotación bbox

Parámetros

Posibles errores