認証

アクセスは HMS が作成するパートナーアカウントを通じて許可されます。パートナーアカウントには apiKey と apiSecret が発行され、アクセスできるホテルは HMS が許可します。ログインエンドポイントは、これらの認証情報をホテルに紐づくトークンと交換します。

ログインとトークン#

リクエスト
POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000
レスポンス · 200
{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}
フィールド説明
apiKeyパートナーキー。base64 の文字を含むため、フォームボディでは URL エンコードが必要です（+ → %2B、= → %3D）。通常は HTTP ライブラリーが自動で処理します。
apiSecretシークレットキー。必ずサーバー側でのみ保管し、ブラウザーやモバイルアプリには絶対に含めないでください。
hotelCodeホテルの HMS ID。パートナーにこのホテルへのアクセス権がない場合は hotel_permission_is_not_found が返ります。
hotelSeoUrlホテルの SEO スラッグ。hotelCode の代わりにこれを使うのは HMS 自身の予約エンジンのみです。サードパーティの連携では hotelCode を送信します。

Bearer ヘッダー#

ログイン以外のすべてのエンドポイントは、Authorization ヘッダーでトークンを受け取ります。

リクエスト
GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

ヘッダーがない場合、形式が正しくない場合（Bearer プレフィックスがない）、またはトークンが不明な場合、API は 401 を返します。

401 Unauthorized
{
    "success": false,
    "error": "Authentication required"
}

トークンの有効期間と更新#

  • トークンの有効期間は7日間です。期限が切れる前に再ログインして更新してください。ログインは軽い処理で、同じホテルに対して何度でも実行できます。
  • トークンを解析しないでください。base64 でエンコードされた構造ですが、形式は保証されていません。不透明な文字列として保存し、そのまま送信してください。
  • 401 が返った場合は、一度だけ再ログインしてリクエストをリトライします。再び 401 が返る場合は、キーペアまたはホテルのアクセス権が変更されています。

ホテルコンテキスト#

トークンは1つのホテルに紐づきます。各エンドポイントの hotelID パラメーターはそのホテルと一致している必要があり、別のホテルを指定すると権限エラーまたは空の結果が返ります。複数ホテルを扱う連携では、ホテルごとに個別のトークンを取得し、ホテル単位でキャッシュしてください。

ログインエラー#

message意味
partner_is_not_foundapiKey / apiSecret のペアが一致しません。キーと URL エンコードを確認してください。
hotel_is_not_foundhotelSeoUrl に該当するホテルがありません。
hotel_permission_is_not_foundパートナーにこのホテルへのアクセス権がないか、権限が無効になっています。HMS サポートにお問い合わせください。

これらのエラーは HTTP 200 で、success: false と token: null とともに返ります。

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