Changelog

Cambios visibles para integradores de la OCR Platform API. Formato basado en Keep a Changelog, versionado SemVer.

[1.5.3] - 2026-10-15

Guía MCP: configuración paso a paso para Claude Code (con alcances), Claude Desktop y claude.ai, Cursor, VS Code, Windsurf y clientes que solo aceptan servidores locales, con una comprobación por cliente.
Guía MCP: prueba de conexión con cURL, prueba de punta a punta desde el asistente y tabla de problemas comunes.
Acceso directo a la guía MCP desde el menú principal de /docs.

Documentación de los códigos failure.code de documentos y extracciones, incluidos extraction_queue_timeout y extraction_processing_timeout.
Documentación de los errores 429 rate_limit_exceeded, 413, 415 y los 404/409 de resultados y cancelación, y del límite de 120 peticiones por minuto por API Key.
Documentación de los estados expired y purged, los campos de respuesta de documentos y extracciones, los filtros y paginación de los listados, y los campos opcionales, tipos y límites de POST /v1/documents.
Guía descargable para IA: secciones de MCP y consumo, header X-Webhook-Event, verificación de firma y versión de la guía.
Ejemplos cURL de listados, cancelación y consumo.

Documentación: un documento solo se puede extraer con la misma API Key que lo creó, no con otra key del mismo proyecto.
Documentación: un replay con la misma Idempotency-Key responde 200 con meta.idempotent_replay: true.
Documentación: format es obligatorio en GET /v1/documents/{id}/result, y document_not_extractable no aplica a documentos en proceso.
Webhooks (documentación): el resultado se consulta en los endpoints /result, son 5 intentos en total (envío + 4 reintentos) y /webhook-test solo registra en un log interno.
GET /v1/usage (documentación): estimated_cost suma reintentos y extracciones fallidas de todos los ambientes del proyecto, y to por defecto es el momento de la consulta.
Portada de /docs: el ejemplo cURL usaba Authorization: Bearer y omitía campos obligatorios.
Ejemplo de errores con Guzzle: el cuerpo trae error.code y error.message.
Colección Postman: agrega el scope usage:read y la variable result_format, y quita el formato html.

GET /v1/usage: estimated_cost usa el precio acordado para tu proyecto cuando existe y, si no, el de cualquier modelo dado de alta en la plataforma; antes solo una lista fija de modelos reportaba costo y el resto quedaba en cero. Los consumos ya registrados no cambian.

Un corte de red o timeout momentáneo con el motor OCR ya no deja el documento en failed: el envío y la consulta de estado se reintentan automáticamente.
Una extracción que falla por un error inesperado ahora pasa de inmediato a failed con failure.code extraction_unexpected_error y dispara extraction.failed; antes quedaba en processing hasta expirar por tiempo.

Las URLs de webhook que apuntan a una IPv6 privada o local (ej. http://[::1]/) ahora se rechazan y no reciben entregas. No requiere acción si tu webhook usa un dominio público.

POST /v1/extractions: response_schema acepta la keyword description (texto) en cualquier campo para dar instrucciones por campo al modelo.
GET /v1/extractions/{id}: cuando failure.code es schema_validation_failed, failure.validation_errors lista los errores del último intento (ej. $.total: is required.).
Servidor MCP público en /mcp para asistentes de IA (Claude Code, Cursor, VS Code): valida custom_instruction y response_schema con las reglas de la API, entrega plantillas por tipo de documento y expone la guía de integración. No requiere API Key ni procesa documentos.
Sección "MCP para asistentes de IA" en la guía de integración, con la configuración por cliente.
Sección "Guía de prompts y schemas": qué agrega la plataforma al prompt, keywords soportadas, límites, plantillas por tipo de documento (CFDI, INE, CSF, comprobante de domicilio) y cómo corregir cada error.

Una lista vacía ([]) en la respuesta del modelo ahora cumple un campo "type": "array"; antes terminaba en validation_failed.
Documentación y guía descargable para IA: los ejemplos de response_schema usaban un formato abreviado ("total": "number|null") que la API rechaza con 422; ahora son JSON Schema válido.
Documentación: el JSON extraído está en data.result de GET /v1/extractions/{id}/result (no en validated_data).

POST /v1/extractions: si omites input_result_type, ahora se elige el primer formato que el documento realmente generó (orden markdown → text → json) en vez de asumir markdown. Antes, un documento sin markdown devolvía 409 document_not_extractable aunque tuviera json o text disponibles. Si envías input_result_type explícito, el comportamiento no cambia.

Webhooks salientes por ambiente: recibe un POST firmado cuando un documento o extracción llega a estado final. Eventos: document.completed, document.partial_success, document.failed, extraction.completed, extraction.failed, extraction.validation_failed.
Firma HMAC-SHA256 en cada entrega (header X-Signature) y header X-Webhook-Event; reintentos automáticos (hasta 5, backoff 30s–1h) y deduplicación por delivery_id.
Receptor de prueba POST /webhook-test para validar la integración de webhooks sin servidor propio.
Sección "Webhooks" en la guía de integración, con ejemplo de verificación de firma.

Endurecimiento interno del almacenamiento de API Keys. No requiere acción: las keys existentes siguen funcionando sin cambios.

Sección "Consumo / Uso" en la guía de integración: cómo consultar tokens, costo estimado y volumen OCR.
Colección Postman actualizada con el endpoint de consumo.

Guía de integración: prerrequisitos, autenticación y referencia de endpoints actualizados con el scope usage:read.

Primera versión etiquetada de la API v1.

Endpoint GET /v1/usage: consumo por proyecto (tokens, costo estimado de extracción y volumen OCR) con filtros from/to. Requiere scope usage:read.
Configuración de proveedor y modelo LLM por proyecto: las extracciones usan la configuración específica del proyecto cuando existe.
Base de la plataforma: subida de documentos OCR, consulta de estado y resultados, extracciones estructuradas con LLM validadas contra schema, autenticación por API Key con scopes e idempotencia.