Flujo: documento OCR

Resumen

POST /documents  →  polling GET /documents/{id}  →  GET /documents/{id}/result

El procesamiento es asíncrono. Tras el POST recibes 202 con status: queued.

1. Crear documento

POST https://ocr.789.com.mx/v1/documents — scope documents:create

Content-Type: multipart/form-data

Tipos de archivo aceptados: PDF, JPEG, PNG, HEIC/HEIF, TXT y XML. La extensión debe coincidir con el contenido real (415 unsupported_media_type si no).

Límites en los perfiles actuales: 50 MB (413 file_too_large) y 100 páginas (422 validation_error). Tu API Key o ambiente pueden tener un límite menor; aplica el más bajo.

Headers:

X-API-Key: tu_api_key
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Respuesta (202):

{
  "data": {
    "id": "doc_01J...",
    "status": "queued",
    "profile": "cfdi_invoice",
    "output_formats": ["markdown", "json"],
    "external_reference": "pedido-1024",
    "created_at": "2026-06-24T18:00:00+00:00"
  },
  "meta": { "request_id": "req_01J..." }
}

Si repites el POST con la misma Idempotency-Key y el mismo payload recibes 200 con el mismo documento y meta.idempotent_replay: true.

2. Consultar estado

GET https://ocr.789.com.mx/v1/documents/{document_id} — scope documents:read

Repite hasta que status sea terminal:

No necesitas vigilar el documento indefinidamente: si se atasca, la plataforma lo pasa a failed sola (ver códigos abajo).

Respuesta (200):

{
  "data": {
    "id": "doc_01J...",
    "status": "completed",
    "profile": "cfdi_invoice",
    "original_filename": "factura.pdf",
    "detected_mime_type": "application/pdf",
    "size_bytes": 184320,
    "page_count": 2,
    "external_reference": "pedido-1024",
    "created_at": "2026-06-24T18:00:00+00:00",
    "requested_outputs": ["markdown", "json"],
    "available_outputs": ["markdown", "json"],
    "failure": null,
    "warnings": [],
    "started_at": "2026-06-24T18:00:02+00:00",
    "completed_at": "2026-06-24T18:00:41+00:00",
    "expires_at": "2026-07-24T18:00:00+00:00"
  },
  "meta": { "request_id": "req_01J..." }
}

Cuando status es failed, failure trae { "code": "...", "message": "..." }:

Ante un failed puedes subir el documento de nuevo con una Idempotency-Key nueva. Si se repite con el mismo archivo, reporta el meta.request_id al equipo de plataforma.

Listar documentos

GET https://ocr.789.com.mx/v1/documents — scope documents:read

Filtros opcionales (query): status, profile, external_reference, created_from, created_to (fechas), page y per_page (por defecto 25, máx. 100). Solo lista los documentos creados con tu API Key, del más reciente al más antiguo. La paginación viene en meta.pagination (page, per_page, total, last_page).

3. Obtener resultado OCR

GET https://ocr.789.com.mx/v1/documents/{document_id}/result — scope results:read

Disponible cuando el documento está en completed o partial_success.

Inline (download=false):

{
  "data": {
    "document_id": "doc_01J...",
    "format": "markdown",
    "content": "# Factura ...",
    "generated_at": "2026-06-24T18:00:41+00:00"
  },
  "meta": { "request_id": "req_01J..." }
}

Descarga (download=true): data trae document_id, format, download_url y expires_at (la URL vale 10 minutos).

4. Cancelar (opcional)

POST https://ocr.789.com.mx/v1/documents/{document_id}/cancel — scope documents:create

Solo funciona mientras el documento sigue en queued. Responde 200 con { "id", "status": "cancelled", "cancelled_at" }. Si ya se envió a OCR recibes 409 document_cannot_be_cancelled. No requiere Idempotency-Key.

Perfiles disponibles (México)

Usa general_document solo si ningún perfil específico aplica.

Siguiente paso

Flujo: extracción — extraer campos estructurados del OCR.