Listar verificaciones

GET https://api.veriko.mx/v1/validations

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

Devuelve una lista paginada de las verificaciones del usuario autenticado. Todos los filtros son aditivos: status (valor único o lista CSV), type, date_from/date_to, search (clave de rastreo, referencia numérica, emisor o receptor), bank, amount_min/amount_max, with_deleted, playground, batch_id y retry_state. Para obtener una fila individual con su retry_state completo y ETag, usa GET /v1/validations/{id}; para descargar el CEP de una fila valid usa 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 fallback a request_data). Independiente de `amount_min`.
`amount_min`	query	`number (float)`	opcional	Monto mínimo inclusive. Se compara contra el `monto` de la verificación (normalized_data, con fallback a request_data). Independiente de `amount_max`.
`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.
`batch_id`	query	`integer`	opcional	Filtra a las validaciones generadas por un job de importación masiva (`POST /v1/validations/imports/{id}/commit`). Útil para la vista post-commit del detalle del import.
`date_from`	query	`string (date)`	opcional	Fecha inicial inclusive (YYYY-MM-DD). Se trunca a 10 caracteres.
`date_to`	query	`string (date)`	opcional	Fecha final inclusive (YYYY-MM-DD). Se trunca a 10 caracteres.
`page`	query	`integer`	opcional	Número de página. Mínimo 1. Predeterminado: `1`
`per_page`	query	`integer`	opcional	Elementos por página (1–50). El controlador acota fuera de rango. Predeterminado: `10`
`playground`	query	`string`	opcional	Cuando vale exactamente `'1'`, restringe el listado a validaciones de sandbox. Cualquier otro valor se ignora (default: solo producción).
`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`.
`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).
`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`.
`type`	query	`string`	opcional	Filtrar por tipo de validación (`direct` o `ocr`).
`with_deleted`	query	`string`	opcional	Tri-state full-visibility: omitir = todas (activas + eliminadas); `'1'` = solo soft-eliminadas; `'0'` = solo activas. Convención compartida con los paneles admin.

Petición

cURLPython•JavaScript•PHP•

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

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).
`type`	`string`	Tipo de recurso JSON:API. Siempre `validation`.
`validation_type`	`string`	Tipo de validación: `direct` para parámetros textuales, `ocr` para imagen de comprobante.
`status`	`string`	Estado del resultado. Ver `Validation.attributes.status` para la descripción completa de cada valor.
`fecha`	`string (date)`	Fecha de la transferencia (YYYY-MM-DD).
`monto`	`number (double)`	Importe de la transferencia en pesos mexicanos (MXN).
`clave_rastreo`	`string`	Clave de rastreo SPEI.
`emisor`	`string`	Banco emisor de la transferencia.
`receptor`	`string`	Banco receptor de la transferencia.
`playground`	`boolean`	Indica si la validación fue ejecutada en modo sandbox.
`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.
`completed_at`	`union`	Marca temporal de finalización de la validación. `null` mientras el estado es `queued` o `processing`.
`deleted_at`	`union`	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.
`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.
`max_retries`	`integer \| null` anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor.
`interval_seconds`	`integer \| null` anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor.
`outcomes`	`array \| null` anulable	Siempre `null` en el shape compacto. Ver `RetryStateFull` para el valor.
`attempts_completed`	`integer`	Número de reintentos completados hasta el momento.
`next_attempt_at`	`union`	Timestamp del próximo reintento programado. `null` si el ciclo está en estado terminal o si no hay reintentos activos.
`resolved_at`	`union`	Timestamp cuando un reintento resolvió la validación a `valid`. `null` si el ciclo no ha terminado por resolución.
`exhausted_at`	`union`	Timestamp cuando se agotaron los reintentos sin resolución. `null` si el ciclo no ha terminado por agotamiento.
`cancelled_at`	`union`	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.

**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	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`