Gäste und Treueprogramm
Gäste sind die Personen, zu denen eine Reservierung gehört. Jeder Gast gehört zu genau einer Unterkunft und trägt ein optionales Treuekonto, das bei bestätigten Aufenthalten Punkte sammelt und sich gegen einen Rabatt einlösen lässt.
POST /guestsScope: guests:write
Findet einen Gast über (property, email) oder legt einen an. Der Aufruf ist idempotent auf die E-Mail-Adresse: Ein erneuter Aufruf für dieselbe Adresse verknüpft mit dem bestehenden Gast, statt ein Duplikat anzulegen, Sie können ihn also bei jedem Checkout gefahrlos absetzen.
| Body-Feld | Erforderlich | Hinweise |
|---|---|---|
email | ja | Dient als Abgleichschlüssel. |
first_name | ja | |
last_name | ja | |
phone | nein | |
nationality | nein | Freitext oder ISO-Ländercode. |
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 }Liefert 201 mit "created": true für einen neuen Gast, oder 200 mit "created": false, wenn ein bestehender Gast verknüpft wurde.
GET /guests/{id}Scope: guests:read (personenbezogene Felder verlangen zusätzlich guests:read:pii)
curl "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34" -H "Authorization: Bearer $VRDN_KEY"Nur mit guests:read:
{
"id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
"first_name": "Ada",
"last_name": "Lovelace",
"nationality": "GB",
"status": "active",
"is_local_verified": false
}Mit guests:read:pii enthält die Antwort zusätzlich email, phone, address, date_of_birth, id_type und id_number.
| Feld | Typ | Hinweise |
|---|---|---|
status | string | active, vip oder blocked. |
is_local_verified | boolean | Ob der Gast als einheimischer Bewohner verifiziert ist (schaltet Raten nur für Einheimische frei). |
PATCH /guests/{id}Scope: guests:write
Aktualisieren Sie jedes veränderbare Feld. Senden Sie nur, was sich ändert. Über local_verified markiert ein Verwaltungsablauf einen Gast als verifizierten einheimischen Bewohner (dabei wird der Zeitpunkt der Verifizierung festgehalten).
| Body-Feld | Hinweise |
|---|---|
first_name, last_name, phone, nationality, address | Profilfelder. |
status | active, vip oder blocked. |
local_verified | Boolescher Wert. true schaltet für diesen Gast Raten nur für Einheimische frei. |
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 }'Liefert den aktualisierten Gast in derselben Struktur wie GET /guests/{id}.
GET /guests/{id}/loyaltyScope: loyalty:read
Punktestand, Lebenszeitpunkte, aktuelle Stufe, Fortschritt zur nächsten Stufe und das jüngste Journal eines Gastes. Gäste ohne bisherige Treueaktivität liefern ein auf null gesetztes Konto statt eines 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" }
]
}| Feld | Typ | Hinweise |
|---|---|---|
points_balance | integer | Einlösbare Punkte. |
lifetime_points | integer | Kumulierte gesammelte Punkte (bestimmen die Stufe, werden nie verringert). |
tier | string | Name der aktuellen Stufe. |
next_tier | object | null | Die nächste Stufe und ihre Schwelle, oder null in der höchsten Stufe. |
recent_transactions | array | Bis zu 10 jüngste Journaleinträge (earn, redeem, expire, adjust). |
POST /loyalty/redemptionsScope: loyalty:write
Belastet die Punkte eines Gastes und schreibt einen redeem-Eintrag ins Journal. Der Punktestand wird atomar geprüft, eine Einlösung kann das Konto also nie überziehen; eine zu hohe Einlösung liefert 409 insufficient_points.
| Body-Feld | Erforderlich | Hinweise |
|---|---|---|
guest_id | ja | Muss zu dieser Unterkunft gehören. |
points | ja | Positive Ganzzahl. |
reservation_id | nein | Verknüpft die Einlösung mit einem Aufenthalt; muss zu dieser Unterkunft und diesem Gast gehören. |
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"
}Nutzen Sie redeemed_value_usd als Rabatt, den Sie in Ihrem eigenen Checkout anwenden. Punkte werden bei bestätigten Aufenthalten in USD automatisch gesammelt (siehe Reservierungen).
- Reservierungen: Holds und Bestätigungen, die Treuepunkte einbringen.
- Authentifizierung: wie das Scoping personenbezogener Daten funktioniert.