Flujo: extracción

La extracción toma el output OCR de un documento y devuelve JSON validado según tu schema.

¿Primera vez escribiendo instrucciones y schemas? Lee la Guía de prompts y schemas: reglas, plantillas por tipo de documento y solución de errores.

Resumen

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

Cada extracción referencia un solo document_id.

Modos de integración

Modo A — Secuencial (recomendado para empezar)

1. Subir documento.
2. Esperar status: completed.
3. Crear extracción.
4. Leer resultado.

Modo B — Paralelo (optimizado)

1. Subir documento.
2. Crear extracción de inmediato.
3. La extracción queda en waiting_for_document hasta que el OCR termine.
4. Se encola automáticamente y procesa sin un segundo POST.
5. Si el OCR falla o no genera el formato que pediste, la extracción pasa a failed con extraction_input_unavailable.

1. Crear extracción

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

Content-Type: application/json

{
  "document_id": "doc_01J...",
  "custom_instruction": "Factura mexicana. Fechas en formato YYYY-MM-DD. Montos como número decimal sin símbolo de moneda.",
  "response_schema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["supplier_name", "invoice_number", "invoice_date", "total"],
    "properties": {
      "supplier_name": { "type": ["string", "null"], "description": "Nombre o razón social del emisor." },
      "invoice_number": { "type": ["string", "null"] },
      "invoice_date": { "type": ["string", "null"], "description": "Formato YYYY-MM-DD." },
      "total": { "type": ["number", "null"], "description": "Total a pagar con impuestos." }
    }
  },
  "input_result_type": "markdown"
}

Headers:

X-API-Key: tu_api_key
Idempotency-Key: 660e8400-e29b-41d4-a716-446655440001
Content-Type: application/json

Idempotency-Key es obligatorio (16–191 caracteres).

Respuesta (202):

{
  "data": {
    "id": "ext_01J...",
    "document_id": "doc_01J...",
    "status": "queued",
    "input_result_type": "markdown",
    "created_at": "2026-06-24T18:01:00+00:00"
  },
  "meta": { "request_id": "req_01J..." }
}

status es waiting_for_document si el OCR del documento sigue en curso (modo B). Si repites el POST con la misma Idempotency-Key y el mismo payload recibes 200 con la misma extracción y meta.idempotent_replay: true.

Si el schema es inválido recibes 422 validation_error con los problemas en error.details.response_schema.

2. Consultar estado

GET https://ocr.789.com.mx/v1/extractions/{extraction_id} — scope extractions:read

Respuesta (200):

{
  "data": {
    "id": "ext_01J...",
    "document_id": "doc_01J...",
    "status": "validation_failed",
    "input_result_type": "markdown",
    "created_at": "2026-06-24T18:01:00+00:00",
    "failure": {
      "code": "schema_validation_failed",
      "message": "The extraction response could not be validated against the requested schema.",
      "validation_errors": ["$.total: is required."]
    },
    "started_at": "2026-06-24T18:01:02+00:00",
    "completed_at": "2026-06-24T18:01:20+00:00"
  },
  "meta": { "request_id": "req_01J..." }
}

failure es null salvo en failed y validation_failed. validation_errors solo aparece con schema_validation_failed.

3. Obtener resultado

GET https://ocr.789.com.mx/v1/extractions/{extraction_id}/result — scope extractions:read

Solo cuando status es completed; en cualquier otro estado recibes 409 result_not_ready. El JSON extraído está en data.result:

{
  "data": {
    "extraction_id": "ext_01J...",
    "document_id": "doc_01J...",
    "result": {
      "supplier_name": "ACME SA DE CV",
      "invoice_number": "A-1024",
      "invoice_date": "2026-06-24",
      "total": 11600.0
    },
    "completed_at": "2026-06-24T18:01:09+00:00"
  }
}

Reglas importantes

• El documento debe haberse creado con la misma API Key.
• Documentos en failed, cancelled, expired o purged no son extraíbles (409 document_not_extractable). Tampoco un documento terminado que no generó el input_result_type pedido ni ningún otro formato utilizable.
• Documentos en queued, submitting_to_docling o processing sí se aceptan: la extracción espera en waiting_for_document (modo B).
• custom_instruction describe qué extraer; la plataforma ya agrega reglas de sistema (solo JSON, no inventar, null si falta). Ver Guía de prompts y schemas.
• response_schema define la forma exacta del JSON de salida.
• Puedes crear varias extracciones sobre el mismo documento (cada una con su Idempotency-Key).