Documentación de la API de myocr.app

Visión general

La API de myocr.app convierte archivos de documentos (PDF, JPG, PNG, WEBP, GIF, BMP, TIFF) en Excel estructurado, CSV, texto o JSON. Envías un archivo y el nombre de un modelo; ejecutamos OCR y análisis de diseño y devolvemos un resultado limpio.

Cada solicitud se autentica con una API key en la cabecera X-API-Key. Las respuestas usan un envoltorio JSON predecible y cada llamada devuelve un request_id útil para soporte y depuración.

Usa el endpoint síncrono para archivos pequeños que necesitas al instante, y el endpoint asíncrono de trabajos (con webhook opcional) para archivos grandes o gran volumen.

Autenticación

Autentica cada solicitud con la cabecera X-API-Key. Crea y gestiona las claves desde tu panel en /account/api. Para emitir una clave live se requiere una tarjeta de pago verificada (antiabuso). ¿Aún sin tarjeta? Crea una clave de prueba gratuita desde el mismo panel: 5 páginas en total, 5 solicitudes/minuto, solo POST /v1/convert — resultados completos y reales, perfecta para una primera integración.

Existen dos tipos de clave: las de prueba (prefijo sk_test_) usan la misma canalización sin consumir cuota de pago cuando aplica, y las live (prefijo sk_live_) para producción. Mantén las claves en secreto y en el servidor — nunca las incluyas en código del cliente.

Los endpoints de gestión de claves (/v1/keys) usan la sesión web de tu inicio de sesión, no la API key.

curl https://api.myocr.app/v1/status \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
print(client.status())

const res = await fetch("https://api.myocr.app/v1/status", {
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" }
});
console.log(await res.json());

Inicio rápido

Convierte tu primer documento en menos de un minuto. Consigue una clave en el panel y envía una solicitud multipart con tu archivo y el modelo que quieras.

El ejemplo siguiente convierte cualquier PDF o imagen con tablas en una hoja .xlsx y la guarda en out.xlsx.

curl -X POST https://api.myocr.app/v1/convert \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F "model=tables" \
  -o out.xlsx

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
result = client.convert("invoice.pdf", model="tables")
result.save("out.xlsx")

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
form.append("model", "tables");

const res = await fetch("https://api.myocr.app/v1/convert", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" },
  body: form,
});
fs.writeFileSync("out.xlsx", Buffer.from(await res.arrayBuffer()));

Conversión síncrona

POST /v1/convert acepta un único archivo (máx. 5 MB, máx. 10 páginas) y devuelve el archivo resultante directamente en el cuerpo de la respuesta — un .xlsx por defecto, o texto/JSON/CSV si defines el parámetro output.

Es el mejor endpoint cuando necesitas la respuesta de inmediato. Para archivos grandes o lotes, usa trabajos asíncronos.

Parámetros

Trabajos asíncronos

Para archivos de hasta 50 MB (y PDFs de hasta 500 páginas) o mayor rendimiento, crea un trabajo con POST /v1/jobs. La llamada devuelve un request_id de inmediato; el archivo se procesa en segundo plano. Los PDFs por encima del límite de páginas se rechazan al instante con TOO_MANY_PAGES — divide el documento.

Consulta GET /v1/jobs/{request_id} para el estado (pending → processing → done/failed) y luego descarga el resultado en GET /v1/jobs/{request_id}/result. Indica un webhook_url para recibir aviso automático al terminar, sin sondeo.

# 1. create the job
curl -X POST https://api.myocr.app/v1/jobs \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@statement.pdf" -F "model=bank_statement"
# → {"success": true, "data": {"request_id": "abcd1234"}}

# 2. poll status, then download the result
curl https://api.myocr.app/v1/jobs/abcd1234 -H "X-API-Key: sk_live_xxxxxxxxxxxx"
curl https://api.myocr.app/v1/jobs/abcd1234/result -H "X-API-Key: sk_live_xxxxxxxxxxxx" -o out.xlsx

job = client.create_job("statement.pdf", model="bank_statement")
job.wait()                     # polls with backoff until done
job.result().save("out.xlsx")

Conversión por lotes

POST /v1/batch acepta de 1 a 20 archivos en una sola solicitud multipart, todos procesados con el mismo modelo. Cada archivo se informa de forma independiente; los fallos por archivo se devuelven en un array errors sin hacer fallar todo el lote.

curl -X POST https://api.myocr.app/v1/batch \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.jpg" \
  -F "model=invoice"

Modelos

Pasa uno de estos valores model. tables y text usan nuestro motor OCR; los modelos especializados devuelven campos específicos del dominio.

PDF mixtos: a menudo una factura va seguida de anexos de detalle — registros de llamadas, resúmenes por línea, desgloses — que repiten las mismas cabeceras de columna. Dale a cada modelo solo las páginas que necesita, con page_range.

invoice en la página de la factura (normalmente la primera) devuelve número, fechas, totales e IVA; tables en las páginas del anexo devuelve el detalle línea por línea. Dos llamadas, dos archivos limpios, y las páginas excluidas no se facturan.

# invoice header from page 1, call detail from pages 3 onwards
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=invoice" -F "page_range=1" -o header.xlsx
curl -X POST https://api.myocr.app/v1/convert -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@bill.pdf" -F "model=tables" -F "page_range=3-" -o detail.xlsx

Formatos de salida

Define el parámetro output para elegir el formato: xlsx (por defecto, hoja estructurada), txt (texto plano), json (campos extraídos como JSON) o csv. El modelo text siempre devuelve txt.

Para model=bank_statement también puedes definir output como csv_quickbooks (CSV de 4 columnas para importación bancaria), csv_xero (plantilla de importación de Xero) u ofx (archivo OFX estándar para la mayoría del software contable). Con output=json la respuesta incluye además un objeto reconciliation: saldos inicial/final, total de créditos y débitos, la diferencia calculada y ok=true cuando las transacciones extraídas cuadran con los saldos del extracto.

Respuestas y cabeceras

Las respuestas JSON siguen un envoltorio fijo: un booleano success, un objeto data (o un objeto error) y un request_id. Las respuestas de archivo devuelven el binario directamente con el Content-Type adecuado.

Cada respuesta incluye la cabecera X-MyOCR-Request-Id. Las respuestas de archivo también incluyen X-MyOCR-Pages-Used (páginas facturadas) y X-MyOCR-Model (el modelo usado).

Una respuesta puede incluir además un array warnings: un campo opcional y añadido, que nunca cambia el resultado. Hoy el único caso es PAGE_RANGE_SUGGESTED, devuelto cuando a un modelo que describe un solo documento (invoice, receipt, business_card) se le pasa un PDF de más de tres páginas sin page_range, que suele significar que los anexos de detalle se están mezclando con el documento. Las respuestas de archivo llevan el código en la cabecera X-MyOCR-Warning, al no tener cuerpo JSON.

{
  "success": true,
  "data": { "request_id": "abcd1234" },
  "request_id": "abcd1234"
}

Errores

Los errores devuelven success: false con un error.code y un error.message legible, más el request_id. Usa el code (estable) para la lógica y el message (puede cambiar) para las personas.

Límites y cuota

Los límites de tasa se aplican por API key (no por IP), así los clientes tras un proxy compartido no comparten el límite: /v1/convert 60 req/min, /v1/jobs 120 req/min, /v1/batch 30 req/min.

Facturación por página, no por llamada. Planes: Free 10 páginas en total (única vez, tarjeta requerida), Starter €29/mes (2.500), Pro €99/mes (10.000), Scale €190/mes (20.000). El servicio nunca se interrumpe: al agotar las páginas del mes te avisamos por email y cargamos un paquete extra al precio por página de tu plan — Starter 500 a €0,0116, Pro 2.000 a €0,0099, Scale 4.000 a €0,0095 — hasta un tope mensual de recarga que tú defines (y puedes desactivar). Alcanzado el tope la API devuelve 402 con un upgrade_url. Consulta el uso con GET /v1/usage.

Webhooks

Cuando pasas un webhook_url a /v1/jobs, enviamos una POST con payload JSON a esa URL cuando el trabajo llega a done o failed. Las entregas se reintentan con backoff si fallan.

Cada entrega va firmada: verifica la cabecera de firma con tu webhook signing secret (visible en el panel) para confirmar que la solicitud viene realmente de myocr.app. El SDK de Python incluye el helper verify_webhook_signature.

SDK

El SDK oficial de Python (myocr-client) envuelve cada endpoint con métodos y excepciones tipados, sondeo automático Job.wait() con backoff y verificación de firma de webhook.

¿Prefieres HTTP directo? Sirve cualquier cliente HTTP — mira los ejemplos cURL y Node de esta guía y la referencia interactiva completa.

pip install myocr-client

Spec OpenAPI