Actualizar un beneficiario

PUT https://api.veriko.mx/v1/beneficiaries/{id}

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

Actualiza un beneficiario existente. Acepta envoltorio JSON:API o un objeto plano. Tres rutas:

Solo label: se sanea y persiste. - account_number nuevo (también acepta el alias legacy clabe): re-deriva account_type, bank_code y bank_name con las mismas reglas que POST /v1/beneficiaries. Para tipo phone el cuerpo debe incluir bank_code.
Solo bank_code: válido únicamente cuando el beneficiario existente es tipo phone; para CLABE/card se ignora silenciosamente. Dispara la auditoría beneficiary.phone_bank_updated cuando el código cambia.

Si el cuerpo no contiene ningún campo editable → 422 no_valid_fields.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id` *	path	`integer`	obligatorio	ID numérico del beneficiario.

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`label`	string (?–100)	opcional	Etiqueta opcional libre. Saneada con `strip_tags` + `trim`. p. ej. `Proveedor XYZ`
`account_number`	string (patrón)	opcional	Nuevo número de cuenta. Reemplaza el existente y dispara la re-derivación de `account_type`, `bank_code` y `bank_name`. Para tipo `phone`, `bank_code` debe acompañar la petición. p. ej. `012180004412345678`
`bank_code`	string (patrón)	opcional	Código Banxico SPEI de 5 dígitos. Para beneficiarios de tipo `phone`, puede enviarse aislado para reasignar el banco DiMo del receptor. Para CLABE/card el campo se ignora. p. ej. `40021`

Petición

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/{id}' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "attributes": {
        "label": "Proveedor XYZ actualizado"
      }
    }
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200** `UpdateBeneficiaryResponse` — Beneficiario actualizado.
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** `PUT /v1/beneficiaries/{id}`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Beneficiario actualizado.	`UpdateBeneficiaryResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	El recurso no existe o no es visible para el llamador	`Error`
422	`4xx`	Falló la validación. Códigos posibles: `no_valid_fields`, `invalid_account_format`, `invalid_clabe_checksum`, `invalid_card_luhn`, `clabe_prefix_not_recognized`, `bank_code_required_for_phone`, `invalid_bank_code`, `invalid_account_length`.	`ErrorResponse`

**Errores de `PUT /v1/beneficiaries/{id}`**
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	`no_valid_fields`	No editable fields in request body. Envelope meta.request_id `d0e1f2a3b4c5`