Objetivo

Enviar los campos de una transferencia SPEI a Banxico y recibir un veredicto legible (valid, not_found, cep_unavailable o error). Cuando la transferencia está confirmada puedes descargar el certificado Comprobante Electrónico de Pago (CEP) en PDF o XML.

Requisitos previos

• Una API key activa (veriko_…). Si no tienes una genérala desde la consola de Veriko, en la sección API y abre el panel API Key.
• Los datos de la transferencia:
  • fecha (fecha).
  • monto (monto).
  • clave de rastreo (clave_rastreo) o referencia numérica (referencia_numerica) — Al menos uno.
  • banco emisor (emisor).
  • banco receptor (receptor)
  • cuenta beneficiaria (cuenta_beneficiaria — CLABE, Tarjeta o Celular).

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.veriko.mx/v1/validate' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2025-03-15",
    "monto": 15000.50,
    "clave_rastreo": "MXBA20250315001234",
    "emisor": "40014",
    "receptor": "40012",
    "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 el modo asíncrono (status:"async")

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

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

Respuesta 202:

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

Para sondear el estado de la validacion: GET /v1/validations/{id} cada 2–5 segundos hasta que status alcance un valor terminal (valid, not_found, cep_unavailable, error):

curl 'https://api.veriko.mx/v1/validations/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer veriko_••••'

3. Descargar el comprobante oficial (CEP)

Cuando status es valid y has_cep es true, puedes descargar el comprobante oficial expedido por el Banco de México (Banxico):

# PDF
curl 'https://api.veriko.mx/v1/validations/f47ac10b-.../cep?format=pdf' \
  -H 'Authorization: Bearer veriko_••••' \
  --output cep.pdf

# XML
curl 'https://api.veriko.mx/v1/validations/f47ac10b-.../cep?format=xml' \
  -H 'Authorization: Bearer veriko_••••' \
  --output cep.xml

También puedes hacer que el comprobante llegue al chat de Telegram vinculado a la cuenta, sin descargarlo tú:

curl -X POST 'https://api.veriko.mx/v1/validations/f47ac10b-.../cep/send-telegram' \
  -H 'Authorization: Bearer veriko_••••'

La respuesta es un 202 inmediato con queued: true: confirma que se encoló, no que se entregó. El documento aparece en el chat unos segundos después, y es el mismo PDF que devuelve la descarga de arriba.

Hacen falta dos condiciones, y cada una falla con su propio código: que el CEP exista —si no, 404 cep_not_available— y que la cuenta tenga Telegram vinculado —si no, 409 telegram_not_linked—. Lo segundo se comprueba en telegram_linked de GET /v1/users/me, y se configura en Gestionar notificaciones.

4. Activar reintentos automáticos en resultados no satisfactorios

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

curl -X PUT 'https://api.veriko.mx/v1/validations/a1b2c3d4-.../retry-policy' \
  -H 'Authorization: Bearer veriko_••••' \
  -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 para configurar reintentos en una sola llamada. Consulta el historial de reintentos de la validación con GET /v1/validations/{id}/retry-attempts.

Para más información de los reintentos, consulta Políticas de reintentos

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.veriko.mx/v1/validate' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Idempotency-Key: mi-sistema-txn-id-12345' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Para más información sobre idempotencia, consulta Idempotencia

Siguientes pasos

• Guarda cuentas en las que recibes transferencias y agiliza futuras validaciones: Crear beneficiario.
• Valida a partir de una imagen de comprobante en lugar de campos manuales: ver Validar vía OCR.
• Consulta el historial completo de validaciones: GET /v1/validations (filtra por estado, rango de fechas, tipo de cuenta).