Ospiti e programma fedeltà
Gli ospiti sono le persone a cui appartiene una prenotazione. Ogni ospite vive sotto una sola struttura e porta con sé un conto fedeltà facoltativo, che accumula punti sui soggiorni confermati e può essere riscattato per ottenere uno sconto.
POST /guestsAmbito: guests:write
Trova un ospite tramite (property, email) oppure ne crea uno. È idempotente sull'email: richiamarlo per lo stesso indirizzo collega l'ospite esistente invece di creare un duplicato, quindi puoi chiamarlo senza rischi a ogni checkout.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
email | sì | Usata come chiave di corrispondenza. |
first_name | sì | |
last_name | sì | |
phone | no | |
nationality | no | Testo libero o codice paese ISO. |
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 }Restituisce 201 con "created": true per un ospite nuovo, oppure 200 con "created": false quando è stato collegato un ospite esistente.
GET /guests/{id}Ambito: guests:read (i campi PII richiedono in più 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 risposta include in più email, phone, address, date_of_birth, id_type e id_number.
| Campo | Tipo | Note |
|---|---|---|
status | string | active, vip o blocked. |
is_local_verified | boolean | Se l'ospite è verificato come residente locale (sblocca le tariffe riservate ai residenti). |
PATCH /guests/{id}Ambito: guests:write
Aggiorna qualsiasi campo modificabile. Invia solo ciò che cambia. Impostare local_verified è il modo in cui un flusso di amministrazione segna un ospite come residente locale verificato (registra anche il momento della verifica).
| Campo del corpo | Note |
|---|---|
first_name, last_name, phone, nationality, address | Campi della scheda. |
status | active, vip o blocked. |
local_verified | Booleano. true sblocca per questo ospite le tariffe riservate ai residenti. |
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 }'Restituisce l'ospite aggiornato nella stessa forma di GET /guests/{id}.
GET /guests/{id}/loyaltyAmbito: loyalty:read
Il saldo punti di un ospite, i punti accumulati da sempre, il livello attuale, i progressi verso il livello successivo e i movimenti recenti. Gli ospiti che non hanno ancora attività fedeltà restituiscono un conto azzerato invece di 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 | Note |
|---|---|---|
points_balance | integer | Punti spendibili. |
lifetime_points | integer | Punti accumulati in totale (determinano il livello, non vengono mai decrementati). |
tier | string | Nome del livello attuale. |
next_tier | object | null | Il livello successivo e la sua soglia, oppure null al livello più alto. |
recent_transactions | array | Fino a 10 movimenti più recenti (earn, redeem, expire, adjust). |
POST /loyalty/redemptionsAmbito: loyalty:write
Addebita i punti di un ospite e registra un movimento redeem. Il saldo viene controllato in modo atomico, quindi un riscatto non può mai andare in rosso, e un riscatto eccessivo restituisce 409 insufficient_points.
| Campo del corpo | Obbligatorio | Note |
|---|---|---|
guest_id | sì | Deve appartenere a questa struttura. |
points | sì | Intero positivo. |
reservation_id | no | Associa il riscatto a un soggiorno, e deve appartenere a questa struttura e a questo ospite. |
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 come sconto da applicare nel tuo checkout. I punti si accumulano automaticamente sui soggiorni confermati in USD (vedi Prenotazioni).
- Prenotazioni: i blocchi e le conferme che fanno accumulare punti fedeltà.
- Autenticazione: come funziona la protezione dei dati personali.