Skip to content
API · Monedero

Monedero del cliente

Consulte el saldo de cualquier cliente identificándolo por id o por teléfono vinculado.

Saldo por id

GET /api/v1/external/customers/:id/wallet

Devuelve el saldo actual del monedero del cliente. Requiere scope wallet:read.

Request

curl https://api.nuvlyx.com/api/v1/external/customers/9f8e…/wallet \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Response 200

{
  "id": "wallet_…",
  "balance": "25000.00",
  "currency": "COP",
  "updatedAt": "2026-05-18T10:21:00.000Z"
}

Saldo por teléfono

GET /api/v1/external/customers/by-phone/:phone/wallet

Devuelve el saldo del cliente identificándolo por su número de WhatsApp. El cliente debe haber vinculado su WhatsApp previamente desde su perfil en la tienda. Si no lo hizo, la API devuelve 404 con un mensaje explícito.

Path parameters

ParámetroFormatoEjemplo
phoneE.164 (con +)%2B573001234567 (URL-encoded)

Request

curl "https://api.nuvlyx.com/api/v1/external/customers/by-phone/%2B573001234567/wallet" \
  -H "Authorization: Bearer nvl_live_TU_TOKEN"

Errores

  • 401 — Token faltante o inválido.
  • 403 — Token sin el scope wallet:read.
  • 404 — Ningún cliente con ese teléfono vinculado a la tienda.

Recargar saldo (por id)

POST /api/v1/external/customers/:id/wallet/recharge

Acredita el monto indicado al monedero del cliente. Internamente crea una WalletTransaction tipo MANUAL_ADJUSTMENT — equivalente a una recarga manual aprobada. Requiere scope wallet:write.

Body

CampoTipoDescripción
amountnúmeroMonto positivo a acreditar (1 – 100,000,000). Máx. 2 decimales.
referencestringReferencia legible (ej "Bot WhatsApp - venta #..."). Queda en el ledger. Opcional.

Request

curl -X POST https://api.nuvlyx.com/api/v1/external/customers/9f8e…/wallet/recharge \
  -H "Authorization: Bearer nvl_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000, "reference": "Pago Nequi #PAGO-0042" }'

Response 200

{
  "id": "wallet_…",
  "balance": "75000.00",
  "currency": "COP",
  "updatedAt": "2026-05-18T10:33:00.000Z"
}

Recargar saldo (por teléfono)

POST /api/v1/external/customers/by-phone/:phone/wallet/recharge

Misma operación, identificando al cliente por su teléfono vinculado. 

curl -X POST "https://api.nuvlyx.com/api/v1/external/customers/by-phone/%2B573001234567/wallet/recharge" \
  -H "Authorization: Bearer nvl_live_TU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50000 }'

¿Por qué los clientes deben vincular su WhatsApp?

Por seguridad y consentimiento del cliente, la API no crea automáticamente clientes a partir de un teléfono recibido por API. El cliente confirma su número desde su perfil en la tienda recibiendo un código por WhatsApp. Una vez vinculado, queda asociado al tenant (phone_verified_at queda con timestamp).

Esto evita creación masiva de clientes fantasma desde integraciones externas y mantiene un flujo de opt-in claro.