Clients et fidélité

Les clients sont les personnes à qui appartient une réservation. Chaque client vit sous un seul établissement et porte un compte de fidélité facultatif, qui cumule des points sur les séjours confirmés et peut être utilisé pour obtenir une remise.

Enregistrer ou rattacher un client

POST /guests

Portée : guests:write

Retrouve un client par (property, email) ou en crée un. L'appel est idempotent sur l'e-mail : le rappeler pour la même adresse rattache le client existant au lieu de créer un doublon, vous pouvez donc l'émettre sans risque à chaque réservation.

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 }

Renvoie 201 avec "created": true pour un nouveau client, ou 200 avec "created": false quand un client existant a été rattaché.

Lire un client

GET /guests/{id}

Portée : guests:read (les champs de données personnelles exigent en plus guests:read:pii)

curl "$VRDN_BASE/guests/3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34" -H "Authorization: Bearer $VRDN_KEY"

Avec guests:read seul :

{
  "id": "3f8a2c1b-9d4e-4c6a-8b7f-5e2d1a9c0b34",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "nationality": "GB",
  "status": "active",
  "is_local_verified": false
}

Avec guests:read:pii, la réponse comprend en plus email, phone, address, date_of_birth, id_type et id_number.

Mettre à jour un client

PATCH /guests/{id}

Portée : guests:write

Modifiez n'importe quel champ modifiable. N'envoyez que ce qui change. C'est en réglant local_verified qu'un parcours d'administration marque un client comme résident local vérifié (l'heure de vérification est alors enregistrée).

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 }'

Renvoie le client mis à jour, dans la même structure que GET /guests/{id}.

Lire la situation de fidélité

GET /guests/{id}/loyalty

Portée : loyalty:read

Le solde de points d'un client, ses points cumulés à vie, son niveau actuel, sa progression vers le niveau suivant et l'historique récent. Un client sans aucune activité de fidélité renvoie un compte à zéro plutôt qu'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" }
  ]
}

Utiliser des points de fidélité

POST /loyalty/redemptions

Portée : loyalty:write

Débite les points d'un client et inscrit une écriture redeem. Le solde est vérifié de façon atomique, une utilisation ne peut donc jamais aller à découvert ; un dépassement renvoie 409 insufficient_points.

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"
}

Servez-vous de redeemed_value_usd comme remise à appliquer dans votre propre parcours de paiement. Les points sont cumulés automatiquement sur les séjours confirmés en USD (voyez Réservations).

Pages liées

• Réservations : les blocages et les confirmations qui cumulent de la fidélité.
• Authentification : comment fonctionne le cloisonnement des données personnelles.