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 – ознака активності.
По вхідним даним система шукає учасників, їх інформацію та налаштування програми лояльності в базі даних. Після цього повертається результат функції з заповненими відповідними полями.
Discount_Transaction_eWallet_Request
Метод виконує запит інформації щодо можливості надання знижки за ID магнітної картки та список транзакцій. Метод підходить для POS та HMS.
Вхідні параметри:
- int MagneticCardID – ID магнітної картки програми лояльності.
- string[32] POSCode – унікальний код POS системи, по якому шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
- Transaction[] Transactions – масив транзакцій структур Transaction. Структура Transaction має наступні поля:
- decimal Sum – сума транзакції.
- DateTime TransactionDate – дата проведення транзакції в POS системі.
- int ServiceGroupCode – код групи послуг POS системи.
- string[30] POSsystemAccount – Л/С в POS системі. (Не впливає на виконання запиту)
- string[30] PointOfSalePOScode – код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не видалених точок. (Не впливає на виконання запиту)
- int BillitemID – ідентифікатор позиції рахунку.
Результат функції:
- string Error – опис виниклої помилки.
- int eWalletID – ID учасника програми лояльності, якому належить картка з запиту.
- int MagneticCardID – ID учасника програми лояльності, якому належить картка з запиту.
- string UserName – ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка з запиту.
- DiscountTransaction[] DiscountTransactions – масив транзакцій для отримання знижки структур DiscountTransaction. Структура DiscountTransaction має наступні поля:
- DateTime TransactionDate – дата проведення транзакції.
- decimal Sum – сума транзакції.
- int ServiceGroupCode – код групи послуг POS системи.
- string[30] POSsystemAccount – Л/С в POS системі.
- decimal Discount – величина знижки в валюті.
- decimal DiscountSum – сума транзакції з урахуванням знижки.
- string[20] DiscountPriceListCode – код прайсу для поточного дисконтного статусу, необов'язково для заповнення, використовується при акцептуванні транзакцій зі знижкою по прайсу.
- string[30] PointOfSalePOScode – код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не видалених точок. (Порожнє поле)
- string ErrorTransaction – опис виниклої помилки для конкретної транзакції (Порожнє поле)
- int BillitemID – ідентифікатор позиції рахунку.
Спочатку відбувається перевірка на дисконтний тип програми, якщо його немає – повертаємо помилку. Далі по MagneticCardID система шукає картку в базі даних, якщо такої немає або вона неактивна, повертається помилка. Якщо картка є і вона активна, система розраховує знижки для транзакцій. Після цього повертається результат функції, заповнюючи відповідні поля.