Parcours réservation complet

Réservation
Réservation
6 routes

Comment passer d'une proposition à un booking validé et contrôlé ?

Ce parcours couvre un enchaînement complet de réservation, depuis la recherche de proposition jusqu'au contrôle du booking validé. Il ajoute aux étapes de création la consultation de l'échéancier de paiement et l'étape de validation du dossier par paiement.

Le scénario est adapté à une documentation fonctionnelle de bout en bout, avec un accent particulier sur les dépendances entre proposition, booking et paiement.

Vue d'ensemble

Ce scénario documente un parcours de réservation complet lorsque l'on souhaite suivre tout le cycle principal: recherche de proposition, préparation, lecture de l'échéancier, création du booking, validation par paiement et contrôle final du dossier.

Prérequis

Disposer d'un x-api-key valide et d'une locale cohérente sur tout le parcours.
Fournir un jeton authorization pour les routes protégées.
Être capable d'obtenir ou de construire une proposition exploitable avant création du booking.
Disposer du booking_id après création, puis du customer_id pour la relecture finale.
Prévoir les informations de paiement nécessaires à la validation, même si le détail exact du payload n'est pas visible dans l'extrait documentaire.

Résultat attendu

Le parcours doit aboutir à un booking validé, avec un suivi lisible des montants attendus et une réponse finale permettant de contrôler les statuts de réservation et de paiement.

Hypothèses de parcours

Le scénario retient une lecture de l'échéancier au niveau proposition avant la validation du booking. Il suppose également que la validation finale s'appuie sur PATCH/v2/bookings/{booking_id}, dont le comportement métier est documenté mais dont le corps de requête détaillé n'est pas exposé dans l'extrait disponible.

Process workflow

Legend:

Obligatoire

Optionnel

Rechercher une proposition optimale

Obligatoire

Cette étape utilise POST/v1/proposals/search/best pour rechercher la meilleure proposition correspondant aux critères de réservation. Elle renvoie un identifiant de proposition, des informations de prix, des éléments de stock et l'éligibilité éventuelle à une option.

Prérequis

Envoyer accept-language et x-api-key.
Ajouter authorization si le contexte client ou partenaire l'exige.
Préparer dans le body les critères de réservation nécessaires à la recherche.

Calling CURL

curl -X POST \
  -H "accept-language: fr-FR" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v1/proposals/search/best"

Example answer

{
  "id": "123456",
  "label": "Proposal with one club room",
  "product_id": "MPAC",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "option_available": true
}

info: Cette route sert surtout à obtenir la proposition optimale d'un contexte de réservation donné avant de qualifier les attendees ou de poursuivre le parcours.

Codes de réponse

200 OK : la meilleure proposition disponible est renvoyée.
400 Bad Request : les critères transmis sont incomplets, incohérents ou le JSON est invalide.
403 Forbidden : au moins un client ajouté n'est pas autorisé à poursuivre.
404 Not Found : le produit demandé est inconnu.

POST/v1/proposals/search/best

Préparer la pré-réservation

Obligatoire

Utilisez POST/v1/prebookings pour recuperer les premieres informations de prebooking a partir d'une proposition avec prix. Cette etape sert de controle intermediaire avant la creation du booking, notamment pour confirmer les attendees visibles et la coherence de transformation du dossier.

Prerequis

Envoyer accept-language, authorization si necessaire, et x-api-key.
Reutiliser une proposition deja calculee et exploitable dans le payload.
Conserver le meme contexte de locale que celui de la proposition.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v1/prebookings' \
  -H 'accept: application/json' \
  -H 'accept-language: fr-FR' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Example answer

[
  {
    "customer_id": "123456789",
    "type": "MAIN"
  }
]

info: Cette route ne cree pas encore le booking. Elle sert a verifier que la proposition priced peut etre interpretee correctement avant l'etape finale.

Codes de reponse

200 OK : retourne les informations de prebooking.
400 Bad Request : le payload est invalide, incomplet ou mal forme.
401 Unauthorized : l'authentification est absente, invalide ou expiree.

POST/v1/prebookings

Consulter l'échéancier de paiement

Obligatoire

Utilisez GET/v1/proposals/{proposal_id}/payment_schedule pour consulter l'echeancier de paiement associe a la proposition. Cette lecture permet de documenter les montants attendus, les deadlines et le decoupage des foyers avant la validation finale du booking.

Prerequis

Fournir proposal_id.
Envoyer x-api-key.
Conserver la proposition retenue jusqu'a l'etape de paiement finale.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v1/proposals/123456/payment_schedule' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

{
  "currency": "EUR",
  "commission_included": true,
  "households": [
    {
      "total": 9815.4,
      "deposit_repayment_schedule": [
        {
          "expected_payment_amount": 1200,
          "deadline": "2026-04-20"
        }
      ]
    }
  ]
}

info: Cette route aide a expliciter le plan de paiement cote interface avant le passage au booking puis a son paiement.

Codes de reponse

200 OK : retourne l'echeancier de paiement de la proposition.
400 Bad Request : la requete est invalide.
403 Forbidden : la proposition n'est pas accessible dans le contexte courant.
404 Not Found : la proposition est introuvable.
409 Conflict : la promotion ou le contexte commercial de la proposition n'est plus applicable.

GET/v1/proposals/{proposal_id}/payment_schedule

Créer le booking à partir de la proposition

Obligatoire

La route POST/v3/bookings crée un booking à partir de la proposition retenue. La documentation indique que la proposition doit déjà être qualifiée et que la création du booking décrémente le stock Club Med.

Prérequis

Envoyer accept-language et x-api-key.
Ajouter authorization si le contexte l'exige.
Conserver la même locale que celle utilisée pour créer et qualifier la proposition.
Préparer dans le body les données minimales attendues pour créer la réservation à partir de la proposition.

Calling CURL

curl -X POST \
  -H "accept-language: fr-FR" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "authorization: Bearer YOUR_TOKEN" \
  "https://api.clubmed.com/v3/bookings"

Example answer

{
  "booking_id": "0123456789",
  "attendees": [
    {
      "customer_id": "123456789",
      "type": "ADULT"
    }
  ]
}

info: La création du booking est l'étape qui fige la réservation à partir de la proposition qualifiée.

Codes de réponse

200 OK : le booking a été créé et renvoie les données de confirmation.
201 Created : le booking est créé avec succès.
400 Bad Request : le payload transmis est invalide ou incomplet.
403 Forbidden : certains usages, comme des paramètres réservés, ne sont pas autorisés.

POST/v3/bookings

Valider le booking par paiement

Obligatoire

Utilisez PATCH/v2/bookings/{booking_id} pour valider le booking au moyen d'un ou plusieurs paiements. Cette etape represente la confirmation finale du dossier une fois la proposition transformee en booking.

Prerequis

Fournir booking_id.
Envoyer accept-language, authorization si necessaire, x-agent-id si votre contexte le requiert, et x-api-key.
Preparer le payload de paiement attendu pour le booking cible.

Calling CURL

curl -X 'PATCH' \
  'https://api.clubmed.com/v2/bookings/0123456789' \
  -H 'accept: application/json' \
  -H 'accept-language: fr-FR' \
  -H 'authorization: Bearer YOUR_TOKEN' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Example answer

HTTP/1.1 204 No Content

info: Cette validation par paiement intervient apres la creation du booking. En cas de 204, le booking est confirme sans corps de reponse.

Codes de reponse

204 No Content : le booking a ete valide par paiement.
400 Bad Request : la requete ou le payload de paiement est invalide.
401 Unauthorized : l'authentification est absente, invalide ou expiree.

PATCH/v2/bookings/{booking_id}

Contrôler le booking final

Obligatoire

La route GET/v3/customers/{customer_id}/bookings/{booking_id} permet de relire le dossier validé dans le périmètre client. Elle donne accès aux statuts de réservation et de paiement, au détail des séjours, aux packages, aux hébergements et à plusieurs liens utiles.

Prérequis

Envoyer accept-language, authorization et x-api-key.
Fournir customer_id et booking_id.

Calling CURL

curl -X GET \
  -H "accept-language: fr-FR" \
  -H "authorization: Bearer YOUR_TOKEN" \
  -H "x-api-key: YOUR_API_KEY" \
  "https://api.clubmed.com/v3/customers/{customer_id}/bookings/{booking_id}"

Example answer

{
  "id": "12345",
  "booking_status": "VALIDATED",
  "payment_status": "PAID",
  "locale": "fr-FR"
}

info: Cette lecture finale permet de confirmer les statuts de réservation et de paiement dans le périmètre client.

Codes de réponse

200 OK : le détail du booking client est renvoyé.
403 Forbidden : le customer_id, l'issuer ou la locale ne correspondent pas.
404 Not Found : le booking est introuvable pour ce client.

GET/v3/customers/{customer_id}/bookings/{booking_id}