OCR Platform
Admin

URL base API

https://ocr.789.com.mx/v1

Buenas prácticas de integración

Recomendaciones para integraciones estables con OCR Platform en producción interna.

Polling de estados

El OCR y las extracciones son asíncronos. Tras un POST recibes 202; debes consultar el estado hasta un terminal.

Recurso Intervalo inicial Intervalo máximo Timeout sugerido
Documento OCR 2 s 10 s 35 min
Extracción LLM 2 s 5 s 20 min

Si algo se atasca, la plataforma lo pasa a failed con un failure.code, así que el timeout de tu lado es solo una red de seguridad. En modo paralelo suma el tiempo del OCR al de la extracción.

Usa backoff exponencial (ej. 2 s → 4 s → 8 s, tope 10 s). No hagas polling en bucle tight sin pausa.

Estados terminales de documento: completed, partial_success, failed, cancelled (más adelante, al pasar la retención, expired y purged).

Estados terminales de extracción: completed, validation_failed, failed, cancelled.

Idempotencia

  • Envía Idempotency-Key (UUID v4) en cada POST /documents y POST /extractions.
  • Genera una key nueva por intento de negocio distinto.
  • Reutiliza la misma key solo al reintentar la misma operación (mismo payload): recibes 200 con el recurso original y meta.idempotent_replay: true, sin duplicarlo.
  • Un 409 idempotency_conflict indica misma key con payload diferente — corrige key o payload.

Modo secuencial vs paralelo (extracción)

Modo Cuándo usarlo
Secuencial Primera integración, debugging, documentos grandes
Paralelo Producción: sube documento y crea extracción de inmediato

En modo paralelo la extracción puede quedar en waiting_for_document hasta que el OCR termine. Sigue haciendo polling sobre la extracción; no necesitas un segundo POST.

Manejo de errores

  • Comprueba siempre HTTP status y el cuerpo JSON (error.code, error.message, error.details).
  • Guarda meta.request_id de cada respuesta para reportar incidentes.
  • No reintentes ciegamente 401, 403 o 422 — corrige credenciales o payload.
  • Ante 429 rate_limit_exceeded espera lo que indica Retry-After (límite: 120 peticiones por minuto por key).
  • Para failed o validation_failed, revisa el mensaje y crea un nuevo recurso con nueva Idempotency-Key.

Seguridad

  • La API Key vive solo en backend (secret manager, .env, variables CI).
  • Nunca en frontend, apps móviles ni repositorios.
  • Usa keys de test en desarrollo y live solo en producción.

Ambientes

Cada API Key pertenece a un proyecto y ambiente (test, staging, live). Los recursos creados con una key no son visibles con otra.

Recurso URL
API https://ocr.789.com.mx/v1
Health https://ocr.789.com.mx/health/live

El ambiente lo determina tu API Key (ocr_test_, ocr_staging_, ocr_live_), no la URL. Confirma la URL con el equipo de plataforma si usas otro despliegue.

JSON Schema en extracciones

  • Usa JSON Schema real: raíz "type": "object" y type en cada campo. Para anulables: "type": ["string", "null"] (el formato abreviado "string|null" responde 422).
  • Pon las reglas de formato de cada campo en description y las generales en custom_instruction.
  • Si recibes validation_failed, lee failure.validation_errors en GET /extractions/{id} y ajusta.
  • Un documento debe estar en completed o partial_success antes de extraer (en modo paralelo también se acepta mientras el OCR sigue en curso).
  • Detalle y plantillas: Guía de prompts y schemas.

Checklist de producción

  • Scopes mínimos asignados (no más permisos de los necesarios).
  • Polling con backoff y timeout configurado.
  • Logs con request_id y document_id / extraction_id.
  • Reintentos idempotentes en uploads y extracciones.
  • Health check (https://ocr.789.com.mx/health/live) en monitorización.

Siguiente paso