Huéspedes y fidelidad
Los huéspedes son las personas a las que pertenece una reserva. Cada huésped vive dentro de un establecimiento y lleva una cuenta de fidelidad opcional que acumula puntos con las estancias confirmadas y se puede canjear por un descuento.
POST /guestsÁmbito: guests:write
Busca un huésped por (property, email) o crea uno. Es idempotente sobre el correo: volver a llamarlo con la misma dirección vincula al huésped existente en lugar de crear un duplicado, así que puedes llamarlo con total seguridad en cada compra.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
email | sí | Se usa como clave de coincidencia. |
first_name | sí | |
last_name | sí | |
phone | no | |
nationality | no | Texto libre o código ISO de país. |
curl -X POST "$VRDN_BASE/guests" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "[email protected]", "first_name": "Ada", "last_name": "Lovelace", "nationality": "GB" }'{ "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34", "created": true }Devuelve 201 con "created": true para un huésped nuevo, o 200 con "created": false cuando se vinculó a un huésped existente.
GET /guests/{id}Ámbito: guests:read (los campos con datos personales requieren además guests:read:pii)
curl "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34" -H "Authorization: Bearer $VRDN_KEY"Solo con guests:read:
{
"id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "GB",
"status": "active",
"is_local_verified": false
}Con guests:read:pii, la respuesta incluye además email, phone, address, date_of_birth, id_type e id_number.
| Campo | Tipo | Notas |
|---|---|---|
status | string | active, vip o blocked. |
is_local_verified | boolean | Si el huésped está verificado como residente local (desbloquea las tarifas solo para locales). |
PATCH /guests/{id}Ámbito: guests:write
Actualiza cualquier campo modificable. Envía solo lo que cambia. Poner local_verified es la forma que tiene un flujo de administración de marcar a un huésped como residente local verificado (deja registrada la hora de la verificación).
| Campo del cuerpo | Notas |
|---|---|
first_name, last_name, phone, nationality, address | Campos del perfil. |
status | active, vip o blocked. |
local_verified | Booleano. true desbloquea para este huésped las tarifas solo para locales. |
curl -X PATCH "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "local_verified": true }'Devuelve el huésped actualizado con la misma forma que GET /guests/{id}.
GET /guests/{id}/loyaltyÁmbito: loyalty:read
El saldo de puntos de un huésped, sus puntos acumulados de por vida, el nivel actual, lo que le falta para el siguiente nivel y el histórico reciente. Los huéspedes que todavía no tienen actividad de fidelidad devuelven una cuenta a cero en lugar de un 404.
curl "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34/loyalty" -H "Authorization: Bearer $VRDN_KEY"{
"points_balance": 1260,
"lifetime_points": 1260,
"tier": "Coral",
"next_tier": { "name": "Lagoon", "min_points": 5000 },
"points_to_next_tier": 3740,
"recent_transactions": [
{ "type": "earn", "points": 1260, "description": "Stay B7XKQ4M2NZ", "created_at": "2026-06-19T08:46:00.000Z" }
]
}| Campo | Tipo | Notas |
|---|---|---|
points_balance | integer | Puntos disponibles para gastar. |
lifetime_points | integer | Puntos acumulados en total (determinan el nivel; nunca se restan). |
tier | string | Nombre del nivel actual. |
next_tier | object | null | El siguiente nivel y su umbral, o null en el nivel más alto. |
recent_transactions | array | Hasta las 10 entradas más recientes del histórico (earn, redeem, expire, adjust). |
POST /loyalty/redemptionsÁmbito: loyalty:write
Descuenta los puntos de un huésped y registra una entrada redeem en el histórico. El saldo se comprueba de forma atómica, así que un canje nunca puede dejar el saldo en negativo; un canje por encima del saldo devuelve 409 insufficient_points.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
guest_id | sí | Debe pertenecer a este establecimiento. |
points | sí | Entero positivo. |
reservation_id | no | Asocia el canje a una estancia; debe pertenecer a este establecimiento y a este huésped. |
curl -X POST "$VRDN_BASE/loyalty/redemptions" \
-H "Authorization: Bearer $VRDN_KEY" \
-H "Content-Type: application/json" \
-d '{ "guest_id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34", "points": 1000, "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27" }'{
"redeemed_points": 1000,
"redeemed_value_usd": 10,
"new_balance": 260,
"tier": "Coral"
}Usa redeemed_value_usd como el descuento que aplicar en tu propio proceso de compra. Los puntos se acumulan automáticamente en las estancias confirmadas en USD (consulta Reservas).
- Reservas: los bloqueos y las confirmaciones que acumulan fidelidad.
- Autenticación: cómo funciona el acotado de los datos personales.