Crear un beneficiario

POST https://api.veriko.mx/v1/beneficiaries

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

Registra una nueva cuenta beneficiaria. El tipo de cuenta (clabe, card, phone) se autodetecta por longitud del número de cuenta:

18 dígitos = CLABE — bank_code se deriva del prefijo y cualquier bank_code enviado por el cliente se ignora.
13–19 dígitos (excepto 18) = tarjeta — bank_code se deriva del BIN vía directorio local con fallback a lookup remoto.
10 dígitos = celular (DiMo) — bank_code es obligatorio en el cuerpo.

Si la cuenta ya existe activa, devuelve 422 beneficiary_already_registered. Si la cuenta existe pero está archivada, se reactiva y se devuelve 200 con meta.reactivated=true (no 201). Antes de crear puedes validar la estructura de la cuenta con GET /v1/beneficiaries/validate-account (chequeo CLABE/Luhn local sin tocar Banxico). El bank_code para tipo phone se elige del catálogo GET /v1/public/banks.

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`account_number`	string (patrón)	obligatorio	Número de cuenta. Se acepta CLABE de 18 dígitos, tarjeta de 13–19 dígitos (excepto 18, reservado a CLABE) o celular DiMo de 10 dígitos. Los separadores (espacios, guiones) se eliminan antes de validar. p. ej. `012180004412345678`
`bank_code`	string (patrón)	opcional	Código Banxico SPEI de 5 dígitos. Obligatorio cuando el tipo detectado es `phone`; ignorado para CLABE y tarjeta (se deriva del prefijo o BIN). Cuando aplica, el código se valida contra el catálogo actual de participantes SPEI. p. ej. `40012`
`label`	string (?–100)	opcional	Etiqueta opcional libre. Saneada con `strip_tags` y `trim` antes de persistirse. p. ej. `Proveedor ABC`

Petición

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/beneficiaries' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_number": "4111111111111111",
    "label": "Tarjeta BBVA nómina"
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 2xx** `CreateBeneficiaryResponse`
Campo	Tipo	Descripción
`type` *	`string`	Tipo de recurso JSON:API. Siempre `beneficiary`.
`id` *	`integer`	Identificador numérico autoincremental del beneficiario en la tabla `user_beneficiaries`.
`attributes` *	`object`	Atributos canónicos del beneficiario (datos de la cuenta receptora y metadatos del registro).
`account_number` *	`string`	Número de cuenta almacenado: CLABE (18 dígitos), tarjeta (13-19 dígitos) o celular DiMo (10 dígitos). Use `account_type` para desambiguar el tipo exacto.
`account_type` *	`string`	Tipo de cuenta autodetectado: `clabe` (18 dígitos), `card` (13-19 dígitos) o `phone` (10 dígitos, celular DiMo).
`bank_code` *	`string`	Código Banxico de 5 dígitos del banco receptor, derivado del prefijo CLABE, BIN de la tarjeta o catálogo DiMo.
`bank_name` *	`string`	Nombre del banco resuelto a partir del prefijo CLABE, BIN de la tarjeta o catálogo DiMo.
`label`	`string \| null` anulable	Etiqueta descriptiva libre del usuario. `null` si no fue asignada.
`status` *	`string`	Estado del beneficiario. `inactive` se asigna cuando el beneficiario se archiva (no aparece en listados por defecto).
`created_at` *	`string (date-time)`	Marca temporal UTC de creación.

**Códigos de respuesta** `POST /v1/beneficiaries`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Beneficiario reactivado (existía en estado archivado para el mismo `account_number`). Incluye `meta.reactivated=true`.	`CreateBeneficiaryResponse`
201	`2xx`	Beneficiario creado.	`CreateBeneficiaryResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
422	`4xx`	Falló la validación. Códigos posibles: `account_number_required`, `invalid_account_format`, `invalid_clabe_checksum`, `invalid_card_luhn`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `invalid_bank_code`, `invalid_account_length`, `beneficiary_already_registered`.	`ErrorResponse`

**Errores de `POST /v1/beneficiaries`**
Código	Clave	Detalle
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`
422	`bank_code_required_for_phone`	A bank_code is required when registering a phone beneficiary. Envelope meta.request_id `f6a7b8c9d0e1`
422	`beneficiary_already_registered`	A beneficiary with this account number already exists. Envelope meta.request_id `b8c9d0e1f2a3`
422	`clabe_prefix_not_recognized`	The CLABE prefix does not match any SPEI participant. Envelope meta.request_id `a7b8c9d0e1f2`