Réservations : Parcours de réservation

Réservation
Réservation
8 routes

Comment transformer une intention de réservation en option confirmée ?

Ce guide décrit le parcours permettant de transformer une intention de réservation en option confirmée via l'API Club Med.

Il couvre la recherche de propositions, la gestion des services et assurances optionnels, la qualification des participants, puis la création de la réservation.

Vue d'ensemble

Ce scénario documente un parcours de préparation de réservation qui commence par la recherche de proposition et se termine par la création du booking.

Prérequis

Une x-api-key valide et un header accept-language cohérent.
Les critères de réservation nécessaires pour rechercher une proposition.
Un proposal_id retourné par la recherche avant l'ajout de services, d'assurance ou de données participants.

Résultat attendu

L'application peut créer ou retrouver une proposition, l'enrichir avec des services optionnels ou une assurance, qualifier les participants et créer l'option de réservation.

Process workflow

Legend:

Obligatoire

Optionnel

Rechercher les propositions correspondantes

Obligatoire

Utilisez POST/v3/proposals/search pour creer la proposition qui pilotera le parcours de reservation. Cette premiere etape calcule le prix, le stock et l'optionabilite a partir des criteres soumis puis retourne le proposal_id necessaire a toutes les etapes suivantes.

Prerequis

Envoyer accept-language et x-api-key.
Ajouter authorization si le contexte vendeur ou partenaire le demande.
Preparer un payload de reservation avec produit, dates, nombre de participants et contexte de package.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v3/proposals/search' \
  -H 'accept: application/json' \
  -H 'accept-language: fr-FR' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Example answer

{
  "id": "123456",
  "product_id": "MPAC",
  "price": {
    "total": 9815.4,
    "currency": "EUR"
  },
  "remaining_stock": 2,
  "option_available": true
}

info: Le proposal_id retourne devient le dossier de travail pour les services, les attendees, l'assurance et la creation du booking.

Codes de reponse

200 OK : retourne la proposition correspondant aux criteres soumis.
400 Bad Request : le payload est invalide, incomplet ou incoherent.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
403 Forbidden : le contexte courant ne peut pas creer la proposition.
404 Not Found : le produit est introuvable.
409 Conflict : les criteres de proposition ne sont plus valides.

POST/v3/proposals/search

Lister les services additionnels disponibles

Optionnel

Utilisez GET/v0/additional_services avec proposal_id pour lister les services additionnels disponibles sur la proposition. Cette etape sert en general a exposer des upsells comme le childcare, les transferts, les locations ou les activites avant la qualification finale du dossier.

Prerequis

Reutiliser un proposal_id valide.
Envoyer accept-language et x-api-key.
Ajouter types si vous souhaitez vous concentrer sur une seule famille de services.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v0/additional_services?proposal_id=123456' \
  -H 'accept: application/json' \
  -H 'accept-language: fr-FR' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "VMOSK1",
    "type": "CHILDCARE",
    "currency": "EUR",
    "schedules": [
      {
        "start_date": "20100430",
        "end_date": "20100430",
        "remaining_stock": 2
      }
    ]
  }
]

info: N'attachez ensuite que des services issus de cette reponse. C'est la liste de reference des upsells compatibles.

Codes de reponse

200 OK : retourne les services disponibles pour la proposition.
206 Partial Content : le resultat est partiel et d'autres pages peuvent exister.
400 Bad Request : la proposition ou les filtres sont invalides.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
403 Forbidden : le marche ou l'authentification courante ne permet pas cette consultation.
404 Not Found : la proposition est introuvable.
409 Conflict : les criteres de proposition ne sont plus valides.
416 Requested Range Not Satisfiable : la plage demandee est invalide.

GET/v0/additional_services

Ajouter les services additionnels sélectionnés

Optionnel

Utilisez PUT/v0/proposals/{proposal_id}/services pour appliquer les services additionnels selectionnes a la proposition. Cette route fonctionne en mode cancel-and-replace, donc chaque appel doit renvoyer la selection complete de services que vous souhaitez conserver.

Prerequis

Fournir proposal_id.
Envoyer accept-language, authorization si necessaire, et x-api-key.
Construire le payload a partir des identifiants retournes par la recherche de services.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v0/proposals/123456/services' \
  -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: Comme la route est cancel-and-replace, oublier un service precedemment choisi revient a le retirer de la proposition.

Codes de reponse

204 No Content : les services de la proposition ont ete mis a jour avec succes.
400 Bad Request : les services sont incompatibles, manquants ou le payload est invalide.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
404 Not Found : la proposition est introuvable.
409 Conflict : la proposition n'est plus economiquement valide.

PUT/v0/proposals/{proposal_id}/services

Qualifier les participants de la proposition

Obligatoire

Utilisez PUT/v3/proposals/{proposal_id}/attendees pour attacher ou mettre a jour les participants sur la proposition avant de la transformer en booking. C'est ici que sont valides l'identite, la composition des foyers et les liens clients.

Prerequis

Fournir proposal_id.
Envoyer accept-language, authorization si necessaire, et x-api-key.
Preparer un payload participants conforme aux regles sur les dates de naissance, les documents et la coherence des foyers.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v3/proposals/123456/attendees' \
  -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

[
  {
    "attendees": [
      {
        "id": "A",
        "customer_id": "123456789",
        "customer_status": "NEW_CUSTOMER",
        "loyalty_status": "GOLD"
      }
    ]
  }
]

info: La plupart des problemes bloquants de qualite de donnees ressortent ici, il faut donc bien exposer les erreurs cote interface.

Codes de reponse

200 OK : retourne la structure attendees mise a jour.
400 Bad Request : les donnees participants sont invalides, incompletes, dupliquees ou incoherentes.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
403 Forbidden : au moins un client ne peut pas poursuivre le parcours.
409 Conflict : la proposition n'est plus economiquement valide.

PUT/v3/proposals/{proposal_id}/attendees

Lister les options d'assurance disponibles

Optionnel

Utilisez GET/v0/additional_services avec types=INSURANCE pour lister les produits d'assurance disponibles sur la proposition. Cette etape isole le sous-ensemble assurance afin de permettre a l'utilisateur de comparer les garanties avant de les ajouter ou de les remplacer.

Prerequis

Reutiliser un proposal_id valide.
Envoyer accept-language et x-api-key.
Ajouter types=INSURANCE pour limiter la reponse aux assurances.

Calling CURL

curl -X 'GET' \
  'https://api.clubmed.com/v0/additional_services?proposal_id=123456&types=INSURANCE' \
  -H 'accept: application/json' \
  -H 'accept-language: fr-FR' \
  -H 'x-api-key: YOUR_API_KEY'

Example answer

[
  {
    "id": "TRAVEL_INSURANCE",
    "type": "INSURANCE",
    "currency": "EUR",
    "schedules": [
      {
        "start_date": "20100430",
        "end_date": "20100430",
        "remaining_stock": 99
      }
    ]
  }
]

info: Filtrer la recherche de services sur INSURANCE permet de concentrer l'interface sur le choix d'assurance sans noyer l'utilisateur dans tout le catalogue.

Codes de reponse

200 OK : retourne les assurances disponibles pour la proposition.
206 Partial Content : le resultat est partiel et d'autres pages peuvent exister.
400 Bad Request : la proposition ou les filtres sont invalides.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
403 Forbidden : le marche ou l'authentification courante ne permet pas cette consultation.
404 Not Found : la proposition est introuvable.
409 Conflict : les criteres de proposition ne sont plus valides.
416 Requested Range Not Satisfiable : la plage demandee est invalide.

GET/v0/additional_services

Ajouter l'assurance sélectionnée

Optionnel

Utilisez PUT/v0/proposals/{proposal_id}/services pour appliquer l'assurance selectionnee a la proposition. Comme la route fonctionne en cancel-and-replace, le payload assurance doit etre fusionne avec tous les autres services que vous souhaitez conserver.

Prerequis

Fournir proposal_id.
Envoyer accept-language, authorization si necessaire, et x-api-key.
Construire le payload assurance a partir des identifiants retournes par l'etape de recherche d'assurance.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v0/proposals/123456/services' \
  -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: N'envoyez jamais uniquement la nouvelle assurance si d'autres services doivent rester sur la proposition. La route remplace toute la liste de services.

Codes de reponse

204 No Content : les services de la proposition ont ete mis a jour avec succes.
400 Bad Request : les services sont incompatibles, manquants ou le payload est invalide.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
404 Not Found : la proposition est introuvable.
409 Conflict : la proposition n'est plus economiquement valide.

PUT/v0/proposals/{proposal_id}/services

Retirer une assurance de la proposition

Optionnel

Utilisez PUT/v0/proposals/{proposal_id}/services pour retirer une assurance de la proposition en renvoyant une liste de services mise a jour sans cette assurance. Comme la route remplace la liste complete, la suppression se fait par omission dans le nouveau payload.

Prerequis

Fournir proposal_id.
Envoyer accept-language, authorization si necessaire, et x-api-key.
Partir de l'etat courant des services de la proposition afin de ne retirer que l'assurance ciblee.

Calling CURL

curl -X 'PUT' \
  'https://api.clubmed.com/v0/proposals/123456/services' \
  -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: Pour retirer une seule assurance en toute securite, reconstruisez le payload a partir de l'etat le plus recent des services plutot que de le recomposer de memoire.

Codes de reponse

204 No Content : la liste des services a ete mise a jour avec succes.
400 Bad Request : les services sont incompatibles, manquants ou le payload est invalide.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
404 Not Found : la proposition est introuvable.
409 Conflict : la proposition n'est plus economiquement valide.

PUT/v0/proposals/{proposal_id}/services

Créer l'option de réservation

Obligatoire

Utilisez POST/v3/bookings pour creer l'option de reservation a partir de la proposition qualifiee. C'est l'etape qui transforme la proposition en dossier de booking et consomme le stock Club Med.

Prerequis

Envoyer accept-language, authorization si necessaire, et x-api-key.
Verifier que les donnees participants ont deja ete qualifiees sur la proposition.
Conserver la meme locale que celle utilisee pour la creation et la qualification de la proposition.

Calling CURL

curl -X 'POST' \
  'https://api.clubmed.com/v3/bookings' \
  -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

{
  "booking_id": "654321",
  "households": [
    {
      "attendees": [
        {
          "customer_id": 987654,
          "type": "MAIN"
        }
      ]
    }
  ],
  "option_durability": {
    "is_reliable": true,
    "expiration_date_time": "20160415T10:23:00.234Z"
  }
}

info: La creation du booking est l'etape engageante du parcours. En cas d'echec, l'erreur pointe souvent vers des donnees de proposition obsoletes, des services manquants ou des incoherences attendees.

Codes de reponse

200 OK : le booking a ete cree et les donnees de confirmation sont retournees.
201 Created : le booking a ete cree avec succes.
400 Bad Request : le payload est invalide ou une donnee obligatoire manque.
401 Unauthorized : l'authentification est absente, invalide ou expiree.
403 Forbidden : le contexte courant n'est pas autorise a creer le booking.
409 Conflict : les conditions de prix, de stock, de promotion ou de transport ne sont plus valides.
419 : le vol associe n'est plus disponible.

POST/v3/bookings