Ροή κράτησης

Η τυπική ροή μιας μηχανής κρατήσεων: λήψη token, λίστα δωματίων για τις ημερομηνίες και τον αριθμό ατόμων που αναζήτησε ο επισκέπτης, εφαρμογή της επιλεγμένης τιμής και τυχόν κουπονιού, ολοκλήρωση του βήματος πληρωμής και καταχώρηση της κράτησης στο HMS με BookingPushRQ. Αυτός ο οδηγός περιγράφει κάθε βήμα με πραγματικά αιτήματα και αποκρίσεις.

1Σύνδεση/external/public/login

2Λίστα δωματίων/external/online/roomType

3Κουπόνι · Πακέταcoupon/search · stock/packages

4Πληρωμήpayment/type/{type}

5Αποστολήchannel/booking

1. Λήψη token#

Συνδεθείτε μία φορά κατά την εκκίνηση του διακομιστή σας ή όταν λήξει το token, και αποθηκεύστε το token μαζί με το αναγνωριστικό του ξενοδοχείου. Λεπτομέρειες: Έλεγχος ταυτότητας.

2. Λίστα δωματίων#

Ζητήστε τη λίστα δωματίων με τις τιμές από τη φόρμα αναζήτησης του επισκέπτη. Αν ταξιδεύουν παιδιά, στείλτε τις ηλικίες τους· η τιμή των παιδιών υπολογίζεται με βάση την ηλικία.

Τερματικό

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"

Τι να εμφανίσετε για κάθε τύπο δωματίου της απόκρισης:

Πεδίο	Στην οθόνη
`name`, `images[]`, `detail`, `roomFeatures[]`	Κάρτα δωματίου
`roomCount`	Δωμάτια που απομένουν. Το 0 σημαίνει «δεν διατίθεται προς πώληση» — η αιτία στο `roomRestrictionMessage`.
`accommodationTypes[].title`	Επιλογή διατροφής (Με πρωινό, Ημιδιατροφή…)
`accommodationTypes[].prices{}`	Επιλογές τιμής: κανονική και μη επιστρέψιμη

Τα κλειδιά του αντικειμένου prices έχουν τη μορφή "<persons>-<1|0>". Η κατάληξη 1 είναι η κανονική (επιστρέψιμη) τιμή, η 0 η μη επιστρέψιμη τιμή· η μη επιστρέψιμη επιλογή φέρει nonRefundable: "[NR]". Με τιμολόγηση ανά δωμάτιο (priceType: 1) το κλειδί είναι 1-1 / 1-0 ανεξάρτητα από τον αριθμό ατόμων.

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. Κουπόνια και πακέτα#

Αν ο επισκέπτης εισαγάγει κουπόνι, επικυρώστε το και εφαρμόστε την έκπτωση από τη δική σας πλευρά:

Τερματικό

curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"

Απόκριση · 200

{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Με change 0, το rate είναι ποσοστιαία έκπτωση (10%)· με 1 είναι σταθερό ποσό (10.00 στο νόμισμα του ξενοδοχείου). Εφαρμόστε την έκπτωση στο ποσό του δωματίου και στείλτε τα μειωμένα σύνολα στην κράτηση.

Για να πουλήσετε επιπλέον υπηρεσίες, εμφανίστε τη λίστα πακέτων. Τα επιλεγμένα πακέτα μπαίνουν στην κράτηση ως extras[], με το id του πακέτου στο stockID. Τα σύνολα μετά από κουπόνια και πακέτα καταχωρούνται στο Total της κράτησης.

4. Βήμα πληρωμής#

Εμφανίστε τους τύπους πληρωμής που δέχεται το ξενοδοχείο και προχωρήστε ανάλογα με την επιλογή του επισκέπτη. Για τον τύπο 10 (online πληρωμή) ξεκινά μια συνεδρία πληρωμής και ο επισκέπτης μεταφέρεται στον πάροχο· μετά την πληρωμή επιστρέφει στο returnUrl σας. Όλοι οι τύποι καλύπτονται στον οδηγό Ροή πληρωμής.

5. Αποστολή της κράτησης#

Μόλις γίνει γνωστό το αποτέλεσμα της πληρωμής, καταχωρήστε την κράτηση στο HMS. Το ID είναι ο μοναδικός κωδικός που δημιουργείτε εσείς· δώστε τον ίδιο κωδικό και στον επισκέπτη. Τα αναγνωριστικά τύπου δωματίου και τύπου διατροφής προέρχονται από τη λίστα δωματίων.

Αίτημα

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

const booking = {
  hotelID: "1000",
  ID: orderNo,                      // ο δικός σας μοναδικός κωδικός κράτησης
  type: "Book",
  createDateTime: new Date().toISOString(),
  checkinDate: "2026-08-18",
  checkoutDate: "2026-08-20",
  RoomStays: [{
    roomTypeID: "2", roomName: "Standard Room",
    ratePlanID: "2", ratePlanName: "Bed & Breakfast",
    type: "Book", NumberOfUnits: "1",
    checkinDate: "2026-08-18", checkoutDate: "2026-08-20",
    GuestCount: { adult: 2, child: 1 },
    PerDayRates: { currency: "TRY", PerDayRate: [
      { stayDate: "2026-08-18", baseRate: "965.00", hotelServiceFees: "0" },
      { stayDate: "2026-08-19", baseRate: "965.00", hotelServiceFees: "0" }
    ]},
    Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", currency: "TRY" }
  }],
  PrimaryGuests: [{ name: "Ayşe", surname: "Demir", PhoneNumber: "+905551112233", email: "[email protected]", CountryCode: "TR" }],
  ChildGuests: [{ age: 7 }],
  SpecialRequest: [{ text: "Late check-in, around 23:00." }],
  extras: [],
  Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", extraTotal: "0.00", currency: "TRY" }
};

const res = await fetch("https://test.hms.gen.tr/external/online/channel/booking", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.HMS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ BookingPushRQ: { Bookings: [booking] } })
});
const { BookingPushRS } = await res.json();
if (BookingPushRS.Error) throw new Error(BookingPushRS.Error);
const hmsId = BookingPushRS.BookingConfirmNumbers[0].HMS_ID;

$booking = [
    'hotelID'        => '1000',
    'ID'             => $orderNo,          // ο δικός σας μοναδικός κωδικός κράτησης
    'type'           => 'Book',
    'createDateTime' => date('c'),
    'checkinDate'    => '2026-08-18',
    'checkoutDate'   => '2026-08-20',
    'RoomStays'      => [[
        'roomTypeID' => '2', 'roomName' => 'Standard Room',
        'ratePlanID' => '2', 'ratePlanName' => 'Bed & Breakfast',
        'type' => 'Book', 'NumberOfUnits' => '1',
        'checkinDate' => '2026-08-18', 'checkoutDate' => '2026-08-20',
        'GuestCount'  => ['adult' => 2, 'child' => 1],
        'PerDayRates' => ['currency' => 'TRY', 'PerDayRate' => [
            ['stayDate' => '2026-08-18', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
            ['stayDate' => '2026-08-19', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
        ]],
        'Total' => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'currency' => 'TRY'],
    ]],
    'PrimaryGuests'  => [['name' => 'Ayşe', 'surname' => 'Demir', 'PhoneNumber' => '+905551112233', 'email' => '[email protected]', 'CountryCode' => 'TR']],
    'ChildGuests'    => [['age' => 7]],
    'SpecialRequest' => [['text' => 'Late check-in, around 23:00.']],
    'extras'         => [],
    'Total'          => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'extraTotal' => '0.00', 'currency' => 'TRY'],
];

$ch = curl_init('https://test.hms.gen.tr/external/online/channel/booking');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('HMS_TOKEN'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['BookingPushRQ' => ['Bookings' => [$booking]]]),
]);
$rs = json_decode(curl_exec($ch), true)['BookingPushRS'];
if (isset($rs['Error'])) {
    throw new RuntimeException($rs['Error']);
}
$hmsId = $rs['BookingConfirmNumbers'][0]['HMS_ID'];

Απόκριση · 200

{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

Το HMS_ID είναι το αναγνωριστικό της κράτησης στο HMS· αποθηκεύστε το μαζί με τη δική σας εγγραφή. Η κράτηση εμφανίζεται στον πίνακα διαχείρισης στο κανάλι «Online» και το HMS στέλνει στον επισκέπτη email επιβεβαίωσης σύμφωνα με τις ρυθμίσεις του ξενοδοχείου.

Πολλά δωμάτια#

Όταν πωλούνται πολλά δωμάτια του ίδιου τύπου δωματίου και τύπου διατροφής, κάθε δωμάτιο είναι ξεχωριστό στοιχείο RoomStays· το NumberOfUnits είναι "1" για το πρώτο, "2" για το δεύτερο κ.ο.κ. Διαφορετικοί τύποι δωματίων είναι επίσης ξεχωριστά στοιχεία. Το Total της κράτησης είναι το άθροισμα όλων των δωματίων και των επιπλέον υπηρεσιών.

Τροποποιήσεις και ακυρώσεις#

Στείλτε ξανά την κράτηση στο ίδιο τελικό σημείο με το ίδιο ID:

type: "Modify" — άλλαξαν ημερομηνίες, δωμάτια ή στοιχεία επισκεπτών. Στείλτε ολόκληρη την κράτηση στην τρέχουσα μορφή της· το HMS αντικαθιστά με αυτήν την υπάρχουσα εγγραφή.
type: "Cancel" — η κράτηση ακυρώθηκε. Και τα δωμάτια φέρουν type: "Cancel".

Συνήθη λάθη#

Διατήρηση της λίστας δωματίων στην cache για πολύ. Η διαθεσιμότητα και οι τιμές αλλάζουν συνεχώς· ανανεώστε τη λίστα πριν ο επισκέπτης περάσει στο βήμα πληρωμής.
Αποστολή childCount που διαφέρει από το μήκος του childAges[]: ο διακομιστής εμπιστεύεται τη λίστα ηλικιών και αλλάζει σιωπηρά τον αριθμό παιδιών.
Αποστολή δικών σας αναγνωριστικών ως roomTypeID / ratePlanID αντί για τα αναγνωριστικά της λίστας δωματίων: επιστρέφεται Could not register..
Αποστολή PaymentCard για τύπους πληρωμής εκτός του 9: τα δεδομένα της κάρτας μεταδίδονται στο HMS χωρίς λόγο.
Επανάληψη μετά από σφάλμα δικτύου με διαφορετικό ID: δημιουργείται διπλή κράτηση. Επαναλάβετε με το ίδιο ID.

Τελευταία ενημέρωση: 21 Σεπτεμβρίου 2026Βρήκατε κάποιο λάθος; Ενημερώστε μας