Referencia de la API de apiCEP

La API de apiCEP permite validar comprobantes de transferencia SPEI y SPID mediante la combinación de análisis OCR de imágenes con verificación en tiempo real contra el sistema CEP (Comprobante Electrónico de Pago) de Banxico. Envía la imagen del comprobante junto con los datos del beneficiario, y la API devuelve un resultado validado y estructurado, incluyendo el CEP oficial.

URL Base

https://api.apicep.cloud

Autenticación

Todas las solicitudes requieren una API key válida enviada en el encabezado Authorization usando el esquema Bearer.

Authorization: Bearer TU_API_KEY

Las solicitudes sin una clave válida retornan 401 Unauthorized. Si excedes la cuota de tu plan, la API retorna 429 Too Many Requests.

Límite de Solicitudes (Rate Limiting)

La información del límite se devuelve en cada respuesta a través de estos encabezados:

Endpoint

Valida un comprobante de transferencia SPEI y SPID contra el registro CEP de Banxico.

POST https://api.apicep.cloud/validate-transfer

Solicitud (Request)

Encabezados

Modos de Validación

El endpoint soporta dos modos de validación según los campos enviados en el body:

• Modo OCR — envía imageUrl con la URL del comprobante. La API extrae los datos automáticamente y los valida contra Banxico.
• Modo Directo (sin OCR) — envía el objeto sender con los datos de la transferencia. En este modo imageUrl no es requerido.

Esquema del Body — Modo OCR

{
  "imageUrl": "https://ejemplo.com/comprobante.jpg",
  "system": "SPEI",
  "beneficiary": {
    "clabe": "012180015469165113",
    "bank": "BBVA MEXICO",
    "name": "Juan Pérez"
  }
}

Esquema del Body — Modo Directo (con sender)

{
  "beneficiary": {
    "clabe": "012180015469165113",
    "bank": "BBVA MEXICO",
    "name": "Juan Pérez"
  },
  "sender": {
    "date": "2026-01-17",
    "amount": 1,
    "bank": "HSBC",
    "trackingKey": "HSBC712057",
    "referenceNumber": "0170126"
  },
  "system": "SPEI"
}

Esquema del Body — Modo OCR con potentialBeneficiaries

{
  "imageUrl": "https://ejemplo.com/comprobante.jpg",
  "system": "SPEI",
  "potentialBeneficiaries": [
    {
      "clabe": "127180016477999560",
      "bank": "AZTECA"
    },
    {
      "phoneNumber": "1234567890",
      "bank": "BBVA"
    },
    {
      "cardNumber": "1234567890123456",
      "bank": "BANORTE"
    },
    {
      "clabe": "123456789012345678",
      "bank": "BANORTE"
    }
  ]
}

Campos de Nivel Superior

Objeto beneficiary

Objeto sender

Reglas de formato

• clabe — exactamente 18 dígitos
• phoneNumber — exactamente 10 dígitos
• cardNumber — exactamente 16 dígitos

Array potentialBeneficiaries

Cómo funciona la selección

El sistema compara los datos extraídos por OCR (banco destino, nombre del beneficiario, CLABE o cuenta detectada) contra cada candidato en potentialBeneficiaries. El candidato con mayor coincidencia se utiliza como beneficiario definitivo para la validación CEP. Si ningún candidato coincide, la validación retornará status: "error".

Bancos Válidos

El campo beneficiary.bank acepta el nombre del banco beneficiario.

Códigos de Estado HTTP

Encabezados de Respuesta

Esquema del Body de Respuesta

{
  "validationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "valid",
  "confidence": 0.97,
  "extracted": {
    "senderBank": "HSBC",
    "receiverBank": "BBVA MEXICO",
    "trackingKey": "2024010112345678",
    "referenceNumber": "987654321",
    "amount": 1500.00,
    "date": "2024-01-15",
    "senderName": "María García",
    "beneficiaryName": "Juan Pérez",
    "paymentConcept": "Pago de renta"
  },
  "validation": {
    "banxicoConfirmed": true,
    "cepStatus": "LIQUIDADO",
    "cepPreviouslyValidated": false,
    "cepDetails": { "..." : "..." }
  },
  "downloads": {
    "cepXml": "https://storage.apicep.cloud/...",
    "cepPdf": "https://storage.apicep.cloud/...",
    "originalImage": "https://storage.apicep.cloud/..."
  },
  "processingTime": {
    "ocr": "1.20s",
    "validation": "3.45s",
    "total": "4.68s"
  }
}

Campos de la Respuesta

Nivel Superior

Objeto extracted

Todos los campos son opcionales — su presencia depende de lo que el OCR haya podido leer.

Objeto validation

Objeto cepDetails

Solo se incluye cuando banxicoConfirmed es true.

Objeto downloads

Todas las URLs se sirven desde https://storage.apicep.cloud.

Objeto processingTime

Valores de Status

Cómo Funciona

El endpoint /validate-transfer ejecuta el siguiente flujo:

1. 1

   Descarga de imagen

   Descarga el comprobante desde la imageUrl proporcionada y almacena una copia en storage.apicep.cloud.

2. 2

   Extracción OCR

   Analiza la imagen para extraer campos SPEI o SPID (clave de rastreo, monto, fecha, bancos, nombres).

3. 3

   Consulta CEP

   Verifica el registro CEP de Banxico usando los datos extraídos y la cuenta del beneficiario proporcionada.

4. 4

   Parseo XML

   Si se encuentra un CEP, descarga y parsea el XML oficial para obtener el objeto cepDetails estructurado.

5. 5

   Respuesta

   Retorna el resultado de validación, datos extraídos, detalles del CEP y URLs de descarga.

Referencia de Errores

A continuación se detallan los códigos de estado HTTP (4xx y 5xx) que puede responder la API, junto con el formato de sus mensajes y su significado correspondiente.

200 con status: "error"

Estos son errores de procesamiento que se retornan con código 200:

Ejemplo de respuesta con campos faltantes

Cuando el OCR no puede extraer todos los datos obligatorios, la API retorna status: "error" con un mensaje descriptivo y el arreglo missingFields indicando exactamente qué campos faltan. Los campos obligatorios son: fecha de la operación, clave de rastreo o número de referencia, institución emisora del pago y monto del pago.

{
  "validationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "error",
  "confidence": 0.45,
  "extracted": {
    "senderBank": "HSBC",
    "amount": 1500.00
  },
  "validation": { "banxicoConfirmed": false },
  "processingTime": {
    "ocr": "1.10s",
    "total": "1.15s"
  },
  "error": "El OCR no pudo extraer los siguientes datos obligatorios del comprobante: fecha de la operación, clave de rastreo o número de referencia. Por favor envía una imagen más clara.",
  "missingFields": [
    "fecha de la operación",
    "clave de rastreo o número de referencia"
  ]
}

Ejemplos de Código

curl -X POST https://api.apicep.cloud/validate-transfer \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://ejemplo.com/comprobante.jpg",
    "system": "SPEI",
    "beneficiary": {
      "clabe": "012180015469165113",
      "bank": "BBVA MEXICO",
      "name": "Juan Pérez"
    }
  }'

Buenas Prácticas para Operaciones Masivas

Si necesitas validar múltiples comprobantes de transferencia en un solo proceso, te recomendamos no enviar todas las solicitudes al mismo tiempo. En su lugar, procésalas de forma secuencial con un intervalo de espera entre cada llamada. Sugerimos 1 segundo entre cada una.

¿Cómo implementarlo? Usa una función sleep entre cada llamada dentro de tu ciclo:

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

const comprobantes = [
  { imageUrl: 'https://ejemplo.com/comprobante1.jpg', clabe: '012180015469165113', bank: 'BBVA MEXICO', name: 'Juan Pérez', system: 'SPEI' },
  { imageUrl: 'https://ejemplo.com/comprobante2.jpg', clabe: '014180015469165114', bank: 'BANAMEX',     name: 'María García', system: 'SPID' },
  { imageUrl: 'https://ejemplo.com/comprobante3.jpg', clabe: '006180015469165115', bank: 'BANORTE',     name: 'Carlos López', system: 'SPEI' },
  // ...más comprobantes
];

for (const comprobante of comprobantes) {
  const response = await fetch('https://api.apicep.cloud/validate-transfer', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer TU_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      imageUrl: comprobante.imageUrl,
      system: comprobante.system,
      beneficiary: {
        clabe: comprobante.clabe,
        bank: comprobante.bank,
      },
    }),
  });

  const result = await response.json();

  if (result.status === 'valid' && result.validation.banxicoConfirmed) {
    console.log(`Transferencia verificada por Banxico ✅`);
    console.log('Monto:', result.extracted.amount);
    console.log('CEP PDF:', result.downloads.cepPdf);
  } else {
    console.log(`No se pudo verificar la transferencia ❌`);
    console.log('Razón:', result.error);
  }

  await sleep(1_000); // ⏳ espera 1 segundo antes del siguiente comprobante
}

Este patrón se llama throttling del lado del cliente y es una buena práctica estándar en integraciones que manejan operaciones masivas. Garantiza que tu proceso sea estable, predecible y fácil de depurar en caso de errores.

Notas

• Las imágenes del comprobante deben ser accesibles públicamente vía HTTPS al momento de la solicitud.
• Las URLs pre-firmadas son compatibles siempre que sigan vigentes durante el procesamiento.