予約フロー

予約エンジンの典型的なフローは次のとおりです。トークンを取得し、ゲストが検索した日付と人数で客室を一覧表示し、選択された料金とクーポンを適用し、決済ステップを完了してから、BookingPushRQ で予約を HMS に書き込みます。このガイドでは、実際のリクエストとレスポンスを使って各ステップを説明します。

1ログイン/external/public/login

2客室一覧/external/online/roomType

3クーポン · パッケージcoupon/search · stock/packages

4決済payment/type/{type}

5送信channel/booking

1. トークンを取得する#

サーバーの起動時、またはトークンの期限切れ時に一度ログインし、トークンをホテル ID と一緒に保存します。詳しくは認証を参照してください。

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`	食事条件の選択肢（朝食付き、2食付き…）
`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（オンライン決済）では決済セッションを開始し、ゲストをプロバイダーに引き継ぎます。決済後、ゲストは指定した returnUrl に戻ります。すべての支払い方法は決済フローガイドで説明しています。

5. 予約を送信する#

決済の結果が確定したら、予約を HMS に書き込みます。ID は自社で生成する一意のコードで、同じコードをゲストにも伝えてください。客室タイプと食事条件の 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 における予約 ID です。自社のレコードと一緒に保存してください。予約は管理パネルの「Online」チャネルに表示され、HMS はホテルの設定に従ってゲストに確認メールを送信します。

複数客室の予約#

同じ客室タイプ・食事条件の客室を複数販売した場合は、客室ごとに個別の RoomStays 要素とし、NumberOfUnits を1室目は "1"、2室目は "2" のように設定します。客室タイプが異なる場合も、それぞれ個別の要素にします。予約の Total は、全客室とオプションの合計です。

変更とキャンセル#

同じ ID で、同じエンドポイントに予約を再送信します。

type: "Modify" — 日付、客室、ゲスト情報が変更された場合。現在の状態の予約全体を送信してください。HMS は既存のレコードをその内容で置き換えます。
type: "Cancel" — 予約がキャンセルされた場合。客室にも type: "Cancel" を指定します。

よくある間違い#

客室一覧を長時間キャッシュする。空室状況と料金は常に変動するため、ゲストが決済ステップに進む前に一覧を更新してください。
childAges[] の長さと異なる childCount を送信する。サーバーは年齢リストを優先し、子どもの人数を暗黙的に変更します。
客室一覧の ID ではなく、自社の ID を roomTypeID / ratePlanID として送信する。Could not register. が返ります。
支払い方法 9 以外で PaymentCard を送信する。カード情報が不必要に HMS へ送信されます。
ネットワークエラー後に別の ID でリトライする。予約が重複して作成されます。同じ ID でリトライしてください。

最終更新: 2026年9月21日誤りを見つけましたか？お知らせください