Validar estructura de cuenta (CLABE, tarjeta o celular)

GET https://api.veriko.mx/v1/beneficiaries/validate-account

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

Valida la estructura de un número de cuenta sin consultar Banxico. Detecta el tipo por longitud (18 = CLABE, 13–19 ≠18 = tarjeta, 10 = celular), verifica el dígito de control (CLABE) o el Luhn (tarjeta) y resuelve el banco. Para CLABEs parciales de 17 dígitos calcula y anexa el dígito de control automáticamente (auto_completed contiene la CLABE de 18 dígitos resultante). El endpoint siempre devuelve 200 cuando el account viene presente: los errores estructurales se reflejan en checksum_valid=false o account_type='unknown' (no se elevan a 422). Usa este endpoint para validar formularios antes de llamar a POST /v1/beneficiaries o POST /v1/validate, evitando el costo de Banxico para cuentas con checksum inválido.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`account` *	query	`string`	obligatorio	Dígitos de la cuenta (completos o parciales). CLABE, tarjeta o celular. Mínimo 1 dígito, máximo 19.
`type`	query	`string`	opcional	Fuerza la interpretación del input en vez de auto-detectar por longitud. `clabe` resuelve el banco por prefijo aunque la CLABE esté incompleta (sin confundirla con tarjeta); `bin` busca un BIN de 6–8 dígitos en el directorio local (solo caché, sin red). Omitir para auto-detección.

Petición

cURLPython•JavaScript•PHP•

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

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200** `ValidateAccountResponse` — Resultado de la validación estructural. El cuerpo siempre tiene forma uniforme; los flags `checksum_valid` y `account_type` comunican el éxito o el motivo del rechazo estructural.
Campo	Tipo	Descripción
`type` *	`string`	Tipo del recurso JSON:API.
`attributes` *	`object`	Resultado de la validación estructural.
`input` *	`string`	Texto recibido tal cual (sin normalizar).
`length` *	`integer`	Longitud en dígitos del input normalizado.
`is_numeric` *	`boolean`	`true` cuando el input original contenía únicamente dígitos (sin separadores).
`account_type` *	`string`	Tipo de cuenta detectado por longitud, o `unknown` para inputs parciales o fuera de rango.
`is_complete` *	`boolean`	`true` cuando el input está completo para su tipo (18 dígitos en CLABE, 13–19 en tarjeta, 10 en celular).
`checksum_valid` *	`boolean`	`true` cuando el dígito de control de la CLABE pasa, o el Luhn de la tarjeta es válido. Para celular siempre `false` (no aplica).
`computed_control_digit`	`string \| null` anulable	Dígito de control CLABE calculado a partir de los primeros 17 dígitos. `null` cuando el tipo no es CLABE o el cálculo no es aplicable.
`auto_completed`	`string \| null` anulable	CLABE de 18 dígitos auto-completada cuando el input venía con 17 dígitos y el control pudo calcularse. `null` en los demás casos.
`bank`	`object \| null` anulable	Metadatos del banco resuelto, o `null` cuando no se pudo identificar. Para CLABE deriva del prefijo; para tarjeta deriva del BIN.
`banxico_code`	`string \| null` anulable	Código Banxico SPEI de 5 dígitos cuando el banco está mapeado.
`name`	`string`	Nombre del banco.
`card`	`object \| null` anulable	Metadatos adicionales del BIN cuando `account_type=card` y hubo coincidencia en el directorio. `null` en cualquier otro caso.
`bin`	`string`	Prefijo BIN consultado.
`brand`	`string \| null` anulable	Marca de la tarjeta (Visa, Mastercard, etc.).
`type`	`string \| null` anulable	Tipo de tarjeta (`debit`, `credit`, etc.).
`level`	`string \| null` anulable	Nivel de la tarjeta (`classic`, `gold`, etc.).
`country_iso`	`string \| null` anulable	ISO 3166-1 alpha-2 del país emisor.

**Códigos de respuesta** `GET /v1/beneficiaries/validate-account`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Resultado de la validación estructural. El cuerpo siempre tiene forma uniforme; los flags `checksum_valid` y `account_type` comunican el éxito o el motivo del rechazo estructural.	`ValidateAccountResponse`
400	`4xx`	`query_param_account_required` — el parámetro `account` viene vacío.	`ErrorResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`

**Errores de `GET /v1/beneficiaries/validate-account`**
Código	Clave	Detalle
400	`query_param_account_required`	The `account` query parameter is required. Envelope meta.request_id `f6a7b8c9d0e1`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`