Buscar cuenta en lista blanca propia

GEThttps://api.veriko.mx/v1/beneficiaries/lookup

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

Busca un número de cuenta exacto dentro de la lista de beneficiarios del usuario autenticado. Cuando existe, la respuesta trae los datos del banco.

La búsqueda está aislada por cuenta: un número que no esté en la lista propia responde con un estado HTTP 404.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`account`*	query	`string`	obligatorio	Número de cuenta completo: 10 dígitos (celular), 16 (tarjeta) o 18 (CLABE). Los separadores, espacios y guiones se eliminan antes de buscar. p. ej. `012180004412345678`

Petición

cURLPython•JavaScript•PHP•

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

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`LookupBeneficiaryAccountResponse` — Cuenta encontrada en la lista del usuario; devuelve metadatos del banco.
Campo	Tipo	Descripción
`data`	`object`	Payload principal de la respuesta. La forma varía según el endpoint (objeto, array, o envelope JSON:API con `type`, `id`, `attributes`).
`type`*	`string`	Tipo del recurso JSON:API. Siempre `beneficiary_lookup`. p. ej. `beneficiary_lookup`
`attributes`*	`object`	Metadatos de la cuenta resuelta.
`account_number`*	`string`	Número de cuenta consultado. p. ej. `012180004412345678`
`account_type`*	`string`	Tipo de cuenta: `clabe` (18 dígitos), `card` (16 dígitos) o `phone` (10 dígitos). p. ej. `clabe`
`bank_code`*	`string`	Código SPEI (5 dígitos) del banco resuelto. p. ej. `40012`
`bank_name`*	`string`	Nombre oficial del banco resuelto, derivado de su `bank_code`. p. ej. `BBVA MEXICO`
`label`	`string \| null`anulable	Etiqueta libre del beneficiario, `null` si no fue asignada. p. ej. `Proveedor ABC`
`meta`	`object`	Metadatos de la respuesta, incluyendo versión de la API, prefijo de ruta, identificador único de la petición y marca temporal del servidor en UTC.
`version`	`string`	Versión de la API que procesó la petición. p. ej. `1.47.0`
`api_version`	`string`	Versión del prefijo de ruta de la API (ej. `v1`). p. ej. `v1`
`request_id`	`string`	Identificador único de la petición (hex). p. ej. `a1b2c3d4e5f6`
`datetime`	`object`	Descriptor compañero presente en el bloque `meta` de cada respuesta (y en el `meta` del cuerpo de los webhooks salientes). Permite a los clientes afirmar el contrato de zona horaria sin releer el spec. p. ej. `{"timezone":"UTC","format":"ISO 8601"}`
`timezone`*	`string`	Siempre `UTC` — la zona canónica para cada campo datetime del cuerpo. p. ej. `UTC`
`format`*	`string`	Siempre `ISO 8601` — sufijo `Z` explícito en cada datetime. p. ej. `ISO 8601`
`links`	`object`	Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

**Códigos de respuesta**`GET /v1/beneficiaries/lookup`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Cuenta encontrada en la lista del usuario; devuelve metadatos del banco.	`LookupBeneficiaryAccountResponse`
400	`4xx`	Parámetro `account` ausente (`query_param_account_required`) o formato inválido (`invalid_account_format`).	`ErrorResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	Cuenta no encontrada en la lista de beneficiarios del usuario.	`ErrorResponse`

**Errores de `GET /v1/beneficiaries/lookup`**
Código	Clave	Ejemplo
400	`invalid_account_format`	No reconocemos el formato de esa cuenta. Envelope meta.request_id `d4e5f6a7b8c9`
400	`query_param_account_required`	Falta el parámetro `account` en la consulta. Envelope meta.request_id `c3d4e5f6a7b8`
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`
404	`beneficiary_not_found_for_account`	No encontramos ningún beneficiario para esa cuenta. Envelope meta.request_id `b2c3d4e5f6a7`