Docs
EN

Objetivo

Permite que MexCep extraiga los campos del comprobante SPEI desde una imagen y valide la transferencia contra el CEP de Banxico — sin que necesites parsear el comprobante manualmente. El registro de validación resultante es idéntico al de POST /v1/validate; puedes descargar el certificado CEP y activar reintentos de la misma manera.

Requisitos previos

  • Una API key activa (mxcep_…) con el permiso validations_ocr:create.
  • Una imagen de comprobante en formato JPEG, PNG o WebP, de menos de 20 MB.
  • La imagen debe contener un comprobante SPEI legible. Los números de cuenta enmascarados se resuelven contra tu lista de beneficiarios registrados cuando la forma enmascarada coincide con una cuenta registrada.

Pasos

1. Enviar el comprobante

Envía la imagen como cadena en base64 en el campo image, o pasa una URL pública en image_url. Opcionalmente puedes proporcionar cuenta_beneficiaria como pista de desambiguación cuando la imagen muestra una cuenta enmascarada.

Opción A — URL remota:

curl -X POST 'https://api.example.com/v1/validate-ocr' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "https://storage.example.com/comprobantes/spei-001.png",
    "playground": false
  }'

Opción B — imagen en base64:

curl -X POST 'https://api.example.com/v1/validate-ocr' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "image": "<bytes-imagen-en-base64>",
    "playground": false
  }'

Respuesta síncrona 200 — el OCR extrajo los campos y Banxico respondió en banda:

{
  "data": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "type": "validation",
    "attributes": {
      "validation_type": "ocr",
      "status": "valid",
      "has_cep": true,
      "ocr_confidence": 0.96,
      "ocr_result": {
        "fecha": "2025-04-10",
        "monto": 12500.00,
        "clave_rastreo": "MXBA20250410003456"
      },
      "image_path": "comprobantes/c3d4e5f6-a7b8-9012-cdef-123456789012.png",
      "processing_time_ms": 2840,
      "created_at": "2025-04-10T11:30:00Z",
      "completed_at": "2025-04-10T11:30:02Z"
    }
  }
}

2. Modo asíncrono (?async=1)

Para pipelines de alto volumen, añade ?async=1 para recibir un 202 inmediato y dejar que la consulta OCR + CEP corra en segundo plano. La imagen se sanea y persiste antes de encolar el job, por lo que no se perderá si el worker está caído momentáneamente.

curl -X POST 'https://api.example.com/v1/validate-ocr?async=1' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "image_url": "https://storage.example.com/comprobantes/spei-002.png" }'

Respuesta 202:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "validation",
    "attributes": { "status": "queued" }
  }
}

Sondea GET /v1/validations/{id} cada 2–5 segundos hasta que status alcance un valor terminal. Respeta el header Retry-After cuando esté presente.

3. Descargar el certificado CEP

Una vez que status sea valid y has_cep sea true, descarga el certificado igual que en una validación directa:

curl 'https://api.example.com/v1/validations/c3d4e5f6-.../cep?format=pdf' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.pdf

4. Recuperar la imagen del comprobante almacenada

La imagen saneada se persiste en la plataforma y es accesible vía GET /v1/validations/{id}/image. Úsala para mostrar el comprobante en tu UI o para archivarlo junto con el CEP.

curl 'https://api.example.com/v1/validations/c3d4e5f6-.../image' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output comprobante.png

Siguientes pasos