VerikoDocs

Escribe para buscar. Enter abre el primer resultado.

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

Actualizar un beneficiario

Audiencia
public
Autenticación
API key
Permiso
beneficiaries:update
Guía de uso →

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: 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; si era el único campo, responde con no_valid_fields.

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

Si el account_number nuevo ya está registrado para la misma cuenta de usuario, activo o archivado, responde con un estado HTTP 422 (con beneficiary_already_registered en el cuerpo) y el beneficiario no cambia.

Parámetros
ParámetroUbicaciónTipoObligatorioDescripción
id*pathintegerobligatorio

ID numérico del beneficiario.

p. ej. 42
Parámetros
ParámetroTipoObligatorioDescripción
labelstring (?–100)opcional

Etiqueta opcional con la que la cuenta se identifica en la lista de beneficiarios.

p. ej. Proveedor XYZ
account_numberstring (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_codestring (patrón)opcional

Código SPEI (4 o 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
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.

Probar en el playground →
Respuesta 200UpdateBeneficiaryResponse — Beneficiario actualizado.
CampoTipoDescripción
dataobject

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

Datos canónicos del beneficiario: los de la cuenta y los 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. Es la cadena vacía ("") cuando la cuenta no tiene un banco conocido: una tarjeta cuyo BIN no está en el directorio. En ese caso bank_name trae un texto de relleno en el idioma de la petición.

p. ej. 40012
bank_name*string

Nombre oficial del banco, resuelto a partir de su bank_code. Con un bank_code vacío es un texto de relleno («BIN no reconocido (411111)»), que se traduce al idioma de la petición.

p. ej. BBVA MEXICO
labelstring | nullanulable

Etiqueta descriptiva libre del usuario. null cuando no fue asignada.

p. ej. Proveedor ABC
status*string

Estado del beneficiario. inactive si el beneficiario fue archivado. active si está en uso.

p. ej. active
created_at*string (date-time)

Fecha y hora, en ISO 8601 UTC, de creación.

p. ej. 2026-01-15T10:00:00Z
metaobject

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.

versionstring

Versión de la API que procesó la petición.

p. ej. 1.47.0
api_versionstring

Versión del prefijo de ruta de la API (ej. v1).

p. ej. v1
request_idstring

Identificador único de la petición (hex).

p. ej. a1b2c3d4e5f66f5e4d3c2b1a
datetimeobject

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
linksobject

Enlaces de paginación o relacionados, presentes solo cuando el endpoint devuelve una colección paginada.

Códigos de respuestaPUT /v1/beneficiaries/{id}
CódigoClaseDescripciónCuerpo
2002xxBeneficiario actualizado.UpdateBeneficiaryResponse
4004xxEl cuerpo de la petición está vacío o no es JSON válido.ErrorResponse
4014xxSe requiere autenticación o las credenciales son inválidasErrorResponse
4034xxPermisos insuficientesErrorResponse
4044xxEl recurso no existe o no es visible para el clienteError
4134xxEl cuerpo de la petición supera el tamaño máximo admitido (body_too_large).ErrorResponse
4224xxEl cuerpo no pasó la validación. Los códigos posibles son no_valid_fields, invalid_account_format, invalid_account_length, invalid_clabe_checksum, invalid_card_luhn, clabe_prefix_not_recognized, bank_code_required_for_phone, invalid_bank_code, max_length_exceeded, beneficiary_already_registered, account_number_invalid_type y label_invalid_type. Las dos últimas aparecen cuando account_number o label llegan con un tipo distinto de cadena de texto (por ejemplo, un número o un arreglo). Todo error de campo trae source.pointer.ErrorResponse
Errores de PUT /v1/beneficiaries/{id}
CódigoClaveEjemplo
400body_empty

El cuerpo de la petición está vacío.

Envelope
meta.request_id
a5b6c7d8e9f00f9e8d7c6b5a
400invalid_json

El cuerpo no es JSON válido.

Envelope
meta.request_id
b6c7d8e9f0a11a0f9e8d7c6b
401unauthorized

Credenciales de autenticación ausentes o inválidas.

Envelope
meta.request_id
c4d5e6f7a8b99b8a7f6e5d4c
403permission_denied

No tienes permiso para acceder a este recurso.

Envelope
meta.request_id
d5e6f7a8b9c00c9b8a7f6e5d
413body_too_large

El cuerpo de la petición es demasiado grande.

Envelope
meta.request_id
1a2b3c4d5e6ff6e5d4c3b2a1
422label_invalid_type

El campo label debe ser una cadena de texto.

Envelope
source.pointer
/data/attributes/label
meta.request_id
e1f2a3b4c5d66d5c4b3a2f1e
422no_valid_fields

El cuerpo no trae ningún campo editable.

Envelope
meta.request_id
d0e1f2a3b4c55c4b3a2f1e0d