Idempotence & réservations sûres

Une réservation se joue une seule fois. Cette page décrit les mécanismes qui vous protègent des doublons et des réservations incertaines.

`clientReference` : obligatoire et unique

Chaque réservation porte votre référence (clientReference, ex. PARTNER-2026-000481) :

Elle est obligatoire dans POST /v1/{code}/bookings.
Elle est unique par partenaire : si vous renvoyez la même requête avec la même clientReference, la passerelle renvoie la même réservation (200 OK), avec l'en-tête X-Idempotent-Replay: true — aucune seconde réservation n'est créée, aucun second débit n'est fait.
Une clientReference nouvelle avec le même rateKey créera une nouvelle réservation (si le tarif est encore garanti).

Le doublon renvoie la réservation existante

# 1er appel  → 201 Created,   reference: BPG-2026-000123
# 2e appel identique → 200 OK, reference: BPG-2026-000123, X-Idempotent-Replay: true

Générez une clientReference avant l'appel et conservez-la : c'est elle qui vous permet de retrouver une réservation après un timeout, sans risque de double réservation.

Règles de retry

Opération	Retry autorisé ?
`POST /bookings`	Jamais d'appel « nouveau » : rejouez la même requête avec la même `clientReference`
`POST /checkrate`, `POST /availability`	Oui (lecture métier, sans effet de bord)
`GET *` (hôtels, réservations, voucher…)	Oui, un nouvel essai unique en cas d'erreur ou de timeout
`POST /bookings/{ref}/cancel`	Idempotent par nature : rejouer renvoie l'état courant de l'annulation

Prix garanti 10 minutes

Après un checkrate réussi, le prix est garanti pendant 10 minutes (expiresAt dans la réponse) :

Réservez dans cette fenêtre avec le rateKey vérifié : le prix ne bougera pas.
Passé expiresAt, le rateKey est refusé (422 rate_expired) : relancez une recherche puis un checkrate.

Timeouts conseillés

Appel	Timeout client conseillé
Lectures (`hotels`, `reference`, `bookings`…)	15 s
`availability`, `checkrate`	25 s
`bookings` (création)	45 s

En cas de timeout sur une création de réservation, ne relancez pas avec une nouvelle clientReference : rejouez la même requête, ou lisez la réservation via GET /v1/{code}/bookings?from=…&to=… pour vérifier son existence.

Côté portes compatibles

OS-Travel — le Token de la recherche joue le rôle du rateKey ; BookingCreation sans PreBooking confirme la pré-réservation. Voir OS-Travel.
Cyberesa — le QuoteId + IdToken rejoués dans HotelBookingCreationREQ garantissent la cohérence avec le devis ; expectedprice permet de détecter un écart de prix. Voir Cyberesa.