API Reservation10

Формат запитів JSON

Форматом переданих і прийнятих даних є протокол обміну JSON. Кодування запитів і відповідей UTF8. Приклад запиту і відповіді наведено нижче. {

  "firstName": "Ім'я",
  "lastName": "Прізвище",
  "адреса": {
      "streetAddress": "Швидке ш., 101, кв.101",
      "city": "Місто",
      "postalCode": 101101
  },
  "phoneNumbers": [
      "+380(98)-765-43-21",
      "+380(98)-123-45-67"
  ]

}

Формат даних

• Формат дати/часу: "yyyy-MM-dd HH:mm:ss";
• Формат дати: "yyyy-MM-dd"
• Формат часу: "HH:mm"
• Роздільник типів із плаваючою крапкою(double): "."

Опис функцій спілкування

GetCompanyInfo

Функція GetCompanyInfo повертає інформацію про компанію, або помилку.

Вхідні параметри:

  1. CompanyCode - string, довжина рядка до 20 символів. Ідентифікаційний код компанії.

Значення, що повертається:

Повертається JSON структура з такими полями:

   1. Result - int, ціле число, що відповідає за результат виконання функції, 0 - OK, 1 - Function Еrror, 2 - Incorrect string.
   2. Error - string, текст помилки, що сталася, якщо функція виконана успішно, то передається порожній рядок.
   3. ErrorCode - string, код помилки. Якщо компанія за кодом не знайдена код помилки - CompanyNotFound
   4. CompanyID - int, ідентифікатор компанії.
   5. CompanyCodeID - int, ідентифікатор коду компанії.
   6. CompanyName - string, назва компанії
   7. CompanyEmail - string, ел. пошта компанії
   8. CompanyFax - рядок, факс компанії
   9. ComanyPhoneNumber - string, номер контактного телефону компанії
   10. IsPrepayment - bool, працює за передоплатою

Get Rooms

Функція GetRooms отримує за вхідними параметрами список категорій номерів із зазначенням кількості вільних номерів кожної категорії.

Вхідні параметри:

   1. HotelID - int, від 1 до +∞, ID готелю
   2. DateArrival - date, дата заїзду - ведеться ігнорування часу.
   3. DateDeparture - date. Дата виїзду - ведеться ігнорування часу.
   4. TimeArrival - string, 5 символів - час заїзду (н/р: "14:00"), якщо час заїзду не вказано, передавати порожній рядок, у такому разі час заїзду буде проставлятися в автоматичному режимі.
   5. Adults - int, від 1 до 1000. Кількість дорослих людей
   6. Childs - int, від 0 до 1000. Якщо кількість дітей немає на формі (визначається параметром), приходить порожній рядок.
   7. ChildAges - int[], масив цілих чисел, що означають вік кожної дитини. Якщо кількість дітей більша за розмірність наступного за ним масиву вікових груп, то повертається помилка.
   8. IsExtraBedUsed - bool, логічне значення. Можливість використання додаткових місць для видачі номерів.
   9. CompanyCodeID - int, ідентифікатор коду компанії, 0 - немає, >0 - визначає ID компанії під якою відбувається бронювання
   10. TimeDeparture - string, 5 символів - час виїзду (н/р: "12:00"), якщо час виїзду не вказано, передавати порожній рядок, у такому разі час виїзду буде проставлятися в автоматичному режимі.

Значення, що повертається:

Повертається JSON структура з такими полями:

   1. Result - int, ціле число, що відповідає за результат виконання функції, 0 - OK, , 1 - Function Еrror, 2 - Incorrect string.
   2. Error - string, текст помилки, що сталася, якщо функція виконана успішно, то передається порожній рядок.
   3. ErrorCode - string, код помилки.
   4. RoomTypes - RoomType[], одновимірний масив JSON структур RoomType, у якому зберігається інформація за категоріями кімнат:
       a. ID - int, ID категорії номера в базі PMS.
       b. FreeRoom - int, кількість вільних номерів цієї категорії.
       c. MainPlacesCount - int, кількість основних місць у номері.
       d. NearestDateToReservation - Nullable<datetime>, дата найближчої можливої броні
   5. СontractConditions - СontractCondition[], одновимірний масив JSON структур СontractCondition, у якому зберігається інформація щодо умов договорів компанії. Це поле заповнюється тільки якщо CompanyID > 0, кількість елементів у масиві відповідає кількості умов договорів, що діють на дату заїзду:
       a. СontractConditionID - int, ідентифікатор умови договору компанії.
       b. СontractConditionName - string, назва умови договору компанії.
       c. PaidTypes - int[], масив кодів типів оплат доступних за цією умовою. Значення елементів масиву: 100 - готівка, 200 - кредитна картка, 300 - безготівкова оплата.
       d. ExpiredDate - datetime, дата закінчення поточного договору компанії.

GetPrices

Функція GetPrices отримує за вхідними параметрами список заявок на бронювання із зазначенням списку послуг і цін на кожен день проживання за кожною заявкою. Далі на сайті цю інформацію обробляють і групують у зручному для користувача вигляді.

Вхідні параметри:

   1. HotelID - int, від 1 до +∞, ID готелю
   2. CompanyID - int, ідентифікатор компанії, 0 - немає, >0 - визначає ID компанії під якою відбувається бронювання
   3. DateArrival - date, дата заїзду - ведеться ігнорування часу.
   4. DateDeparture - date, дата виїзду - ведеться ігнорування часу.
   5. TimeArrival - string, 5 символів - час заїзду (н/р: "14:00"), якщо час заїзду не вказано, передавати порожній рядок, у такому разі час заїзду буде проставлятися в автоматичному режимі.
   6. Adults - int, від 1 до 1000. Кількість дорослих людей
   7. Childs - int, від 0 до 1000. Якщо кількість дітей немає на формі (визначається параметром), приходить порожній рядок.
   8. ChildAges - int[], масив цілих чисел, що означають вік кожної дитини. Якщо кількість дітей більша за розмірність наступного за ним масиву вікових груп, то повертається помилка.
   9. IsExtraBedUsed - bool, логічне значення. Можливість використання додаткових місць для видачі номерів.
   10. IsoLanguage - string, 2 символи, двобуквена iso назва мови для виведення запиту.
   11. RoomTypeIDs - int[], масив ідентифікаторів категорій номерів, для яких потрібно брати ціну.
   12. СontractConditionID - int, ідентифікатор умови договору, за якою необхідно отримати PriceLists.  0 - системна умова, >0  - ідентифікатор обраної умови.
   13. СontractConditionAddIDs - int[], масив ідентифікаторів умов договорів, за якими необхідно отримати PriceLists.
   14. PaidType - int, тип оплати 100 - готівка, 200 - кредитна картка, 300 - безготівкова оплата.
   15. NeedTransport - int, від 0 до 1, потрібно замовити транспорт 0 - не потрібно, 1 - потрібно
   16. IsTouristTax - int, параметр чи оподатковується цей гість, 1- оподатковується, 0 - не оподатковується. За замовчуванням 1.
   17. AgentCategory - int, категорія контрагента. 0 - не вказано (буде використано категорію, налаштовану для готелю за замовчуванням), 1 - Резидент, 2 - Нерезидент.
   18. AgentCategories - int[], масив категорій контрагентів (можливі значення елементів масиву як у полі AgentCategory). Якщо масив містить хоча б один елемент, то ціни за послугами-надбавками повертаються окремо від цін на основні послуги.
   19. TimeDeparture - string, 5 символів - час виїзду (н/р: "12:00"), якщо час виїзду не вказано, передавати порожній рядок, у такому разі час виїзду буде проставлятися в автоматичному режимі.
   20. LPAuthCode - string, 20 символів. Код бронювання програми лояльності.

Значення, що повертається:

Повертається JSON структура з такими полями:

   1. Result - int, ціле число, що відповідає за результат виконання функції, 0 - OK, 1 - Function Еrror, 2 - Incorrect string.
   2. Error - string, текст помилки, що сталася, якщо функція виконана успішно, то передається порожній рядок.
   3. ErrorCode - string, код помилки.
   4. ValuteShort - рядок, скорочення базової валюти в зазначеній мові.
   5. PriceLists - PriceList[], одновимірний масив JSON структур PriceList, у якому зберігається інформація про прейскуранти, що повертаються, а також про ціни для цих прейскурантів на запитувані категорії кімнат: 
       a. PriceListID - int, ID прейскуранта в базі HMS;
       b. PriceListName - string, найменування прейскуранта;
       c. ConditionID - int, ID умови договору;
       d. IsNonReturnRate - int, ознака неповоротного тарифу, 1 - неповоротний тариф, 0 - поворотний тариф. 
       e. IsSpecRate- int, ознака спеціальної пропозиції, 1 - спеціальна пропозиція, 0 - звичайний тариф. 
       f. RoomTypes - RoomType[], одновимірний масив JSON структур RoomType, у якому зберігається інформація щодо цін для категорій кімнат:
           i. ID - int, ID категорії номера в базі HMS.
           ii. Services - Service[], одновимірний масив JSON структур Service, в якому зберігається інформація за цінами послуг. Кількість елементів у цьому масиві визначає кількість різних послуг:
               1. ServiceID - int, ідентифікатор послуги
               2. ServiceName - string, назва послуги
               3. ServiceCode - int, податковий код групи
               4. ServiceSystemCode - string, системний код
               5. ServiceTypeName - string, назва типу улуги
               6. PriceDates - PriceDate[], одновимірний масив JSON структур PriceDate, в якому зберігається інформація за цінами послуги для категорії кімнати для зазначеного часового проміжку. Кількість елементів у цьому масиві визначає кількість дат, що відображаються користувачеві на сайті:
                   a. Date - datetime, дата і час споживання послуги
                   b. Price - double, сума нарахування в поточний день
                   c. RackRatePrice - double, сума нарахування в поточний день за прейскурантом стійки
           iii. AgentCategories - AgentCategory[], одновимірний масив JSON структур Service, в якому зберігається інформація за цінами послуг-надбавок для різних категорій контрагентів. Заповнюється залежно від вхідного параметра. AgentCategories: якщо масив містить хоча б один елемент, то ціни на послуги-надбавки повертаються окремо від цін на основні послуги в даному полі; якщо масив не заповнено, то ціни на послуги-надбавки повертаються до RoomType.Services разом із рештою послуг.
               1. AgentCategory - int, категорія контрагента.
               2. Services - Service[], одновимірний масив JSON структур Service, в якому зберігається інформація за цінами послуг-надбавок для категорії контрагента.
                          iv. SaleRestrictions - JSON-структура, в якій міститься інформація щодо обмежень продажів для категорії кімнати на вказаний часовий проміжок:
               1. ClosedToSale - JSON-структура містить інформацію про обмеження "Заборона продажів":
                   a.  HasRestrictions - bool, ознака наявності обмеження
                   b. Message - string, текст повідомлення
               2. ClosedToArrive - JSON структура містить інформацію про обмеження "Заборона заїзду":
                   a.  HasRestrictions - bool, ознака наявності обмеження
                   b. Message - string, текст повідомлення
               3. EarlyReservation - JSON структура містить інформацію про обмеження "Раннє бронювання":
                   a.  HasRestrictions - bool, ознака наявності обмеження
                   b. Message - string, текст повідомлення
               4. MinStay - JSON структура містить інформацію про обмеження "Мінімальний період проживання":
                   a.  HasRestrictions - bool, ознака наявності обмеження
                   b. Days - int, кількість днів. 0 - якщо відсутні чинні обмеження на мінімальний період проживання.
                   c. Message - string, текст повідомлення
               5. MinPay - JSON структура містить інформацію про обмеження "Мінімальна передоплата":
                   a. Days - int, кількість днів.
                   b. Message - string, текст повідомлення
                   c. MinPayPaymentRules - MinPayPaymentRuleInfo[], одновимірний масив JSON структур MinPayPaymentRuleInfo, у якому зберігається інформація про обов'язковість оплат:
   i. TimeFromArriveDate - long, Час до заїзду (сек.), діє в більший бік, тобто в разі різниці між датою заїзду та датою бронювання, більшої за це значення, оплата буде обов'язковою, якщо меншою - ні.
   ii. TimeForPayment - long, час для оплати з дати бронювання (сек.)

AddRoomReservation

Функція AddRoomReservation створює нову бронь у базі за вхідними параметрами і повертає ID броні. Примітка: У разі вибору типу оплати-300 (безготівкова оплата) в HMS створюється автоматично рахунок на компанію.

Вхідні параметри:

   1. HotelID - int, від 1 до +∞, ID готелю
   2. DateArrival - date, дата заїзду - ведеться ігнорування часу.
   3. DateDeparture - date .Дата виїзду - ведеться ігнорування часу.
   4. TimeArrival - string, 5 символів - час заїзду (н/р: "14:00"), якщо час заїзду не вказано, передавати порожній рядок, у такому разі час заїзду буде проставлятися в автоматичному режимі.
   5. Adults - int, від 1 до 1000. Кількість дорослих людей
   6. Childs - int, від 0 до 1000. Якщо кількість дітей немає на формі (визначається параметром), приходить порожній рядок.
   7. ChildAges - int[], масив цілих чисел, що означають вік кожної дитини. Якщо кількість дітей більша за розмірність наступного за ним масиву вікових груп, то повертається помилка.
   8. IsExtraBedUsed - bool, логічне значення. Можливість використання додаткових місць для видачі номерів.
   9. GuestLastName - string, прізвище гостя
   10. GuestFirstName - string, ім'я гостя
   11. RoomTypeID - int, 1 до +∞, ID категорії номера
   12. CompanyID - int, ідентифікатор компанії, 0 - немає, >0 - визначає ID компанії під якою відбувається бронювання
   13. Company - рядок, назва компанії
   14. СontractConditionID - int, ідентифікатор умови договору компанії. 0 - системна умова, >0 - ідентифікатор обраної умови.
   15. PaidType - int, тип оплати 100 - готівка, 200 - кредитна картка, 300 - безготівкова оплата.
   16. Iso3Country - string, рядок 3 символи, iso позначення країни.
   17. Country - string, назва країни
   18. Address - рядок, адреса проживання
   19. Phone - рядок, телефон
   20. Fax - рядок, факс
   21. eMail - рядок, пошта
   22. NeedTransport - int, від 0 до 1, потрібно замовити транспорт 0 - не потрібно, 1 - потрібно
   23. Comment - string, рядок коментарів. Обріжеться під час вставки в базу.
   24. ClientInfo - string, додаткова інформація про людину, яка зробила бронь: IP-адреса, тощо.
   25. IsTouristTax - int, ознака включення тур.збору в автоматично створений рахунок, 1- включається, 0 - не включається
   26. AgentCategory - int, категорія контрагента. 0 - не вказано (буде використано категорію, налаштовану для готелю за замовчуванням), 1 - Резидент, 2 - Нерезидент.
   27. PriceListID - int, 1 до +∞, ID прейскуранта
   28. LoyaltyCardTypeID - int, ідентифікатор типу карти лояльності.
   29. LoyaltyCardNumber - string, 20 символів. Код бронювання програми лояльності.
   30. ContactName - string, до 50 символів. Контактна особа під час бронювання.
   31. TimeDeparture - string, 5 символів - час виїзду (н/р: "12:00"), якщо час виїзду не вказано, передавати порожній рядок, у такому разі час виїзду буде проставлятися в автоматичному режимі.
   32. BirthDate - date, дата народження.
   33. UTM_CAMPAIGN - string, 128 символів - UTM-мітка. Назва рекламної кампанії
   34. UTM_CONTENT - string, 128 символів - UTM-мітка. Інформація, яка допомагає розрізняти оголошення, якщо збігаються інші параметри
   35. UTM_MEDIUM - string, 128 символів - UTM-мітка. Тип трафіку
   36. UTM_SOURCE - string, 128 символів - UTM-мітка. Рекламна система
   37. UTM_TERM - string, 128 символів - UTM-мітка. Ключове слово, яке ініціювало показ оголошення

Значення, що повертається:

Повертається JSON структура з такими полями:

   1. Result - int, ціле число, що відповідає за результат виконання функції, 0 - OK, 1 - Function Еrror, 2 - Incorrect string.
   2. Error - string, текст помилки, що сталася, якщо функція виконана успішно, то передається порожній рядок.
   3. ErrorCode - string, код помилки.
   4. Account - int, від 1 до +∞, ID броні