Clientes
identificados por teléfono

Cliente por id

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

Devuelve un cliente del tenant. Requiere scope customers:read.

Request

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

Response 200

{
  "id": "9f8e7d…",
  "name": "Juan Pérez",
  "email": "juan@example.com",
  "phone": "+573001234567",
  "phoneVerifiedAt": "2026-05-15T14:00:00.000Z",
  "role": "CLIENT_RETAIL",
  "isActive": true,
  "createdAt": "2026-04-30T09:12:00.000Z"
}

Cliente por teléfono

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

Devuelve el cliente cuyo WhatsApp coincide con el número enviado. El cliente debe haber vinculado previamente su WhatsApp (phoneVerifiedAt != null); si no, devuelve 404 con un mensaje explícito.

Path parameters

Request

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

¿Cómo vincula el cliente su WhatsApp?

1. El cliente entra a la tienda (https://<su-tienda>.nuvlyx.com) y se autentica.
2. Va a Mi cuenta → Vincular WhatsApp.
3. Ingresa su número y recibe un código de 6 dígitos por WhatsApp.
4. Confirma el código → phone_verified_at queda con timestamp.

A partir de ese momento, su sistema externo puede invocar cualquier endpoint by-phone con ese número y la API lo reconoce.

Reglas y límites

• Unicidad: un teléfono solo puede estar vinculado a un único cliente por tienda.
• Rate limit del OTP: máximo 5 códigos por hora por cliente. Re-envío con espera mínima de 60 segundos.
• Expiración del OTP: 10 minutos. Máximo 5 intentos por código antes de invalidarlo.
• Quitar vinculación: el cliente puede desvincular en cualquier momento desde su perfil. La API dejará de reconocerlo por teléfono inmediatamente.