Flux de réservation

Le flux type d’un moteur de réservation : obtenir un jeton, lister les chambres pour les dates et l’occupation recherchées par le client, appliquer le tarif choisi et un éventuel coupon, effectuer l’étape de paiement, puis enregistrer la réservation dans HMS avec BookingPushRQ. Ce guide détaille chaque étape avec de vraies requêtes et réponses.

1Connexion/external/public/login
2Liste des chambres/external/online/roomType
3Coupon · Forfaitscoupon/search · stock/packages
4Paiementpayment/type/{type}
5Transmissionchannel/booking

1. Obtenir un jeton#

Connectez-vous une fois au démarrage de votre serveur ou à l’expiration du jeton, et stockez le jeton avec l’identifiant de l’hôtel. Détails : Authentification.

2. Lister les chambres#

Demandez la liste des chambres avec les valeurs du formulaire de recherche du client. S’il y a des enfants, envoyez leur âge ; la tarification enfant est calculée en fonction de l’âge.

Terminal
curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "startDate=2026-08-18" -d "endDate=2026-08-20" \
  -d "adultCount=2" -d "childCount=1" -d "childAges[]=7" -d "language=en"

Ce qu’il faut afficher pour chaque type de chambre de la réponse :

ChampÀ l’écran
name, images[], detail, roomFeatures[]Fiche de la chambre
roomCountChambres restantes. 0 signifie « non disponible à la vente » — la raison figure dans roomRestrictionMessage.
accommodationTypes[].titleFormule de pension (Petit-déjeuner inclus, Demi-pension…)
accommodationTypes[].prices{}Options tarifaires : standard et non remboursable

Les clés de l’objet prices sont de la forme "<persons>-<1|0>". Le suffixe 1 désigne le tarif standard (remboursable), 0 le tarif non remboursable ; l’option non remboursable porte nonRefundable: "[NR]". En tarification par chambre (priceType: 1), la clé est 1-1 / 1-0 quelle que soit l’occupation.

accommodationTypes[0].prices
{
    "2-1": {
        "total": 2,
        "title": 2,
        "nonRefundable": "",
        "price": "1930.00",
        "currency": "TRY",
        "id": "2/2",
        "prices": [
            {
                "price": "965.00",
                "tarih": "18.08.2026"
            },
            {
                "price": "965.00",
                "tarih": "19.08.2026"
            }
        ]
    },
    "2-0": {
        "total": 2,
        "title": 2,
        "nonRefundable": "[NR]",
        "price": "1737.00",
        "currency": "TRY",
        "id": "2-0/2",
        "prices": [
            {
                "price": "868.50",
                "tarih": "18.08.2026"
            },
            {
                "price": "868.50",
                "tarih": "19.08.2026"
            }
        ]
    }
}

3. Coupons et forfaits#

Si le client saisit un coupon, validez-le et appliquez la réduction de votre côté :

Terminal
curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"
Réponse · 200
{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Si change vaut 0, rate est une réduction en pourcentage (10 %) ; s’il vaut 1, il s’agit d’un montant fixe (10.00 dans la devise de l’hôtel). Appliquez la réduction au montant de la chambre et envoyez les totaux remisés dans la réservation.

Pour vendre des extras, affichez la liste des forfaits. Les forfaits choisis sont ajoutés à la réservation dans extras[], avec l’id du forfait dans stockID. Les totaux après coupons et forfaits sont inscrits dans le Total de la réservation.

4. Étape de paiement#

Listez les types de paiement acceptés par l’hôtel et poursuivez selon le choix du client. Pour le type 10 (paiement en ligne), une session de paiement est ouverte et le client est redirigé vers le prestataire ; après le paiement, il revient sur votre returnUrl. Tous les types sont décrits dans le guide Flux de paiement.

5. Transmettre la réservation#

Une fois le résultat du paiement connu, enregistrez la réservation dans HMS. ID est le code unique que vous générez ; communiquez ce même code au client. Les identifiants de type de chambre et de type de pension proviennent de la liste des chambres.

Requête
curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @booking.json
Réponse · 200
{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID est l’identifiant de la réservation dans HMS ; conservez-le avec votre propre enregistrement. La réservation apparaît dans le panneau sous le canal « Online », et HMS envoie au client un e-mail de confirmation selon les paramètres de l’hôtel.

Plusieurs chambres#

Lorsque plusieurs chambres du même type de chambre et du même type de pension sont vendues, chaque chambre forme un élément RoomStays distinct ; NumberOfUnits vaut "1" pour la première, "2" pour la deuxième, et ainsi de suite. Des types de chambre différents font eux aussi l’objet d’éléments distincts. Le Total de la réservation est la somme de toutes les chambres et de tous les extras.

Modifications et annulations#

Renvoyez la réservation au même endpoint avec le même ID :

  • type: "Modify" — les dates, les chambres ou les informations du client ont changé. Envoyez la réservation complète dans son état actuel ; HMS remplace l’enregistrement existant par celle-ci.
  • type: "Cancel" — la réservation a été annulée. Les chambres portent elles aussi type: "Cancel".

Erreurs fréquentes#

  • Mettre la liste des chambres en cache trop longtemps. Les disponibilités et les tarifs changent en permanence ; actualisez la liste avant que le client n’accède à l’étape de paiement.
  • Envoyer un childCount différent de la longueur de childAges[] : le serveur se fie à la liste des âges et modifie le nombre d’enfants sans avertissement.
  • Envoyer vos propres identifiants comme roomTypeID / ratePlanID au lieu de ceux de la liste des chambres : Could not register. est renvoyé.
  • Envoyer PaymentCard pour d’autres types de paiement que le 9 : les données de carte sont transmises à HMS inutilement.
  • Relancer après une erreur réseau avec un ID différent : cela crée une réservation en double. Relancez avec le même ID.
Dernière mise à jour: 21 septembre 2026Vous avez repéré une erreur ? Signalez-la-nous