Comparer et appliquer des contre-propositions

  • Services
  • 10 routes
Comment identifier, comparer et appliquer une contre-proposition Club Med ?

Ce scénario explique comment Club Med expose des contre-propositions autour d'une demande de voyage. Le parcours couvre d'abord la suggestion de dates alternatives à partir des critères de recherche, puis l'exploration d'alternatives sur une proposition déjà créée, comme le package, le tarif, le transport ou l'hébergement.

L'objectif est d'aider un intégrateur à construire un écran de comparaison fiable : partir d'une proposition de référence, lire son état courant, la rafraîchir si nécessaire, puis présenter uniquement les variantes réellement applicables.

Vue d'ensemble

La notion de contre-proposition ne correspond pas à une seule route. Elle s'appuie sur plusieurs ressources qui interviennent à différents moments du tunnel de réservation :

  • avant la sélection finale, avec POST/v0/proposals/date_suggestion pour proposer d'autres dates ;
  • après la création d'une proposition, avec des routes dédiées aux alternatives de package, de tarif, de transport ou de confort d'hébergement.

Prérequis

  • Disposer d'une x-api-key valide.
  • Fournir un accept-language sur les routes qui l'exigent.
  • Avoir les critères de réservation permettant de créer une proposition de référence.
  • Disposer d'un proposal_id valide pour les étapes de lecture, rafraîchissement et arbitrage des alternatives.
  • Prévoir un bearer token lorsque votre contexte d'intégration le requiert.

Résultat attendu

À la fin du parcours, l'application peut :

  • générer une proposition de référence ;
  • lister des contre-propositions par date ;
  • relire puis rafraîchir la proposition retenue ;
  • afficher les alternatives applicables sur le package, le tarif, le transport et l'hébergement ;
  • appliquer une alternative de package ou de tarif lorsque la route correspondante est utilisée.

Process workflow

Legend:
Obligatoire
Optionnel
1

Créer une proposition de référence

Obligatoire

Cette route crée une proposition de référence à partir des critères de séjour initiaux.

Prérequis

Préparez les critères de séjour, les participants et le produit cible avant de lancer les comparaisons.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "product-1", "start_date": "2026-07-05", "end_date": "2026-07-12", "attendees": [{"birthdate": "1990-03-12"}, {"birthdate": "2016-05-20"}]}' \
  "https://api.clubmed.com/v1/proposals/search/best"

Example answer

{
  "id": "proposal-1",
  "product_id": "product-1",
  "stay": {
    "start_date": "2026-07-05",
    "end_date": "2026-07-12"
  },
  "price": {
    "amount": 2890,
    "currency": "EUR"
  },
  "option_available": true
}

info: La proposition de référence sert de point de comparaison pour toutes les contre-propositions ensuite.

Codes de réponse

  • 200 OK : la proposition de référence est renvoyée.
  • 400 Bad Request : critères invalides ou JSON mal formé.
  • 401 Unauthorized : jeton manquant ou invalide.
  • 403 Forbidden : contexte commercial non autorisé.
  • 404 Not Found : produit introuvable.
POST/v1/proposals/search/best
Voir plus
2

Lister les contre-propositions par date

Optionnel

Cette route retourne des contre-propositions fondées sur d'autres dates de séjour.

Prérequis

Réutilisez les critères de la proposition de référence et ciblez la même configuration de participants.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "product-1", "start_date": "2026-07-05", "end_date": "2026-07-12", "attendees": [{"birthdate": "1990-03-12"}, {"birthdate": "2016-05-20"}]}' \
  "https://api.clubmed.com/v0/proposals/date_suggestion"

Example answer

{
  "date_suggestion": [
    {
      "start_date": "2026-07-12",
      "end_date": "2026-07-19",
      "price": {
        "amount": 2750,
        "currency": "EUR"
      }
    }
  ],
  "price_currency": "EUR"
}

info: Cette vue est utile pour arbitrer rapidement entre flexibilité de dates et niveau de prix.

Codes de réponse

  • 200 OK : la liste des suggestions de dates est renvoyée.
  • 400 Bad Request : critères invalides ou JSON mal formé.
  • 401 Unauthorized : jeton manquant ou invalide.
  • 403 Forbidden : accès refusé.
  • 404 Not Found : produit introuvable.
  • 409 Conflict : les critères ne sont plus valides.
POST/v0/proposals/date_suggestion
Voir plus
3

Lire la proposition retenue

Obligatoire

Cette route relit la proposition retenue pour récupérer son état complet avant arbitrage.

Prérequis

Munissez-vous de l'identifiant de proposition choisi lors des étapes précédentes.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  "https://api.clubmed.com/v2/proposals/{proposal_id}"

Example answer

{
  "id": "proposal-1",
  "price": {
    "amount": 2890,
    "currency": "EUR"
  },
  "alternative_price": {
    "amount": 2750,
    "currency": "EUR"
  },
  "remaining_stock": 4,
  "transportation_summary": {
    "is_transportation_included": true
  }
}

info: Utilisez cette lecture pour sécuriser les comparaisons avant d'appliquer une contre-proposition.

Codes de réponse

  • 200 OK : la proposition est renvoyée.
  • 400 Bad Request : paramètres invalides.
  • 409 Conflict : proposition invalide ou conditions économiques non applicables.
GET/v2/proposals/{proposal_id}
Voir plus
4

Rafraîchir la proposition avant arbitrage

Optionnel

Cette route rafraîchit la proposition pour recalculer stock et prix avant décision finale.

Prérequis

Appelez-la juste avant d'arbitrer si la proposition a été consultée il y a plusieurs minutes.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"refresh_stock": true}' \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/refresh"

Example answer

{
  "id": "proposal-1",
  "remaining_stock": 3,
  "price": {
    "amount": 2910,
    "currency": "EUR"
  }
}

info: Un refresh évite d'appliquer une contre-proposition sur des données déjà obsolètes.

Codes de réponse

  • 200 OK : la proposition rafraîchie est renvoyée.
  • 400 Bad Request : JSON invalide.
  • 401 Unauthorized : jeton manquant ou invalide.
  • 403 Forbidden : accès refusé.
  • 409 Conflict : un service ou un composant n'est plus disponible.
POST/v1/proposals/{proposal_id}/refresh
Voir plus
5

Consulter les packages alternatifs

Optionnel

Cette route liste les packages alternatifs applicables à la proposition.

Prérequis

Utilisez une proposition existante et encore valide.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  "https://api.clubmed.com/v0/proposals/{proposal_id}/alternative_packages"

Example answer

[
  {
    "id": "AI",
    "differential_price": {
      "amount": 42,
      "currency": "EUR"
    }
  }
]

info: Le différentiel de prix aide à identifier rapidement un package plus riche ou plus économique.

Codes de réponse

  • 200 OK : les packages alternatifs sont renvoyés.
  • 400 Bad Request : paramètres invalides.
GET/v0/proposals/{proposal_id}/alternative_packages
Voir plus
6

Appliquer un package alternatif

Optionnel

Cette route applique le package alternatif choisi à la proposition.

Prérequis

Réutilisez l'identifiant package renvoyé à l'étape précédente.

Calling CURL

curl -X PUT \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"id": "AI"}' \
  "https://api.clubmed.com/v0/proposals/{proposal_id}/alternative_packages"

Example answer

HTTP/1.1 204 No Content

info: Le succès est retourné sans body. Relisez ensuite la proposition si vous devez afficher le résultat consolidé.

Codes de réponse

  • 204 No Content : le package est appliqué.
  • 400 Bad Request : package indisponible, validation échouée ou JSON invalide.
  • 403 Forbidden : clé API invalide.
  • 404 Not Found : proposition introuvable.
PUT/v0/proposals/{proposal_id}/alternative_packages
Voir plus
7

Consulter les tarifs alternatifs

Optionnel

Cette route retourne les tarifs alternatifs applicables à la proposition.

Prérequis

Utilisez une proposition encore valide pour comparer les politiques tarifaires disponibles.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  "https://api.clubmed.com/v0/proposals/{proposal_id}/alternative_rates"

Example answer

[
  {
    "type": "FLEXIBLE_RATE",
    "currency": "EUR",
    "price_difference": 42
  }
]

info: Cette lecture permet d'anticiper l'impact prix avant de basculer vers un autre tarif.

Codes de réponse

  • 200 OK : les tarifs alternatifs sont renvoyés.
  • 400 Bad Request : paramètres invalides.
GET/v0/proposals/{proposal_id}/alternative_rates
Voir plus
8

Appliquer un tarif alternatif

Optionnel

Cette route applique un tarif alternatif sur la proposition.

Prérequis

Réutilisez le type de tarif choisi après comparaison des écarts de prix.

Calling CURL

curl -X PUT \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"type": "FLEXIBLE_RATE"}' \
  "https://api.clubmed.com/v0/proposals/{proposal_id}/rates"

Example answer

{
  "id": "proposal-1",
  "price": {
    "amount": 2890,
    "currency": "EUR"
  },
  "alternative_price": {
    "amount": 2750,
    "currency": "EUR"
  },
  "remaining_stock": 4,
  "transportation_summary": {
    "is_transportation_included": true
  }
}

info: Contrairement à d'autres routes d'application, cette route renvoie la proposition mise à jour dans le body.

Codes de réponse

  • 200 OK : la proposition mise à jour est renvoyée.
  • 400 Bad Request : paramètres invalides, validation échouée ou JSON invalide.
PUT/v0/proposals/{proposal_id}/rates
Voir plus
9

Consulter les transports alternatifs

Optionnel

Cette route retourne le transport appliqué et les alternatives disponibles pour la proposition.

Prérequis

Réutilisez une proposition éligible au transport. Conservez l'identifiant du transport sélectionné pour l'étape suivante.

Calling CURL

curl -X POST \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  -H "Content-Type: application/json" \
  -d '{"journeys": [{"transport_class": "STANDARD"}]}' \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/available_transports"

Example answer

[
  {
    "id": "transport-1",
    "is_applied_transportation": false,
    "time_validity_limit": "2026-07-01T10:00:00Z",
    "price": {
      "amount": 220,
      "currency": "EUR"
    },
    "total_differential_price": {
      "amount": 80,
      "currency": "EUR"
    },
    "journeys": [
      {
        "travel_sections": [
          {
            "departure_point": "Paris",
            "arrival_point": "Valmorel",
            "transport_class": "STANDARD"
          }
        ]
      }
    ]
  }
]

info: La description et le cURL sont alignés sur la bonne route Swagger available_transports.

Codes de réponse

  • 200 OK : les transports alternatifs sont renvoyés.
  • 400 Bad Request : la proposition n'est pas éligible au transport ou le JSON est invalide.
  • 404 Not Found : la proposition est introuvable.
POST/v1/proposals/{proposal_id}/available_transports
Voir plus
10

Consulter les meilleurs hébergements alternatifs

Optionnel

Cette route retourne une sélection de meilleurs hébergements alternatifs pour la proposition.

Prérequis

Vous pouvez affiner avec is_pmr_room_priority, is_family_room ou is_mixable_room selon votre logique métier.

Calling CURL

curl -X GET \
  -H "x-api-key: $API_KEY" \
  -H "accept-language: fr-FR" \
  "https://api.clubmed.com/v1/proposals/{proposal_id}/best_accommodations?is_family_room=true"

Example answer

{
  "alternative_accommodations": [
    {
      "id": "room-2",
      "label": "Family Superior Room"
    }
  ],
  "price": {
    "amount": 120,
    "currency": "EUR"
  }
}

info: Utilisez cette lecture pour proposer une alternative d'hébergement argumentée sans quitter la proposition courante.

Codes de réponse

  • 200 OK : les meilleurs hébergements alternatifs sont renvoyés.
  • 400 Bad Request : paramètres invalides.
  • 401 Unauthorized : jeton manquant ou invalide.
GET/v1/proposals/{proposal_id}/best_accommodations
Voir plus