API Протокол взаємодії Servio Loyalty Program з зовнішніми POS системами.

Список Змін

ДАТА ВНЕСЕННЯ	ЗМІНЕНА ЧАСТИНА (Розділ, сторінка)	НОМЕР НОВОЇ РЕДАКЦІЇ	ЗМІНИ Тип (доповнення, видалення) та конкретний опис
07.09.2023		1.00	Документ створено
22.09.2023		1.01	Додано функції транзакцій з сертифікатами: PayCertificatesRequest, PayCertificatesAccept
25.09.2023		1.02	Додано (і убрано з транзакцій запиту, де було) необов'язковий ввід часу транзакції (якщо не вказано - буде час готелю з запиту або інсталяції) в операції підтвердження додавання транзакцій (п. 2.3, 2.5, 2.7, 2.9, 2.11, 2.13)
29.09.2023		1.03	Сумісність з API зовнішньої лояльності
23.10.2023		1.04	Змінено принцип роботи і описання транзакцій повернень (п. 2.15 – 2.24)
03.01.2024		1.05	Додано і/або змінено методи Get_eWallet_Info, Add_eWallet_Bonuses, Pay_Transaction_eWallet_Bonuses_Request, Pay_Transaction_eWallet_Bonuses_Accept, Discount_Transaction_eWallet_Request, Discount_Transaction_eWallet_Accept, Pay_Transaction_eWallet_PayCard_Accept для інтеграції з POS. Змінено метод PayMoneyAccept (дублює Pay_Transaction_eWallet_PayCard_Accept). Методи Discount_Transaction_eWallet_Accept, Add_eWallet_Bonuses, Pay_Transaction_eWallet_Bonuses_Accept, Add_eWallet_Bonuses_Accept, Return_Discount_Transaction_eWallet_Accept, Return_Pay_Transaction_eWallet_Bonuses_Accept, Return_Add_eWallet_Bonuses_Accept тепер зберігають деталізацію (змінена деталізація у вхідних даних).
01.02.2024		1.06	Додано інтеграцію з HMS. Удалено методи Add_eWallet_Bonuses_Accept, PayMoneyRequest, PayMoneyAccept. Додано методи Pay_Transaction_eWallet_PayCard_Request, Departure_Transaction_Accept. Переіменовані методи MoneyInputRequest, MoneyInputAccept, CertificateTransactionsRequest, CertificateTransactionsAccept, ReturnMoneyInputRequest, ReturnMoneyInputAccept, ReturnPayMoneyRequest, ReturnPayMoneyAccept.
15.02.2024		1.07	Додано поле RoomNightBalance в кошелек з методу Get_eWallet_Info. Додано методи для роботи з безкоштовними номерами Add_RoomNights_Accept, WriteOff_RoomNights_Accept, Return_WriteOff_RoomNights_Accept
19.02.2024		1.08	Додано метод Money_Input, видалено метод Money_Input_Accept
26.03.2024		1.09	Додано методи Chat_GetAccountInfo, Chat_GetLastBonusTransactionsInfo, Chat_PersonalDataCorrection
09.07.2024		1.10	Змінена структура запиту і відповіді методу WriteOff_RoomNights_Accept. Додано метод Get_eWallet_Secure_Info. Додано метод Get_File.
12.07.2024		1.11	Верифіковано документ. Внесено правки.
18.09.2024		1.12	Додано метод Change_LoyaltyAccount_Password.
15.11.2024		1.13	В метод Get_eWallet_Info додано номер телефону в тіло запиту
19.11.2024		1.14	Додано метод GetLastBonusTransactionsInfo

Опис взаємодії

Взаємодія системи HMS Servio і Servio Restaurant з процесинговим центром буде здійснюватися через звернення до WCF служби процесингу за допомогою протоколу JSON, кодування передачі даних UTF8, методом POST. Для цього протоколу всі типи та значення повинні передаватися в текстовому представленні. Тому необхідно використовувати такі формати для текстового представлення даних:

• datetime – строкове представлення дати в форматі «yyyy-MM-dd HH:mm:ss»
• decimal – 18.2 – використовується округлення до 2-х знаків після коми, як розділювач цілої та дробної частини виступає «.» (крапка)
• int – стандартне десятинне строкове представлення цілого числа
• string[N] – обмежена по розміру строка, розмір рядка плаваючий від 0 до N символів.
• string – необмежена по розміру строка, розмір рядка плаваючий від 0 до 8000 символів.
• bool – строкове представлення логічного типу, де «1» – істина (true), «0» – хибність (false)

Приклад запиту та відповіді в форматі JSON:

Запит:

• POST http://localhost:8000/ServioLoyaltyService/PayBonusesRequest
• Content-Type: application/json; charset=utf-8
• Host: localhost:8000
• Content-Length: 241
• Connection: Keep-Alive

{
   "MagneticCardID":"5",
   "Transactions":[
      {
         "Sum":"300.3",
         "ServiceGroupID":"3"
      }
   ]
}

Результат:

• HTTP/1.1 200 OK
• Content-Length: 186
• Content-Type: application/json; charset=utf-8
• Server: Microsoft-HTTPAPI/2.0
• Date: Wed, 06 Sep 2023 11:58:56 GMT

{
   "Error":null,
   "MagneticCardID":5,
   "BonusBalance":0.00,
   "UserName":"666 666",
   "Transactions":[
      {
         "BonusesToPay":0.00,
         "ServiceGroupID":3,
         "Sum":300.3,
         "TransactionDate":"2023-09-06 14:58:56"
      }
   ]
}

Функції протоколу

Протокол обміну представлений у вигляді окремих відкритих функцій, до яких може звертатися будь-який клієнт POS системи.

Get_eWallet_Info

Метод по номеру магнітної карти та/або ідентифікатору компанії та/або коду бронювання та/або короткому номеру картки з програмою лояльності повертає інформацію по карті, учаснику, якому вона належить, транзакціям і налаштуванням програми лояльності. Метод підходить для POS та HMS.

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

• string[32] POSCode – унікальний код POS системи, по якому шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
• int? CompanyAccount – ідентифікатор компанії HMS Servio.
• string[20] AuthCode – код бронювання. (Не впливає на виконання запиту)
• string[20] SynkLoyaltyCode – код синхронізації програми лояльності. (Не впливає на виконання запиту)
• string[50] CardNumber – повний номер картки, по повному співпаданню якого шукається магнітна картка, що належить учаснику програми лояльності.
• string[30] ShortCardNumber – короткий номер картки, по повному співпаданню якого (при наявності) шукається магнітна картка, що належить учаснику програми лояльності.
• string[30] PhoneNumber – номер телефону, перевіряє співпадіння по останнім 9 цифрам з контактом або компанією програми лояльності.
• int? PersonID – ІД персони.

Результат функції:

• string Error – опис виниклої помилки.
• eWallet[] eWallets – масив описів електронних гаманців eWallet. Елементи масиву містять такі поля:

 * int eWalletID – ID електронного гаманця.
 * string[100] LoyaltyProgramName – назва програми лояльності.
 * string[50] BonusStatusName – назва статусу програми лояльності.
 * decimal BonusBalance – поточний бонусний баланс електронного гаманця.
 * decimal AccumulatedBonuses – поточна кількість накоплених бонусів електронного гаманця.
 * string[50] DiscountStatusName – назва статусу програми лояльності.
 * string[20] DiscountPriceListCode – код прайсу для поточного дисконтного статусу.
 * decimal DiscountTransactionsSum – сума всіх неанульованих транзакцій з урахуванням знижки, проведених для цього гаманця.
 * string[20] ServioSynkCode – код синхронізації програми лояльності.
 * int? CompanyAccount – ідентифікатор компанії HMS Servio.
 * string[30] MagneticCardShortNumber – короткий номер магнітної картки.
 * string[30] MagneticCardFullNumber – довгий номер магнітної картки.
 * decimal BonusSum – сума бонусів.
 * decimal PaySum – сума на платіжній картці.
 * decimal Credit – сума кредиту.
 * decimal Accumulation – сума оборотів по картці.
 * bool IsPayCard – флаг, що визначає налаштування лояльності «Робота з грошовими коштами».
 * decimal ExtraMoneySum – сума екстра-денег.
 * bool IsSmartCard – ознака смарт-картки.
 * string ShortCode – короткий номер магнітної картки.
 * decimal DayLimit – ліміт списання за день.
 * decimal WeekLimit – ліміт списання за тиждень.
 * decimal MonthLimit – ліміт списання за місяць.
 * decimal YearLimit – ліміт списання за рік.
 * bool UsePayLimits – ознака використання лімітів списання.
 * bool UseCatLimits – ознака використання лімітів категорій.
 * datetime ValidityStart – дата початку дії картки/сертифіката.
 * datetime Validity – дата закінчення дії картки/сертифіката.
 * bool Issue – ознака Issued.
 * int Cardid – ІД картки.
 * string Comment – коментар.
 * string Description – примітка.
 * decimal Discount – розмір знижки по картці.
 * string SynkLoyaltyCode – код лояльності з налаштувань програми лояльності.
 * int RoomNightBalance – кількість безкоштовних ночей учасника.
 * int MagneticCardID – ідентифікатор картки.
 * string UserName – ім'я власника.
 * string MobilePhone – номер телефону.
 * int DiscountGroupID – ідентифікатор дисконтної групи.
 * bool IsBonusProgram – приналежність до бонусної системи.
 * bool IsDiscountProgram – приналежність до дисконтної системи.
 * bool IsActive – ознака активності.

По вхідним даним система шукає учасників, їх інформацію та налаштування програми лояльності в базі даних. Після цього повертається результат функції з заповненими відповідними полями.