Listar verificaciones

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

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

Devuelve el historial de verificaciones de la cuenta autenticada, paginado. Los catorce filtros son aditivos: se acumulan, no se excluyen entre sí. status admite un valor único o una lista separada por comas; search busca en clave de rastreo, referencia numérica, emisor y receptor; bank acepta la clave SPEI; amount_min y amount_max acotan el importe; y with_deleted, playground, batch_id, type, retry_state y el rango de fechas afinan el resto. La forma de la paginación está en la paginación. Esta lista es el índice, no el detalle. El retry_state completo y el ETag de una verificación están en GET /v1/validations/{id}, y el CEP de una fila con veredicto valid en GET /v1/validations/{id}/cep.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`amount_max`	query	`number (float)`	opcional	Monto máximo inclusive. Se compara contra el `monto` de la verificación (normalized_data, con respaldo en request_data). Independiente de `amount_min`. p. ej. `50000`
`amount_min`	query	`number (float)`	opcional	Monto mínimo inclusive. Se compara contra el `monto` de la verificación (normalized_data, con respaldo en request_data). Independiente de `amount_max`. p. ej. `1000.5`
`bank`	query	`string`	opcional	Filtra por la clave SPEI de 3 dígitos del banco (receptor o emisor). Solo dígitos, máximo 5 caracteres; cualquier otro valor se ignora. p. ej. `012`
`batch_id`	query	`integer`	opcional	Filtra a las validaciones generadas por una importación masiva (`POST /v1/validations/imports/{id}/commit`). Útil para la vista tras la confirmación del detalle del import. p. ej. `42`
`from`	query	`string (date)`	opcional	Fecha inicial inclusive (YYYY-MM-DD). Se trunca a 10 caracteres. p. ej. `2025-01-01`
`page`	query	`integer`	opcional	Número de página. Mínimo 1. Predeterminado: `1` p. ej. `1`
`per_page`	query	`integer`	opcional	Elementos por página (1–50). El controlador acota fuera de rango. Predeterminado: `10` p. ej. `10`
`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 de texto case-insensitive sobre el contenido JSON de la validación (request_data + normalized_data): clave de rastreo, referencia numérica, monto, cuenta, y los nombres de banco/beneficiario resueltos (p. ej. `scotiabank` encuentra "SCOTIABANK") cuando están en los datos normalizados. Se trunca a 100 caracteres; `%` y `_` se tratan como literales (no comodines). p. ej. `scotiabank`
`status`	query	`string`	opcional	Filtrar por estado granular. Acepta un único valor o una lista separada por comas (CSV), p. ej. `not_found,cep_unavailable,invalid,failed,error` para el segmento "No confirmadas". Cada token debe pertenecer al allowlist: `queued`, `processing`, `valid`, `not_found`, `cep_unavailable`, `invalid`, `failed`, `error`; los tokens fuera del allowlist se ignoran. El filtro se respeta literalmente en ambos casos (`status = ?` con un valor, `status IN (...)` con CSV), de modo que los segmentos "En proceso" (`processing`) y "Pendientes" (`queued`) quedan distintos. Para el conjunto pre-terminal combinado, envía `status=queued,processing`. p. ej. `valid`
`to`	query	`string (date)`	opcional	Fecha final inclusive (YYYY-MM-DD). Se trunca a 10 caracteres. p. ej. `2025-03-31`
`type`	query	`string`	opcional	Filtrar por tipo de validación (`direct` o `ocr`). 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' \
  -H 'Authorization: Bearer veriko_••••'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`ValidationListItem` — Lista paginada de validaciones con metadata de paginación.
Campo	Tipo	Descripción
`id`	`string (uuid)`	Identificador único de la validación (UUID v4). p. ej. `3fa85f64-5717-4562-b3fc-2c963f66afa6`
`type`	`string`	Tipo de recurso JSON:API. Siempre `validation`. p. ej. `validation`
`validation_type`	`string`	Tipo de validación: `direct` para parámetros textuales, `ocr` para imagen de comprobante. p. ej. `direct`
`status`	`string`	Estado del resultado. Ver `Validation.attributes.status` para la descripción completa de cada valor. `queued` — en cola; `processing` — en curso; `valid` — el comprobante existe y cuadra; `not_found` — Banxico no lo encuentra; `cep_unavailable` — el servicio no pudo entregarlo; `invalid` — los datos no cuadran; `failed` — el intento no pudo completarse; `error` — falló el sistema al procesarla. p. ej. `valid`
`fecha`	`string (date)`	Fecha de la transferencia (YYYY-MM-DD). p. ej. `2025-03-15`
`monto`	`number (double)`	Importe de la transferencia en pesos mexicanos (MXN). p. ej. `15000.5`
`clave_rastreo`	`string`	Clave con la que el banco identifica la transferencia ante el sistema de pagos. p. ej. `MXBA20250315001234`
`emisor`	`string`	Banco emisor de la transferencia. p. ej. `BANCO NACIONAL DE MEXICO`
`receptor`	`string`	Banco receptor de la transferencia. p. ej. `BBVA MEXICO`
`playground`	`boolean`	Indica si la validación fue ejecutada en modo sandbox. p. ej. `false`
`created_at`	`string (date-time)`	Timestamp ISO 8601 en UTC con sufijo `Z` explícito. Ejemplo: `"2026-05-01T05:14:38Z"`. Cada campo `_at`, `_end`, `_start`, `_date` de la API usa esta forma. El descriptor compañero en `meta.datetime` permite afirmar el contrato en tiempo de ejecución sin volver a leer este spec. El `new Date(value)` nativo del navegador, el `datetime.fromisoformat` (≥3.11) de Python y el `time.Parse(time.RFC3339)` de Go parsean este formato directamente. p. ej. `2026-05-01T05:14:38Z`
`completed_at`	`TimestampUTC \| null`	Marca temporal de finalización de la validación. `null` mientras el estado es `queued` o `processing`.
`deleted_at`	`TimestampUTC \| null`	Timestamp de eliminación (soft-delete). `null` si la validación no fue eliminada.
`is_deleted`	`boolean`	`true` si y solo si `deleted_at` tiene valor; campo de conveniencia para filtrado en la UI. p. ej. `false`
`retry_state`	`object`	Estado compacto del ciclo de reintentos. Los campos de política (`max_retries`, `interval_seconds`, `outcomes`) son siempre `null` en esta vista; consultar `GET /v1/validations/{id}` para el estado completo.
`enabled`	`boolean`	Indica si el ciclo de reintentos está activo para esta validación. p. ej. `true`
`max_retries`	`integer \| null`anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor. p. ej. `null`
`interval_seconds`	`integer \| null`anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor. p. ej. `null`
`outcomes`	`array \| null`anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor. p. ej. `null`
`attempts_completed`	`integer`	Número de reintentos completados hasta el momento. p. ej. `2`
`next_attempt_at`	`TimestampUTC \| null`	Timestamp del próximo reintento programado. `null` si el ciclo está en estado terminal o si no hay reintentos activos.
`resolved_at`	`TimestampUTC \| null`	Timestamp cuando un reintento resolvió la validación a `valid`. `null` si el ciclo no ha terminado por resolución.
`exhausted_at`	`TimestampUTC \| null`	Timestamp cuando se agotaron los reintentos sin resolución. `null` si el ciclo no ha terminado por agotamiento.
`cancelled_at`	`TimestampUTC \| null`	Timestamp cuando el ciclo fue cancelado explícitamente. `null` si no fue cancelado.
`terminal_state`	`string \| null`anulable	Estado terminal del ciclo: `pending` — activo, sin resultado final aún; `resolved` — un reintento obtuvo `valid`; `exhausted` — se agotaron los intentos; `cancelled` — cancelado por el usuario. `null` si la validación no tiene ciclo de reintentos. p. ej. `pending`

**Códigos de respuesta**`GET /v1/validations`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Lista paginada de validaciones con metadata de paginación.	Sin cuerpo
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
422	`4xx`	Valor inválido para `retry_state` (código `invalid_filter`).	`ErrorResponse`

**Errores de `GET /v1/validations`**
Código	Clave	Ejemplo
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`