Автентифікація

Доступ надається через партнерський обліковий запис, який створює 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. Якщо партнер не має доступу до готелю, повертається hotel_permission_is_not_found.
hotelSeoUrlSEO-адреса готелю. Замість 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 означає, що змінилася пара ключів або доступ до готелю.

Контекст готелю#

Токен прив’язаний до одного готелю. Параметр hotelID в ендпоінтах має збігатися з цим готелем; запит до іншого готелю призведе до помилки доступу або порожніх результатів. Для інтеграцій із кількома готелями отримуйте окремий токен для кожного готелю й кешуйте його окремо.

Помилки входу#

messageЗначення
partner_is_not_foundПара apiKey / apiSecret не збіглася. Перевірте ключі та їхнє кодування для URL.
hotel_is_not_foundНе знайдено готелю з таким hotelSeoUrl.
hotel_permission_is_not_foundПартнер не має доступу до цього готелю або доступ неактивний. Зверніться до підтримки HMS.

Ці помилки повертаються з HTTP 200, success: false і token: null.

Останнє оновлення: 21 вересня 2026 р.Знайшли помилку? Повідомте нам