Objetivo

Enviar los campos de una transferencia SPEI al CEP de Banxico y recibir un veredicto legible por máquina (valid, not_found, cep_unavailable o error). Cuando la transferencia está confirmada puedes descargar el certificado CEP oficial en PDF o XML.

Requisitos previos

• Una API key activa (mxcep_…). Obtenla desde tu perfil con GET /v1/users/me/api-key.
• Los datos de la transferencia: fecha (fecha), monto (monto) y al menos uno de: clave de rastreo (clave_rastreo) o referencia numérica (referencia_numerica). También requeridos: banco emisor (emisor), banco receptor (receptor) y cuenta beneficiaria (cuenta_beneficiaria — CLABE, tarjeta o número celular DiMo).

Pasos

1. Enviar la validación

Manda los campos de la transferencia a POST /v1/validate. Proporciona clave_rastreo, referencia_numerica o ambos — más identificadores aumentan la precisión.

curl -X POST 'https://api.example.com/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2025-03-15",
    "monto": 15000.50,
    "clave_rastreo": "MXBA20250315001234",
    "emisor": "BANCO NACIONAL DE MEXICO",
    "receptor": "BBVA MEXICO",
    "cuenta_beneficiaria": "012180004412345678"
  }'

Respuesta síncrona (200) — la consulta al CEP se completó en el momento:

{
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "type": "validation",
    "attributes": {
      "status": "valid",
      "has_cep": true,
      "processing_time_ms": 1320,
      "created_at": "2025-03-15T14:22:10Z",
      "completed_at": "2025-03-15T14:22:11Z"
    },
    "links": {
      "self": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "cep_xml": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479/cep?format=xml",
      "cep_pdf": "/v1/validations/f47ac10b-58cc-4372-a567-0e02b2c3d479/cep?format=pdf"
    }
  }
}

Valores de estado:

2. Manejar la ruta asíncrona (status: "async")

Con alta carga o cuando pasas ?async=1, la API responde 202 y la validación se procesa en segundo plano:

curl -X POST 'https://api.example.com/v1/validate?async=1' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{ "fecha": "...", "monto": ..., "clave_rastreo": "...", ... }'

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 (valid, not_found, cep_unavailable, error):

curl 'https://api.example.com/v1/validations/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer mxcep_••••'

3. Descargar el certificado CEP

Cuando status es valid y has_cep es true, descarga el certificado:

# PDF (legible por humanos)
curl 'https://api.example.com/v1/validations/f47ac10b-.../cep?format=pdf' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.pdf

# XML (legible por máquina, formato canónico Banxico)
curl 'https://api.example.com/v1/validations/f47ac10b-.../cep?format=xml' \
  -H 'Authorization: Bearer mxcep_••••' \
  --output cep.xml

4. Activar reintentos automáticos en resultados no válidos

Para resultados not_found o cep_unavailable, activa reintentos automáticos para que la plataforma consulte Banxico nuevamente sin llamadas adicionales de tu parte:

curl -X PUT 'https://api.example.com/v1/validations/a1b2c3d4-.../retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "max_retries": 3,
    "interval_seconds": 600,
    "outcomes": ["not_found", "cep_unavailable"]
  }'

También puedes incluir retry_policy directamente en el body del POST /v1/validate original para configurar reintentos en una sola llamada. Consulta el historial de reintentos con GET /v1/validations/{id}/retry-attempts.

5. Evitar envíos duplicados

Usa el encabezado Idempotency-Key para deduplicar reintentos de red. Cualquier petición con la misma clave y body idéntico dentro de 24 horas devuelve la respuesta en caché:

curl -X POST 'https://api.example.com/v1/validate' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Idempotency-Key: mi-sistema-txn-id-12345' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Siguientes pasos

• Consulta el historial completo de validaciones: GET /v1/validations (filtra por estado, rango de fechas, tipo de cuenta).
• Valida a partir de una imagen de comprobante en lugar de campos manuales: ver Validar vía OCR.
• Exporta resultados a CSV para conciliación: GET /v1/validations/export.