Actualizar un beneficiario

PUThttps://api.veriko.mx/v1/beneficiaries/{id}

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

Actualiza un beneficiario ya registrado. El cuerpo admite la envoltura JSON:API o un objeto plano, y lo que se envíe determina el alcance del cambio:

Solo label: Se guarda, sin tocar la cuenta.
Un account_number nuevo, o el alias antiguo: vuelven a derivarse account_type, bank_code y bank_name. Si el nuevo número es un celular (phone), el cuerpo debe llevar bank_code.
Solo bank_code: se aplica únicamente sobre un beneficiario de tipo celular. En una CLABE o una tarjeta el banco se deriva del número, así que el valor enviado se descarta sin error.

Un cuerpo sin ningún campo editable responde con un estado HTTP 422 (con no_valid_fields en el cuerpo).

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

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

Petición

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/beneficiaries/{id}' \
  -H 'Authorization: Bearer veriko_••••' \
  -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
`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 de recurso JSON:API. Siempre `beneficiary`. p. ej. `beneficiary`
`id`*	`string`	Identificador numérico del beneficiario en el sistema. p. ej. `42`
`attributes`*	`object`	Atributos canónicos del beneficiario (datos de la cuenta y metadatos del registro).
`account_number`*	`string`	Número de cuenta almacenado: CLABE (18 dígitos), tarjeta (16 dígitos) o celular/DiMo (10 dígitos). Use `account_type` para desambiguar el tipo exacto. 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 descriptiva libre del usuario. `null` si no fue asignada. p. ej. `Proveedor ABC`
`status`*	`string`	Estado del beneficiario. `inactive` si el beneficiario fue archivado o dado de baja. `active` si está en uso. p. ej. `active`
`created_at`*	`string (date-time)`	Marca temporal UTC de creación. p. ej. `2026-01-15T10:00:00Z`
`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**`PUT /v1/beneficiaries/{id}`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Beneficiario actualizado.	`UpdateBeneficiaryResponse`
400	`4xx`	El cuerpo de la petición está vacío o no es JSON válido.	`ErrorResponse`
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 cliente	`Error`
413	`4xx`	El cuerpo de la petición supera el tamaño máximo admitido (`body_too_large`).	`ErrorResponse`
422	`4xx`	El cuerpo no pasó la validación. Los códigos posibles son `no_valid_fields`, `invalid_account_length`, `clabe_prefix_not_recognized` y `bank_code_required_for_phone`.	`ErrorResponse`

**Errores de `PUT /v1/beneficiaries/{id}`**
Código	Clave	Ejemplo
400	`body_empty`	El cuerpo de la petición está vacío. Envelope meta.request_id `a5b6c7d8e9f0`
400	`invalid_json`	El cuerpo no es JSON válido. Envelope meta.request_id `b6c7d8e9f0a1`
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`
413	`body_too_large`	El cuerpo de la petición es demasiado grande. Envelope meta.request_id `1a2b3c4d5e6f`
422	`no_valid_fields`	El cuerpo no trae ningún campo editable. Envelope meta.request_id `d0e1f2a3b4c5`