ПрограмаЛояльності

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

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

   1. datetime - строкове подання дати у форматі "yyyy-MM-dd HH:mm:ss"
   2. decimal - 18.2 - використовується округлення до 2х знаків після коми, як роздільник цілої та дробової частини виступає "." (крапка)
   3. int - стандартне десяткове строкове подання цілого числа
   4. string[N] - обмежений за розміром рядок, розмір рядка плаваючий від 0 до N символів.
   5. string - необмежений за розміром рядок, розмір рядка плаваючий від 0 до 8000 символів.
   6. 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 Сервер: Microsoft-HTTPAPI/2.0 Дата: 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 електронного гаманця o string[100] LoyaltyProgramName - назва програми лояльності 

(string.Empty) o string[50] BonusStatusName - назва статусу програми лояльності o decimal BonusBalance - поточний бонусний баланс електронного гаманця o decimal AccumulatedBonuses - поточна кількість накопичених бонусів електронного гаманця

       ◦ string[50] DiscountStatusName - назва статусу програми лояльності o string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, потрібен для синхронізації знижки за прейскурантом, якщо гаманець відноситься до дисконтної програми і для нього заведений код прейскуранта. (string.Empty)
       ◦ decimal DiscountTransactionsSum - сума всіх неанульованих транзакцій з урахуванням знижки, проведених для цього гаманця
       ◦ string[20] ServioSynkCode - код синхронізації програми лояльності o int? CompanyAccount - ідентифікатор компанії HMS Servio.
       ◦ string[30] MagneticCardShortNumber - короткий номер магнітної картки o string[30] MagneticCardFullNumber - довгий номер магнітної картки o decimal BonusSum - сума бонусів o decimal PaySum - сума на платіжній картці o decimal Credit - сума кредиту o decimal Accumulation - сума оборотів за карткою
       ◦ bool IsPayCard - прапор, що визначає налаштування лояльності "Робота з грошовими коштами"
       ◦ decimal ExtraMoneySum - сума екстра-грошей o bool IsSmartCard - ознака смарт карти (false) 
       ◦ string ShortCode - короткий номер магнітної картки o decimal DayLimit - ліміт списання за день 
       ◦ decimal WeekLimit - ліміт списання за тиждень o decimal MonthLimit - ліміт списання за місяць 
       ◦ decimal YearLimit - ліміт списання за рік o bool UsePayLimits - ознака використання лімітів списання (false) 
       ◦  bool UseCatLimits - ознака використання лімітів категорій (false) 
       ◦ datetime ValidityStart - дата початку дії картки/сертифіката o datetime Validity - дата закінчення дії картки/сертифіката o bool Issue - ознака Issued (false) 
       ◦ int Cardid - ІД картки 
       ◦ string Comment - коментар (string.Empty) 
       ◦ string Description - Примітка (string.Empty) 
       ◦ decimal Discount - розмір знижки за карткою (0) 
       ◦ string SynkLoyaltyCode - код лояльності з налаштувань програми лояльності 
       ◦ int RoomNightBalance - кількість безкоштовних номероночей учасника o 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 - сума транзакції. o DateTime TransactionDate - дата проведення транзакції в POS-системі. o 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 - сума транзакції. o int ServiceGroupCode - код групи послуг POS-системи. 
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. 
       ◦ decimal Discount - величина знижки у валюті. 
       ◦ decimal DiscountSum - сума транзакції з урахуванням знижки.
       ◦ string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, не обов'язковий для заповнення, використовується при акцептуванні транзакцій зі знижкою за прейскурантом.
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Порожнє поле)
       ◦ string ErrorTransaction - опис помилки, що виникла для конкретної транзакції (Порожнє поле)
       ◦ int BillitemID - ідентифікатор позиції рахунку

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

Discount_Transaction_eWallet_Accept

Метод виконує підтвердження надання знижки за ID магнітної картки та списком транзакцій. Метод підходить для POS і HMS.

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

   • int MagneticCardID - ID магнітної картки програми лояльності.
   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int? BillID - ідентифікатор рахунку
   • int BaseExternalID - ідентифікатор зовнішньої системи
   • DiscountTransaction[] DiscountTransactions - масив транзакцій для отримання знижки структур DiscountTransaction. Структура DiscountTransaction має такі поля: o decimal Sum - сума транзакції.
       ◦ decimal DiscountSum - сума транзакції зі знижкою. (Не впливає на виконання запиту)
       ◦ DateTime TransactionDate - дата проведення транзакції.
       ◦ int ServiceGroupCode - код групи послуг POS системи. (Не впливає на виконання запиту)
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. (Не впливає на виконання запиту)
       ◦ decimal Discount - величина знижки у валюті. (Не впливає на виконання запиту)
       ◦ string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, не обов'язковий для заповнення, використовується при акцептуванні транзакцій зі знижкою за прейскурантом. (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ десяткова? Quantity - кількість o string ErrorTransaction - опис виниклої помилки для конкретної транзакції. (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

   • int ItemID - ID нарахування
   • int ServiceCode - Код послуги
   • string Name - Назва послуги
   • string ClassName - Назва класу послуги
   • string ClassCode - Код класу послуги
   • string SubClassName - Назва підкласу послуги
   • string SubClassCode - Код підкласу послуги
   • decimal Price - Ціна позиції
   • decimal Quantity - Кількість - Кількість
   • decimal Total - Підсумкова вартість 

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

   • string Error - опис помилки, що виникла.
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal PayBonuses - загальна сума знижки за транзакціями із запиту

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

Return_Discount_Transaction_eWallet_Request

Метод виконує запит інформації щодо можливості повернення транзакцій зі знижкою за ID магнітної картки та списком транзакцій. Метод підходить для 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 системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ decimal DiscountSum - сума транзакції зі знижкою. (Не впливає на виконання запиту)
       ◦ decimal Discount - величина знижки у валюті. (Не впливає на виконання запиту)
       ◦ string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, не обов'язковий для заповнення, використовується при акцептуванні транзакцій зі знижкою за прейскурантом. (Не впливає на виконання запиту) o десяткова? Quantity - кількість

string ErrorTransaction - опис виниклої помилки для конкретної транзакції. (Не впливає на виконання запиту)

       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

   • int ItemID - ID нарахування
   • int ServiceCode - Код послуги
   • string Name - Назва послуги
   • string ClassName - Назва класу послуги
   • string ClassCode - Код класу послуги
   • string SubClassName - Назва підкласу послуги
   • string SubClassCode - Код підкласу послуги
   • decimal Price - Ціна позиції
   • decimal Quantity - Кількість - Кількість
   • decimal Total - Підсумкова вартість

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

   • string Error - опис помилки, що виникла.
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту.
   • int MagneticCardID - ID учасника програми лояльності, якому належить картка із запиту.
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту.
   • bool IsOTPNeed - ознака необхідності підтвердження операції паролем/пін-кодом (Завжди false)
   • DiscountTransaction[] DiscountTransactions - масив транзакцій для отримання знижки структур DiscountTransaction. Структура DiscountTransaction має такі поля:
   • DateTime TransactionDate - дата проведення транзакції.
   • decimal Sum - сума транзакції. o int ServiceGroupCode - код групи послуг POS-системи. o string[30] POSsystemAccount - Л/Рахунок у POS системі. o decimal Discount - величина знижки у валюті. o decimal DiscountSum - сума транзакції з урахуванням знижки.
   • string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, не обов'язковий для заповнення, використовується при акцептуванні транзакцій зі знижкою за прейскурантом.

string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Порожнє поле)

   • string ErrorTransaction - опис помилки, що виникла для конкретної транзакції (Порожнє поле)
   • TransactionDetails Details - деталізація позицій рахунку. Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

       ◦ int ItemID - ID нарахування
       ◦ int ServiceCode - Код послуги
       ◦ string Name - Назва послуги
       ◦ string ClassName - Назва класу послуги
       ◦ string ClassCode - Код класу послуги
       ◦ string SubClassName - Назва підкласу послуги
       ◦ string SubClassCode - Код підкласу послуги
       ◦ decimal Price - Ціна позиції
       ◦ decimal Quantity - Кількість - Кількість
       ◦ decimal Total - Підсумкова вартість

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

Return_Discount_Transaction_eWallet_Accept

Метод виконує підтвердження повернення зі знижкою за ID магнітної картки та списком транзакцій. Метод підходить для HMS.

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

   • int MagneticCardID - ID магнітної картки програми лояльності.
   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • string CodeOTP - пароль/пін-код підтвердження операції. (Не впливає на виконання запиту)
   • DiscountTransaction[] DiscountTransactions - масив транзакцій для отримання знижки структур DiscountTransaction. Структура DiscountTransaction має такі поля:

decimal Sum - сума транзакції.

       ◦ decimal DiscountSum - сума транзакції зі знижкою. (Не впливає на виконання запиту)
       ◦ DateTime TransactionDate - дата проведення транзакції. o int ServiceGroupCode - код групи послуг POS-системи.
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. (Не впливає на виконання запиту)
       ◦ decimal Discount - величина знижки у валюті. (Не впливає на виконання запиту)
       ◦ string[20] DiscountPriceListCode - код прейскуранта поточного дисконтного статусу, не обов'язковий для заповнення, використовується при акцептуванні транзакцій зі знижкою за прейскурантом. (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ string ErrorTransaction - опис виниклої помилки для конкретної транзакції. (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку. Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

   • int ItemID - ID нарахування
   • int ServiceCode - Код послуги
   • string Name - Назва послуги
   • string ClassName - Назва класу послуги
   • string ClassCode - Код класу послуги
   • string SubClassName - Назва підкласу послуги
   • string SubClassCode - Код підкласу послуги
   • decimal Price - Ціна позиції
   • decimal Quantity - Кількість - Кількість
   • decimal Total - Підсумкова вартість 

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

   • string Error - опис помилки, що виникла.
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal Discount - загальна сума знижки за транзакціями із запиту

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

Add_eWallet_Bonuses_Request

Метод виконує запит інформації щодо можливості нарахування бонусів за ID магнітної картки та списком транзакцій. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int MagneticCardID - ID магнітної картки
   • int CustomerType - тип замовника в POS системі (Не впливає на виконання запиту)
   • int CustomerID - ID замовника в POS системі (Не впливає на виконання запиту)
   • Transaction[] Transactions - масив транзакцій структур Transaction. Структура Transaction має такі поля:
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі (Не впливає на виконання запиту)
       ◦ int ServiceGroupCode - код групи послуг POS системи o decimal Quantity - кількість послуг за транзакцією o decimal Sum - сума транзакції o string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ string ServiceProviderName - Найменування постачальника послуг (Не впливає на виконання запиту)
       ◦ string ServiceProviderID - ID постачальника послуг у POS системі (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека

decimal ReceiptSum - Сума чека

▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

   • int ItemID - ID нарахування
   • int ServiceCode - Код послуги
   • string Name - Назва послуги
   • string ClassName - Назва класу послуги
   • string ClassCode - Код класу послуги
   • string SubClassName - Назва підкласу послуги
   • string SubClassCode - Код підкласу послуги
   • decimal Price - Ціна позиції
   • decimal Quantity - Кількість - Кількість
   • decimal Total - Підсумкова вартість

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

   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • int MagneticCardID - ID магнітної картки
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal BonusBalance - поточний бонусний баланс електронного гаманця
   • Transaction[] Transactions - масив транзакцій Transaction, за якими можливо виконати нарахування бонусів. Структура Transaction має такі поля:
   • DateTime TransactionDate - дата проведення транзакції в POS-системі 

(Порожнє поле) o int ServiceGroupCode - код групи послуг POS системи o decimal Quantity - кількість послуг за транзакцією o decimal Sum - сума транзакції o string[30] POSsystemAccount - Л/Рахунок у POS системі o string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Порожнє поле)

   • string ServiceProviderName - Найменування постачальника послуг o string ServiceProviderID - ID постачальника послуг у POS-системі o TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

       ◦ int ItemID - ID нарахування
       ◦ int ServiceCode - Код послуги
       ◦ string Name - Назва послуги
       ◦ string ClassName - Назва класу послуги
       ◦ string ClassCode - Код класу послуги
       ◦ string SubClassName - Назва підкласу послуги
       ◦ string SubClassCode - Код підкласу послуги
       ◦ decimal Price - Ціна позиції
       ◦ decimal Quantity - Кількість - Кількість
       ◦ decimal Total - Підсумкова вартість
       ◦ string Error - опис помилки, що виникла
       ◦ bool IsOTPNeed - ознака необхідності підтвердження операції паролем/пін-кодом

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

Add_eWallet_Bonuses

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

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

   • int MagneticCardID - ID магнітної картки.
   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • POSServiceProvider[] POSServiceProviders - Список сервіс провайдерів, які беруть участь в операції. (Опціонально). Структура POSServiceProvider має такі поля:
       ◦ string POSSProviderID - ID постачальника послуг у POS системі 
       ◦ string CompanyName - Назва компанії 
       ◦ bool IsCompany - Компанія чи фізособа 
       ◦ рядок AddressLegal - Юридична адреса 
       ◦ рядок ITN - ІПН 
       ◦ string TaxIDCode - ЄДРПОУ(У) 
       ◦ string JobPosition - Посада для підпису (наприклад: Директор) 
       ◦ string Employee - Прізвище та ініціали для підпису (наприклад Пупкін В.П.) 
       ◦ string AffilateCode - Код філії, якщо є 
       ◦ string Bank_MFO - МФО банку з реквізитів рахунку 
       ◦ string Bank_Name - Назва банку з реквізитів рахунку 
       ◦ string Bank_Account - Рахунок у банку з реквізитів рахунку 
       ◦ string IBAN - IBAN з реквізитів рахунку, якщо є 
       ◦ string NDSNumber - Номер свідоцтва платника ПДВ, якщо є
   • Transaction[] Transactions - масив транзакцій для нарахування бонусів Transaction. 

Структура Transaction має такі поля: o decimal Sum - сума транзакції. o DateTime TransactionDate - дата проведення транзакції в POS-системі.

       ◦ int ServiceGroupCode - код групи послуг POS-системи.
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ десяткова? Quantity - кількість o TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:

▪ int BillID - ID рахунку в POS-системі ▪ DateTime BillDate - Дата створення рахунку ▪ int CurrencyCode - Міжнародний код валюти оплати ▪ string ReceiptType - Тип чека ▪ decimal ReceiptSum - Сума чека ▪ string PaymentType - Назва типу оплати ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:

   • int ItemID - ID нарахування
   • int ServiceCode - Код послуги
   • string Name - Назва послуги
   • string ClassName - Назва класу послуги
   • string ClassCode - Код класу послуги
   • string SubClassName - Назва підкласу послуги
   • string SubClassCode - Код підкласу послуги
   • decimal Price - Ціна позиції
   • decimal Quantity - Кількість - Кількість
   • decimal Total - Підсумкова вартість 

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

   • int MagneticCardID - ID магнітної картки програми лояльності із запиту.
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту.
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal AddedBonuses - кількість нарахованих бонусів за транзакції
   • decimal BonusBalance - поточний бонусний баланс електронного гаманця
   • string Error - опис помилки, що виникла

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

Return_Add_eWallet_Bonuses_Request

Метод виконує запит інформації щодо можливості повернення транзакцій з нарахуванням бонусів за ID магнітної картки та списком транзакцій. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int MagneticCardID - ID магнітної картки
   • int CustomerType - тип замовника в POS системі (Не впливає на виконання запиту)
   • int CustomerID - ID замовника в POS системі (Не впливає на виконання запиту)
   • Transaction[] Transactions - масив транзакцій структур Transaction. Структура Transaction має такі поля: 
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі 
       ◦ int ServiceGroupCode - код групи послуг POS системи o decimal Quantity - кількість послуг за транзакцією 
       ◦ decimal Sum - сума транзакції 
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ string ServiceProviderName - Найменування постачальника послуг (Не впливає на виконання запиту)
       ◦ string ServiceProviderID - ID постачальника послуг у POS системі (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS-системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               • int ItemID - ID нарахування
               • int ServiceCode - Код послуги
               • string Name - Назва послуги
               • string ClassName - Назва класу послуги
               • string ClassCode - Код класу послуги
               • string SubClassName - Назва підкласу послуги
               • string SubClassCode - Код підкласу послуги
               • decimal Price - Ціна позиції
               • decimal Quantity - Кількість - Кількість

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту
   • bool IsOTPNeed - ознака необхідності підтвердження операції паролем/пін-кодом (Завжди false)
   • Transaction[] Transactions - масив транзакцій Transaction, за якими можливо виконати скасування нарахування бонусів. Структура Transaction має такі поля:
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі
       ◦ int ServiceGroupCode - код групи послуг POS системи 
       ◦ decimal Quantity - кількість послуг за транзакцією
       ◦ decimal Sum - сума транзакції
       ◦ string[30] POSsystemAccount - Л/Рахунок в POS системі
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Даний код повинен бути унікальним в межах POS системи серед не віддалених точок.
       ◦ string string ServiceProviderName - Найменування постачальника послуг
       ◦ string ServiceProviderID - ID постачальника послуг в POS системі
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               • int ItemID - ID нарахування
               • int ServiceCode - Код послуги
               • string Name - Назва послуги
               • string ClassName - Назва класу послуги
               • string ClassCode - Код класу послуги
               • string SubClassName - Назва підкласу послуги
               • string SubClassCode - Код підкласу послуги
               • decimal Price - Ціна позиції
               • decimal Quantity - Кількість
               • decimal Total - Підсумкова вартість

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

Return_Add_eWallet_Bonuses_Accept

Метод виконує підтвердження повернення транзакцій з нарахуванням бонусів за ID магнітної картки та списком транзакцій. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int MagneticCardID - ID магнітної картки
   • int CustomerType - тип замовника в POS системі (Не впливає на виконання запиту)
   • int CustomerID - ID замовника в POS системі (Не впливає на виконання запиту)
   • Transaction[] Transactions - масив транзакцій структур Transaction. Структура Transaction має такі поля:
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі 
       ◦ int ServiceGroupCode - код групи послуг POS системи (Не впливає на виконання запиту)
       ◦ decimal Quantity - кількість послуг за транзакцією 
       ◦ decimal Sum - сума транзакції o string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ string ServiceProviderName - Найменування постачальника послуг (Не впливає на виконання запиту)
       ◦ string ServiceProviderID - ID постачальника послуг у POS системі (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку (Опціонально). Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS-системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               • int ItemID - ID нарахування
               • int ServiceCode - Код послуги
               • string Name - Назва послуги
               • string ClassName - Назва класу послуги
               • string ClassCode - Код класу послуги
               • string SubClassName - Назва підкласу послуги
               • string SubClassCode - Код підкласу послуги
               • decimal Price - Ціна позиції
               • decimal Quantity - Кількість - Кількість
               • decimal Total - Підсумкова вартість
               • POSServiceProvider[] POSServiceProviders - Список сервіс провайдерів, які беруть участь в операції. (Не впливає на виконання запиту). Структура POSServiceProvider має такі поля:
                   ◦ string POSSProviderID - ID постачальника послуг у POS системі 
                   ◦ string CompanyName - Назва компанії 
                   ◦ bool IsCompany - Компанія чи фізособа 
                   ◦ рядок AddressLegal - Юридична адреса 
                   ◦ рядок ITN - ІПН 
                   ◦ string TaxIDCode - ЄДРПОУ(У) 
                   ◦ string JobPosition - Посада для підпису (наприклад: Директор) 
                   ◦ string Employee - Прізвище та ініціали для підпису (наприклад Пупкін В.П.) 
                   ◦ string AffilateCode - Код філії, якщо є 
                   ◦ string Bank_MFO - МФО банку з реквізитів рахунку 
                   ◦ string Bank_Name - Назва банку з реквізитів рахунку 
                   ◦ string Bank_Account - Рахунок у банку з реквізитів рахунку 
                   ◦ string IBAN - IBAN з реквізитів рахунку, якщо є 
                   ◦ string NDSNumber - Номер свідоцтва платника ПДВ, якщо є

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту
   • decimal AddedBonuses - кількість нарахованих бонусів за транзакції Спочатку відбувається перевірка на бонусний тип програми, якщо ні - повертаємо

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

Pay_Transaction_eWallet_Bonuses_Request

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

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

   • int MagneticCardID - ID магнітної картки.
   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • Transaction[] Transactions - масив транзакцій структур Transaction. Структура Transaction має такі поля: 
       ◦ DateTime? TransactionDate - дата проведення транзакції в POS системі. (Не впливає на виконання запиту)
       ◦ int ServiceGroupCode - код групи послуг POS-системи. o decimal Sum - сума транзакції.
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту) 

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

   • string Error - опис помилки, що виникла.
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту.
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту.
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту.
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту.
   • PayTransaction[] PayTransactions - масив транзакцій для оплати бонусами PayTransaction. Структура PayTransaction має такі поля: o DateTime TransactionDate - дата проведення транзакції в POS-системі. o int ServiceGroupCode - код групи послуг POS-системи. o decimal Sum - сума транзакції.
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі. (Порожнє поле) o decimal BonusesToPay - кількість бонусів, необхідних для оплати транзакції
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Даний код повинен бути унікальним в межах POS системи серед не віддалених точок. (Порожнє поле). o string ErrorTransaction - опис виниклої помилки для конкретної транзакції. (Порожнє поле)

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

Pay_Transaction_eWallet_Bonuses_Accept

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

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

   • int MagneticCardID - ID магнітної картки.
   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • PayTransaction[] Transactions - масив транзакцій для оплати бонусами PayTransaction. Структура PayTransaction має такі поля:
       ◦ decimal Sum - сума транзакції. o DateTime TransactionDate - дата проведення транзакції в POS-системі. o int ServiceGroupCode - код групи послуг POS-системи.
       ◦ decimal BonusesToPay - кількість бонусів, необхідних для оплати транзакції.
       ◦ десяткова? Quantity - кількість o string[30] POSsystemAccount - Л/Рахунок у POS системі. (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально) Структура TransactionDetails має такі поля:
            • int BillID - ID рахунку в POS-системі
            • DateTime BillDate - Дата створення рахунку
            • int CurrencyCode - Міжнародний код валюти оплати
            • string ReceiptType - Тип чека
            • decimal ReceiptSum - Сума чека
            • string PaymentType - Назва типу оплати
            • PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
              	 ◦	int ItemID - ID нарахування

◦ int ServiceCode - Код послуги ◦ string Name - Назва послуги ◦ string ClassName - Назва класу послуги ◦ string ClassCode - Код класу послуги

                ◦	string SubClassName - Назва підкласу послуги

◦ string SubClassCode - Код підкласу послуги

              	 ◦	decimal Price - Ціна позиції

◦ decimal Quantity - Кількість - Кількість

                ◦	decimal Total - Підсумкова вартість

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal PayBonuses - загальна сума списаних бонусів
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту

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

Return_Pay_Transaction_eWallet_Bonuses_Request

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

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int MagneticCardID - ID магнітної картки
   • int CustomerType - тип замовника в POS системі (Не впливає на виконання запиту)
   • int CustomerID - ID замовника в POS системі (Не впливає на виконання запиту)
   • Transaction[] Transactions - масив транзакцій структур Transaction. Структура Transaction має такі поля:
       o DateTime TransactionDate - дата проведення транзакції в POS системі 
       o int ServiceGroupCode - код групи послуг POS системи 
       o decimal Quantity - кількість послуг за транзакцією 
       o decimal Sum - сума транзакції 
       o string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       o string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       o string ServiceProviderName - найменування постачальника послуг 
       o string ServiceProviderID - ідентифікатор постачальника послуг TransactionDetails[] Details - деталізація позицій рахунку. Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS-системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               • int ItemID - ID нарахування
               • int ServiceCode - Код послуги
               • string Name - Назва послуги
               • string ClassName - Назва класу послуги
               • string ClassCode - Код класу послуги
               • string SubClassName - Назва підкласу послуги
               • string SubClassCode - Код підкласу послуги
               • decimal Price - Ціна позиції
               • decimal Quantity - Кількість - Кількість
               • decimal Total - Підсумкова вартість

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту
   • bool IsOTPNeed - ознака необхідності підтвердження операції паролем/пін-кодом (Завжди false)
   • PayTransaction[] PayTransactions - масив транзакцій для оплати бонусами PayTransaction. Структура PayTransaction має такі поля:
       o DateTime TransactionDate - дата проведення транзакції в POS системі 
       o int ServiceGroupCode - код групи послуг POS системи (Порожнє поле) 
       o decimal Sum - сума транзакції 
       o decimal Quantity - кількість послуг за транзакцією 
       o string[30] POSsystemAccount - Л/Рахунок у POS-системі (Порожнє поле)
       o decimal BonusesToPay - кількість бонусів, необхідних для оплати транзакції
       o string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Порожнє поле)
       o string ErrorTransaction - опис помилки, що виникла для конкретної транзакції (Порожнє поле)
       o string ServiceProviderName - найменування постачальника послуг 
       o string ServiceProviderID - ідентифікатор постачальника послуг 
       o TransactionDetails[] Details - деталізація позицій рахунку. Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS-системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               ◦ int ItemID - ID нарахування
               ◦ int ServiceCode - Код послуги
               ◦ string Name - Назва послуги
               ◦ string ClassName - Назва класу послуги
               ◦ string ClassCode - Код класу послуги
               ◦ string SubClassName - Назва підкласу послуги
               ◦ string SubClassCode - Код підкласу послуги
               ◦ decimal Price - Ціна позиції
               ◦ decimal Quantity - Кількість - Кількість
               ◦ decimal Total - Підсумкова вартість

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

Return_Pay_Transaction_eWallet_Bonuses_Accept

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

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int MagneticCardID - ID магнітної картки
   • int CustomerType - тип замовника в POS системі (Не впливає на виконання запиту)
   • int CustomerID - ID замовника в POS системі (Не впливає на виконання запиту)
   • PayTransaction[] Transactions - масив транзакцій для оплати бонусами PayTransaction. Структура PayTransaction має такі поля:: 
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі
       ◦ int ServiceGroupCode - код групи послуг POS системи
       ◦ decimal Quantity - кількість послуг за транзакцією
       ◦ decimal Sum - сума транзакції o string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ decimal BonusesToPay - кількість бонусів, необхідних для оплати транзакції (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ рядок ErrorTransaction - f o string ServiceProviderName - найменування постачальника послуг 
       ◦ string ServiceProviderName - ідентифікатор постачальника послуг
       ◦ TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:
           ▪ int BillID - ID рахунку в POS-системі
           ▪ DateTime BillDate - Дата створення рахунку
           ▪ int CurrencyCode - Міжнародний код валюти оплати
           ▪ string ReceiptType - Тип чека
           ▪ decimal ReceiptSum - Сума чека
           ▪ string PaymentType - Назва типу оплати
           ▪ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
               • int ItemID - ID нарахування
               • int ServiceCode - Код послуги
               • string Name - Назва послуги
               • string ClassName - Назва класу послуги
               • string ClassCode - Код класу послуги
               • string SubClassName - Назва підкласу послуги
               • string SubClassCode - Код підкласу послуги
               • decimal Price - Ціна позиції
               • decimal Quantity - Кількість
               • decimal Total - Підсумкова вартість
               • POSServiceProvider[] POSServiceProviders - Список сервіс провайдерів, які беруть участь в операції. (Не впливає на виконання запиту). Структура POSServiceProvider має такі поля:
                    o string POSSProviderID - ID постачальника послуг у POS системі 
                    o string CompanyName - Назва компанії 
                    o bool IsCompany - Компанія чи фізособа 
                    o рядок AddressLegal - Юридична адреса 
                    o рядок ITN - ІПН 
                    o string TaxIDCode - ЄДРПОУ(У) 
                    o string JobPosition - Посада для підпису (наприклад: Директор) 
                    o string Employee - Прізвище та ініціали для підпису (наприклад Пупкін В.П.) 
                    o string AffilateCode - Код філії, якщо є
                    o string Bank_MFO - МФО банку з реквізитів рахунку
                    o string Bank_Name - Назва банку з реквізитів рахунку 
                    o string Bank_Account - Рахунок у банку з реквізитів рахунку 
                    o string IBAN - IBAN з реквізитів рахунку, якщо є 
                    o string NDSNumber - Номер свідоцтва платника ПДВ, якщо є
                • string CodeOTP - пароль/пін-код підтвердження операції

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal BonusBalance - баланс бонусів учасника програми лояльності, якому належить картка із запиту
   • decimal PayBonuses - загальна кількість витрачених бонусів за транзакції 

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

Get_Certificates_Info

Метод за ID і номером сертифікатів повертає інформацію за знайденими сертифікатами. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int? СertificateID - ID сертифіката
   • string[100] CertificateNumber - Номер сертифіката
   • string[20] CertificateCode - код оплати сертифіката (Не впливає на виконання запиту)

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

   • string Error - опис помилки, що виникла
   • Certificates[] - масив описів сертифікатів Certificate . Елементи масиву структури з такими полями:
       ◦ int CertificateID - ID сертифіката 
       ◦ string CertificateNumber - Номер сертифіката 
       ◦ string CertificateCode - код оплати сертифіката (Порожнє поле) 
       ◦ string CertificateTypeName - тип сертифіката 
       ◦ bool IsCertificateTypeActive - тип сертифіката активний? 
       ◦ bool IsCertificateTypeDeleted - тип сертифіката видалено?
       ◦ DateTime? CertificateTypeActionStartDate - дата початку проведення акції типу сертифіката (Порожнє поле)
       ◦ DateTime? CertificateTypeActionEndDate - дата закінчення проведення акції типу сертифіката (Порожнє поле)
       ◦ decimal CertificateAmount - сума сертифіката o bool IsCertificateActive - статус сертифіката активний?
       ◦ string CertificateStatusName - назва статусу сертифіката 
       ◦ DateTime? CertificateActivationDate - дата активації CertificateActivationDate 
       ◦ DateTime? CertificateDeactivationDate - дата деактивації.
       ◦ int? AccountID - ідентифікатор власника o string[100] LoyaltyProgramName - назва програми лояльності гаманця 
       (Порожнє поле) 
       ◦ string UserName - ПІБ учасника з анкети електронного гаманця (якщо є гаманець і анкета учасника, інакше null).

Certificate_Transactions_Request

Метод виконує запит інформації щодо можливості оплати сертифікатом за ID сертифіката і списком транзакцій. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS системи, за яким шукається зв'язка POS системи та користувача програми лояльності. (Не впливає на виконання запиту)
   • int CertificateID - ID сертифіката
   • CertificateTransaction[] CertificateTransactions - масив транзакцій структур Transaction. Структура Transaction має такі поля: 
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі (Не впливає на виконання запиту)
       ◦ int ServiceGroupCode - код групи послуг POS системи (Не впливає на виконання запиту)
       ◦ decimal Sum - сума транзакції o string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ string ServiceProviderName - Найменування постачальника послуг (Не впливає на виконання запиту)
       ◦ int? PaymentID - ID нарахування. Необхідно для пошуку учасника програми лояльності.
       ◦ string TransactionError - опис виниклої помилки для конкретної транзакції (Не впливає на виконання запиту)
       ◦ DateTime PaymentConsumptionDate - дата споживання послуги (з нарахування) (Не впливає на виконання запиту)

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

   • int CertificateID - ID сертифіката
   • string CertificateStatusName - статус сертифіката
   • decimal CertificateAmount - ціна сертифіката
   • DateTime? CertificateDeactivationDate - дата деактивації. Найменша з цих двох: розрахована дата деактивації сертифіката і дата припинення дії типу сертифіката. (CertificateDeactivationDate буде null, якщо дата активації сертифіката == null) У цей день сертифікат ВЖЕ не діє.
   • int? AccountID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, який оплатив нарахування, якщо такий є.
   • CertificateTransaction[] CertificateTransactions - масив транзакцій для оплати сертифікатом CertificateTransaction. Структура CertificateTransaction має такі поля:
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі 
       ◦ int ServiceGroupCode - код групи послуг POS системи 
       ◦ decimal Sum - сума транзакції 
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі 
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. 
       ◦ string ServiceProviderName - Найменування постачальника послуг 
       ◦ int? PaymentID - ID нарахування. Необхідно для пошуку учасника програми лояльності.
       ◦ string TransactionError - опис виниклої помилки для конкретної транзакції
       ◦ DateTime PaymentConsumptionDate - дата споживання послуги (з нарахування)
   • string Error - опис помилки, що виникла
   • bool IsOTPNeed - ознака необхідності підтвердження операції паролем/пін-кодом

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

Certificate_Transactions_Accept

Метод виконує підтвердження оплати сертифіката за ID сертифіката і списком транзакцій. Метод підходить для HMS.

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

   • string[32] POSCode - унікальний код POS-системи, за яким шукається зв'язка POSсистеми та користувача програми лояльності.
   • int CertificateID - ID сертифіката
   • int MagneticCardID - ідентифікатор карти
   • string CodeOTP - пароль/пін-код підтвердження операції
   • CertificateTransaction[] CertificateTransactions - масив транзакцій для оплати сертифікатом CertificateTransaction. Структура CertificateTransaction має такі поля:
       ◦ DateTime TransactionDate - дата проведення транзакції в POS системі o int ServiceGroupCode - код групи послуг POS системи (Не впливає на виконання запиту)
       ◦ decimal Sum - сума транзакції o int? PaymentID - ID нарахування. Необхідно для пошуку учасника програми лояльності.
       ◦ string[30] POSsystemAccount - Л/Рахунок у POS системі (Не впливає на виконання запиту)
       ◦ string[30] PointOfSalePOScode - код точки продажу в POS системі. Цей код має бути унікальним у межах POS системи серед не віддалених точок. (Не впливає на виконання запиту)
       ◦ DateTime PaymentConsumptionDate - дата споживання послуги (з нарахування) 
       (Не впливає на виконання запиту) 
       ◦ string ServiceProviderName - найменування постачальника послуг 
       ◦ string TransactionError - опис виниклої помилки для конкретної транзакції
   • TransactionDetails Details - деталізація позицій рахунку. (Опціонально). Структура TransactionDetails має такі поля:
       ◦ int BillID - ID рахунку в POS-системі 
       ◦ DateTime BillDate - Дата створення рахунку 
       ◦ int CurrencyCode - Міжнародний код валюти оплати 
       ◦ string ReceiptType - Тип чека 
       ◦ decimal ReceiptSum - Сума чека 
       ◦ string PaymentType - Назва типу оплати 
       ◦ PositionInfo[] Items - Деталізація позицій чека. Структура PositionInfo має такі поля:
           ▪ int ItemID - ID нарахування
           ▪ int ServiceCode - Код послуги
           ▪ string Name - Назва послуги
           ▪ string ClassName - Назва класу послуги
           ▪ string ClassCode - Код класу послуги
           ▪ string SubClassName - Назва підкласу послуги
           ▪ string SubClassCode - Код підкласу послуги
           ▪ decimal Price - Ціна позиції
           ▪ decimal Quantity - Кількість - Кількість
           ▪ decimal Total - Підсумкова вартість

Результат функції: • string Error - опис помилки, що виникла • int CertificateID - ID сертифіката

   • string CertificateStatusName - статус сертифіката
   • decimal CertificateStartBalance - вартість сетрифіката
   • decimal AllTransactionsSum - сума всіх проведених транзакцій
   • decimal CertificateFinishBalance - залишок сертифіката
   • int? AccountID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, який оплатив нарахування, якщо такий є.

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

Money_Input_Request

Метод виконує запит інформації щодо можливості покласти гроші на картку за ID магнітної картки. Метод підходить для HMS.

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

   • int MagneticCardID - ID магнітної картки програми лояльності 

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal MoneyBalance - баланс лояльних грошей учасника програми лояльності, якому належить картка із запиту

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

Money_Input

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

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

   • int MagneticCardID - ID магнітної картки програми лояльності (для HMS)
   • int CardNumber - короткий або довгий номер магнітної картки програми лояльності (для POS)
   • decimal Summ - сума поповнення
   • DateTime? PaymentTime - час оплати (необов'язкове поле, якщо не вказувати, братиметься час готелю із запиту або час інсталяції) 

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

   • string Error - опис помилки, що виникла
   • int MagneticCardID - ID магнітної картки програми лояльності із запиту
   • int eWalletID - ID учасника програми лояльності, якому належить картка із запиту
   • string UserName - ім'я (ПІБ контакту або назва компанії) учасника програми лояльності, якому належить картка із запиту
   • decimal MoneyBalance - баланс лояльних грошей учасника програми лояльності, якому належить картка із запиту
   • eWallet[] eWallets - результат аналогічний функції Get_eWallet_Info.

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