Obtener las estadísticas de verificaciones de la cuenta

GEThttps://api.veriko.mx/v1/validations/stats

Audiencia: public
Autenticación: API key
Permiso: validations:read

Devuelve las verificaciones de la cuenta contadas de dos maneras distintas, y la distinción importa:

Los contadores de primer nivel —valid, not_found, cep_unavailable, error, pending— cuentan por veredicto, que es lo que respondió Banxico. other es el resto, y en la práctica son las filas inválidas.
by_status cuenta por estado del ciclo de vida (queued, processing, valid, …), que es el mismo eje sobre el que filtra la lista. Sus cubos suman el total.

by_type reparte entre validación directa y por OCR, y deleted cuenta las retiradas del historial.

Los filtros son los mismos que en GET /v1/validations —fechas, tipo, búsqueda, banco, importe, playground, lote y eliminadas—, con una excepción: status se acepta y no altera los números, porque cada contador trae su propio criterio.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`amount_max`	query	`number (float)`	opcional	Monto máximo inclusive (normalized_data, alternativa request_data). p. ej. `50000`
`amount_min`	query	`number (float)`	opcional	Monto mínimo inclusive (normalized_data, alternativa request_data). p. ej. `1000.5`
`bank`	query	`string`	opcional	Restringe los contadores a la clave SPEI de 3 dígitos del banco (receptor o emisor). Solo dígitos, máximo 5 caracteres. p. ej. `012`
`batch_id`	query	`integer`	opcional	Restringe los contadores al lote de un import masivo. p. ej. `42`
`from`	query	`string (date)`	opcional	Fecha inicial inclusive (YYYY-MM-DD). p. ej. `2025-01-01`
`playground`	query	`string`	opcional	Deja solo las validaciones hechas desde el banco de pruebas. El único valor admitido es `1`: cualquier otro —incluido `true`— responde `422` en vez de ignorarse, para que quede claro que el filtro no se aplicó. p. ej. `1`
`retry_state`	query	`string`	opcional	Filtrar por estado del ciclo de reintentos automáticos: `pending` = en curso; `resolved` = resuelta vía reintento; `exhausted` = intentos agotados; `cancelled` = cancelado manualmente. Valores fuera del allowlist devuelven 422 `invalid_filter`. p. ej. `pending`
`search`	query	`string`	opcional	Búsqueda en clave de rastreo, referencia numérica, emisor y receptor. p. ej. `MXBA`
`status`	query	`string`	opcional	Se acepta y no altera los números. Existe para que una interfaz pueda reenviar el mismo juego de filtros que usa en `GET /v1/validations` sin tener que quitarlo; cada indicador de esta respuesta lleva su propio criterio y no se recorta por estado. Los demás filtros —fechas, banco, importe, tipo— sí se aplican. p. ej. `valid`
`to`	query	`string (date)`	opcional	Fecha final inclusive (YYYY-MM-DD). p. ej. `2025-03-31`
`type`	query	`string`	opcional	Cómo se pidió la validación: `direct` con los campos escritos a mano, `ocr` a partir de una imagen del comprobante. p. ej. `direct`
`with_deleted`	query	`string`	opcional	Si incluir las validaciones borradas. `0` deja solo las vivas —el comportamiento por omisión— y `1` incluye también las que se borraron. Las borradas conservan su resultado: sirven para cuadrar un histórico que ya se había exportado. p. ej. `0`

Petición

cURLPython•JavaScript•PHP•

curl -X GET 'https://api.veriko.mx/v1/validations/stats' \
  -H 'Authorization: Bearer veriko_••••'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`ValidationStats` — Estadísticas agregadas de validaciones del usuario.
Campo	Tipo	Descripción
`type`	`string`	Tipo del recurso JSON:API (siempre `validation_stats`). p. ej. `validation_stats`
`attributes`	`object`	Conteos agregados de validaciones del usuario (cumpliendo los filtros). Los cubos de primer nivel cuentan por `banxico_status` (veredicto); `by_status` desglosa por la columna `status` (ciclo de vida).
`total`	`integer`	Cantidad total de validaciones del usuario que cumplen los filtros. Incluye todas, sin importar el estado Banxico. p. ej. `47`
`valid`	`integer`	Subconjunto del total con `banxico_status='valid'` (transferencia confirmada). p. ej. `35`
`not_found`	`integer`	Subconjunto del total con `banxico_status='not_found'`. p. ej. `5`
`cep_unavailable`	`integer`	Subconjunto del total con `banxico_status='cep_unavailable'` (el servicio CEP de Banxico no estaba disponible al momento de validar). p. ej. `2`
`error`	`integer`	Subconjunto del total con `banxico_status='error'` (error Banxico, p.ej. HTTP 5xx o fallo de red). p. ej. `1`
`pending`	`integer`	Subconjunto del total con `banxico_status='pending'`: validaciones asíncronas aún en cola o en proceso, sin resultado CEP todavía. p. ej. `1`
`deleted`	`integer`	Cantidad de validaciones soft-deleted del usuario (cumpliendo los mismos filtros). p. ej. `2`
`other`	`integer`	Resto del total tras restar `valid`, `not_found`, `cep_unavailable`, `error` y `pending`. En la práctica corresponde a filas `invalid`. Se calcula como `max(0, total - valid - not_found - cep_unavailable - error - pending)`. p. ej. `1`
`by_type`	`object`	Desglose por tipo de validación. `direct + ocr` siempre suma `total`.
`direct`*	`integer`	Validaciones directas (por campos CLABE/tarjeta/teléfono). p. ej. `30`
`ocr`*	`integer`	Validaciones por OCR de comprobante. p. ej. `17`
`by_status`	`object`	Desglose por estado de ciclo de vida (columna `status`: `queued` / `processing` / `valid` / `not_found` / `cep_unavailable` / `invalid` / `failed` / `error`). Es el MISMO eje sobre el que filtra la tabla de validaciones (a diferencia de `valid` / `not_found` / `cep_unavailable` / `error` / `pending` arriba, que cuentan por `banxico_status`): una fila en curso aparece como `processing`/`queued` aquí, pero como `pending` en aquellos cubos. Las ocho llaves siempre están presentes (0 si no hay filas) y siempre suman `total`.
`queued`*	`integer`	Validaciones en cola, aún sin procesar (asíncronas). p. ej. `3`
`processing`*	`integer`	Validaciones en proceso contra Banxico ahora mismo. p. ej. `1`
`valid`*	`integer`	Validaciones con estado de ciclo de vida `valid` (confirmadas). p. ej. `35`
`not_found`*	`integer`	Validaciones con estado `not_found`. p. ej. `5`
`cep_unavailable`*	`integer`	Validaciones con estado `cep_unavailable`. p. ej. `2`
`invalid`*	`integer`	Validaciones con estado `invalid` (entrada inválida). p. ej. `1`
`failed`*	`integer`	Validaciones con estado `failed` (fallo del pipeline). p. ej. `0`
`error`*	`integer`	Validaciones con estado `error`. p. ej. `1`

**Códigos de respuesta**`GET /v1/validations/stats`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Estadísticas agregadas de validaciones del usuario.	Sin cuerpo
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
422	`4xx`	Un filtro trae un valor fuera de su lista admitida. El código es `invalid_filter` y el `detail` nombra el parámetro.	`ErrorResponse`

**Errores de `GET /v1/validations/stats`**
Código	Clave	Ejemplo
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
422	`invalid_filter`	El filtro `retry_state` trae un valor no admitido. Envelope meta.request_id `c3d4e5f6a1b2`