Autenticación
Todas las rutas bajo https://ocr.789.com.mx/v1 requieren autenticación por API Key.
Header obligatorio
X-API-Key: ocr_live_xxxxxxxxxxxxxxxx
Accept: application/json
Headers recomendados
| Header | Obligatorio | Descripción |
|---|---|---|
X-API-Key |
Sí | Credencial emitida por el equipo de plataforma |
Accept |
Sí | application/json |
Idempotency-Key |
En POST /documents y POST /extractions |
UUID único por operación de creación (16–191 caracteres) |
X-Request-ID |
No | ID para correlacionar logs con tu sistema. Solo A-Z a-z 0-9 . _ -, máximo 64 caracteres; si no cumple, la API genera uno (req_...). Siempre se devuelve en el header X-Request-ID y en meta.request_id. |
Idempotencia
En POST /documents y POST /extractions envía un Idempotency-Key único (ej. UUID v4). Sin él, o con menos de 16 caracteres, la API responde 422 validation_error (error.details.idempotency_key).
Si repites la misma key con el mismo payload, no se duplica el recurso: recibes 200 (no 202) con el mismo recurso y meta.idempotent_replay: true. Si repites la key con un payload distinto recibes 409 idempotency_conflict.
Límite de peticiones
Cada API Key puede hacer hasta 120 peticiones por minuto. Al superarlo la API responde 429 rate_limit_exceeded con los headers Retry-After y X-RateLimit-*; espera lo que indica Retry-After antes de reintentar.
Scopes
| Scope | Permite |
|---|---|
documents:create |
Crear y cancelar documentos |
documents:read |
Listar y consultar documentos |
results:read |
Descargar resultado OCR |
extractions:create |
Crear extracciones |
extractions:read |
Consultar extracciones y resultados |
usage:read |
Consultar el consumo del proyecto (GET /usage) |
Errores de autenticación
| HTTP | Código | Causa |
|---|---|---|
| 401 | invalid_api_key |
Key ausente o incorrecta |
| 403 | api_key_not_active |
Key suspendida, revocada o expirada, o su proyecto o ambiente está inactivo |
| 403 | insufficient_scope |
Key sin permiso para el endpoint |
Ver Errores comunes para más detalle.