API Протокол обміну даними між системами Servio HMS та Servio Restaurant

Матеріал з expertsolution
Перейти до навігації Перейти до пошуку

СПИСОК ЗМІН

ДАТА ВНЕСЕННЯ ЗМІНЕНА ЧАСТИНА (Розділ, сторінка) НОМЕР НОВОЇ РЕДАКЦІЇ ЗМІНИ Тип (доповнення, видалення) та конкретний опис
14.05.13 1.00 Документ створено
15.05.13 1.00 Документ написано
13.06.13 1.01 Повний збіг при пошуку гостя по кімнаті. Поля TransactionID, Description при проведенні транзакції.
30.07.14 1.02 Додавання функцій для проведення підтвердження споживання нарахувань по корпоративній карті.
11.08.14 1.03 Протокол перероблено під використання довгого номера в картах лояльності.
26.08.14 1.04 Додано ClientID у функцію пошуку, змінено функції роботи з карткою лояльності.
16.10.14 1.05 Внесено зміни в логіку методу GetGuestNotConfirmSales (обробка пакетів послуг)
16.10.14 1.06 Внесено зміни в логіку методу GetTransactionObjects додано фільтрацію по замковим картам.
08.11.2018 1.07 Додано необов'язкове поле RestaurantBill у метод DoTransaction. Поле успадковується в окреме як частина попереднього поля Description і є XML рядком ресторанного рахунку.
28.09.2021 1.08 Додано опис структури XML поля RestaurantBill
Додано поля для структури RestaurantBill що доповнюють властивості товарів:
TRANSLATIONS – переклади
EXCISESTAMPS – акцизні марки

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

Цей протокол описує взаємодію між програмними пакетами Servio HMS (далі - «готель») і програмними пакетами Servio Restaurant ( «ресторан»). Ініціатором взаємодії є користувач «ресторану». На стороні «готель» реалізовані веб-сервіси, які викликаються з «ресторану». Взаємодію можна розділити на 2 етапи: ідентифікація, транзакція.
На етапі ідентифікації виводиться список «готельних» об'єктів, які можуть брати участь в угоді. Для пошуку об'єктів використовується один з наступних алгоритмів:

  • Пошук гостей – введення параметрів: номер кімнати, гостьовий рахунок, номер картки депозитного рахунку. Результатом буде список паспортних даних знайдених гостей із зазначенням Особистого кабінету, Номера депозитного рахунку, Номера номера, Прізвища, Кредитного ліміту, Балансу гостя, Залишку депозиту, Залишку всіх депозитів, Дати проживання. Якщо клієнтів у гостя немає, то відображається інформація про гостя.
  • Пошук активних подій – Вхідні параметри: Немає. Результатом буде список активних подій, що діють на поточну дату, з наступною інформацією: L/Account події, назва, назва типу події, дати проведення події, баланс.
  • Пошук активних постійних облікових записів – вхідні параметри: немає. Результатом буде список активних постійних рахунків з наступною інформацією: L/Рахунки постійного рахунку, назви, назва типу постійного рахунку, залишок.
  • Пошук активних особових рахунків – Вхідні параметри: немає. Результатом буде список активних особових рахунків із зазначенням: Особистий кабінет, ПІБ клієнта, дата проживання, баланс.

В результаті пошуку користувачеві «ресторану» видається список об'єктів угоди. Він вибирає об'єкт, що цікавить, і переходить до наступного етапу: проведення угоди.

На етапі транзакції користувач вибирає об'єкт угоди, тип угоди. Тип угоди - це один з наступних варіантів проведення угоди: закриття на об'єкті угоди, оплата депозитом. При закритті угоди по об'єкту, нарахування послуги додається на
основний рахунок цього об'єкта, і ніяких подальших дій не очікується. При оплаті завдатком платником створюється рахунок-фактура, згідно з яким до рахунку нарахування послуги додається об'єкт транзакції, оплата здійснюється шляхом депозиту, а рахунок закривається.
В результаті транзакції користувачеві «ресторану» показується результат транзакції.


Опис реалізації

Реалізація являє собою dll для проекту ExternalConnectionService, для якого реалізована WCF служба з наступними функціями:

GetTransactionObjects

  • GetTransactionObjects – функція на основі вхідних параметрів генерує список об'єктів транзакцій та повертає їх у результаті.

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

  • HotelID – ідентифікатор готелю, обов'язковий, вн. Фільтри за об'єктом готелю.
  • AccountType – тип запитуваного об'єкта, обов'язковий параметр, перерахування: 1 – гість, 4 – подія, 5 – постійний обліковий запис, 6 – особистий кабінет. Цей параметр визначає алгоритм пошуку об'єктів угоди.
  • GuestID – обліковий запис L/Guest, необов'язковий параметр, int. Фільтри за особистим кабінетом гостя. Цей параметр використовується тільки в алгоритмі пошуку побутових клієнтів, в інших алгоритмах він ігнорується.
  • RoomNumber — номер кімнати, необов'язковий параметр, рядок[20]. Фільтрує за номером кімнати гостя, щоб переконатися, що рядок введення повністю збігається з рядками номера кімнати. Цей параметр використовується тільки в алгоритмі пошуку побутових клієнтів, в інших алгоритмах він ігнорується.
  • DepositCardNumber – номер картки депозитного рахунку, необов'язковий параметр, рядок[20]. Він фільтрується за номером картки, прив'язаної до депозитного рахунку клієнта, забезпечується повний збіг рядків. Цей параметр використовується тільки в алгоритмі пошуку побутових клієнтів, в інших алгоритмах він ігнорується.
  • LoyaltyCardNumber – номер картки лояльності, рядок. Разом з типом програми лояльності фільтрує проживаючих гостей-покупців по картці лояльності. Забезпечується повний збіг номера картки. Цей параметр використовується тільки в алгоритмі пошуку побутових клієнтів, в інших алгоритмах він ігнорується.
  • LockCardNumber – це необов'язковий рядковий параметр, номер картки системи блокування. Фільтрує гостей за карткою замку. Забезпечується повний збіг номера картки. Цей параметр використовується тільки в алгоритмі пошуку побутових клієнтів, в інших алгоритмах він ігнорується.

Результат:

Повертає список структур TransactionObject в результаті:

  • HotelID - ідентифікатор готелю, обов'язковий, вн.
  • AccountType – тип запитуваного об'єкту, обов'язковий параметр перебору: 1 – гість, 4 – подія, 5 – постійний рахунок, 6 – особистий кабінет.
  • AccountID – L/аккаунт сутності об'єкта транзакції, обов'язковий параметр, int.
  • DepositID – ID депозитного рахунку, необов'язковий параметр, int. Заповнюється тільки для депозитного рахунку клієнта.
  • ClientID – ID паспортних даних, необов'язковий параметр, int. Заповнюється тільки для гостей.
  • PlaceName – розташування об'єкту транзакції, необхідний параметр, рядок[50]. Для гостей він заповнюється із зазначенням кількості та типу залу, для заходів – назва типу заходу, для постійного рахунку – назва типу постійного рахунку, для особистого кабінету – назва готелю.
  • Name – ім'я об'єкта транзакції, необхідний параметр, рядок[200]. Для гостей заповнюється ПІБ клієнта, якщо немає, то ПІБ гостя. Для подій – назва події, для постійного рахунку – назва постійного рахунку, для особистого кабінету – ПІБ клієнта.
  • FirstDate — дата початку об'єкта транзакції, необов'язковий параметр, рядок "dd.MM.yyyy ГГ:хх". Для гостя – дата приїзду гостя, для заходу – дата початку заходу, для постійного рахунку – порожня, для особистого кабінету – дата заїзду.
  • LastDate – дата завершення об'єкту транзакції, необов'язковий параметр, рядок "дд.ММ.рррррр ГГ:х". Для гостя – дата виїзду гостя, для заходу – дата проведення закінчення заходу, для постійного рахунку – порожній, для особистого – дата виїзду.
  • CreditLimit – кредитний ліміт об'єкту транзакції, необов'язковий параметр, рядок: "d15.d2". Для гостя – кредитний ліміт гостя, для заходу – кредитний ліміт події, для постійного рахунку – порожній, для особистого кабінету – порожній.
  • Balance – баланс об'єкта транзакції, обов'язковий параметр, рядок: "d15.d2". Для гостя – баланс гостя, для заходу – баланс заходу, для постійного рахунку – постійний залишок на рахунку, для особистого кабінету – баланс особового рахунку.
  • DepositBalance – залишок коштів на депозитному рахунку, необов'язковий параметр, рядок: "d15.d2". Заповнюється тільки для депозитного рахунку клієнта в базовій валюті.
  • GuestDepositBalance - це сума залишків всіх депозитних рахунків цього гостя, необов'язковий параметр, рядок: "d15.d2". Він заповнюється тільки для гостя, якщо у гостя є параметр загального депозиту, використовуються депозитні рахунки базової валюти.

Алгоритм пошуку гостей:

  1. Ми знаходимо всіх гостей цього готелю, які проживають на даний момент.
  2. Якщо вказано параметр GuestID, фільтруйте за Особистим кабінетом гостя.
  3. Якщо вказано параметр RoomNumber, фільтруйте за номером кімнати.
  4. Якщо вказано параметр LockCardNumber, фільтруйте гостей за прив'язаними картками блокування.
  5. Якщо вказано параметр LoyaltyCardNumber, фільтруйте гостей за карткою лояльності, використовуючи поле «довгий номер»
  6. Для списку гостей, що залишився, ми знаходимо всі паспортні дані і формуємо список гостей-клієнтів, а якщо клієнта немає, то в якості прізвища беремо ПІБ гостя.
  7. По кожному гостю-клієнту зі списку знайдіть всі відкриті депозитні рахунки базової валюти, сформуйте список депозитів гостя-клієнта.
  8. Якщо вказано параметр DepositCardNumber, відфільтруйте список депозитів гість-клієнт-депозит за номером картки депозитного рахунку.
  9. Для решти списку депозитів гість-клієнт формуємо отриманий список.

Алгоритм пошуку подій:

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

Алгоритм пошуку постійних облікових записів:

  1. Ми знаходимо всі активні постійні рахунки цього готелю.
  2. На основі отриманого списку формуємо отриманий список.

Алгоритм пошуку в особистих рахунків

  1. Знайдіть всі активні особисті кабінети цього готелю.
  2. На основі отриманого списку формуємо отриманий список.

DoTransaction

DoTransaction - функція проведення транзакції по об'єкту. Повертає bool значення, що вказує на успішність або неуспішність проведення транзакції.

  • HotelID (int) – ідентифікатор готелю, обов'язковий параметр
  • AccountType – тип запитуваного об'єкта, обов'язковий параметр, перелік:
    • 1 - гість
    • 4 - подія
    • 5 - постійний рахунок
    • 6 - особовий рахунок
  • AccountID (int) – особовий рахунок сутності об'єкта транзакції, обов'язковий параметр
  • DepositID (int) – ідентифікатор депозитного рахунку, необов'язковий параметр. Заповнюється лише для оплати з депозитного рахунку клієнта.
  • ServiceID (int) – ідентифікатор операції проведення послуги, необов'язковий параметр. Якщо параметр не вказано, використовується послуга ресторану за замовчуванням.
  • Quantity (string "d6.d3") – кількість послуги, обов'язковий параметр
  • Price (string "d15.d2") – ціна послуги, обов'язковий параметр
  • TransactionType – тип транзакції, обов'язковий параметр, перелік:
    • 1 – закриття на рахунок об'єкта
    • 2 – оплата депозитом
  • TransactionID (int) – ідентифікатор транзакції в ресторані, необов'язковий параметр
  • Description (string[2000]) – додаткова інформація про транзакцію, необов'язковий параметр
  • RestaurantBill (nvarchar[max]) – детальна інформація про транзакцію у XML-форматі, необов'язковий параметр
  • BILL - рахунок

Атрибути:

  • ID (int) – ідентифікатор рахунку
  • Number (int) – номер рахунку
  • Opened (datetime) – дата відкриття
  • Closed (datetime) – дата закриття
  • TermName – назва терміналу

Поля:

  • ITEMS – масив товарів з атрибутами:
    • ID (int) – ідентифікатор товару
    • Code (string) – код товару
    • Code2 (string) – додатковий код товару
    • Name (string) – назва номенклатури
    • Amount (decimal) – кількість
    • Price (decimal) – ціна
    • Discount (decimal) – знижка
    • Total (decimal) – сума
    • Fiscal (int) – ознака фіскальної позиції (0-ні, 1-фіскальна)
    • AdditionalServiceCode (string) – додатковий код послуги
    • TaxSchema (int) – податкова схема
    • Barcode (string) – штрих-код
    • Excise – акцизна марка
  • COMMENT (string) – друкована форма рахунку
  • TRANSLATIONS – масив перекладів номенклатури:
    • Code – код товару
    • Name – переклад
    • Lang – мова перекладу

Алгоритм проведення транзакції

Пошук об'єкта "гостиниці"

  • Для заданих параметрів (ID готелю, тип об'єкта, ID об'єкта) здійснюється пошук об'єкта "гостиниці"
  • Якщо об'єкт не знайдено:
    • Генерується помилка
    • Алгоритм зупиняється

Створення нарахування послуги

  • Для знайденого об'єкта створюється нарахування послуги з заданими параметрами
  • Нарахування прикріплюється до гостя
  • Якщо виникає помилка:
    • Помилка пробрасовується далі
  • Якщо TransactionType == 1:
    • Транзакція зберігається
    • Повертається результат функції

Пошук депозитного рахунку

  • Для заданих параметрів (ID готелю, тип об'єкта, ID об'єкта, ID депозитного рахунку) здійснюється пошук депозитного рахунку гостиниці
  • Якщо депозитний рахунок не знайдено або виявлено логічну помилку:
    • Генерується помилка
    • Алгоритм зупиняється

Проведення оплати

  • Створюється рахунок з платником-об'єктом
  • До рахунку додається створене нарахування
  • Оплата здійснюється з депозитного рахунку
  • Рахунок закривається
  • Якщо виникає помилка:
    • Помилка пробрасовується далі
  • Повертається результат транзакції

GetGuestNotConfirmSales

GetGuestNotConfirmSales - функція формування списку непідтверджених нарахувань послуг для гостя.

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

  • GuestID (int) - обов'язковий:
    • Особовий рахунок гостя
    • Виконує фільтрацію по особовому рахунку
  • ServiceGroupCodes (string[]) - необов'язковий:
    • Список кодів груп послуг для фільтрації
    • Виконує фільтрацію нарахувань по групі послуг
  • ConsumptionDate (string) - обов'язковий:
    • Дата споживання послуги у форматі "dd.MM.yyyy hh:mm"
    • Виконує фільтрацію по даті споживання
    • Якщо є період споживання - додаткова фільтрація по часу

Результат:

Список структур GuestNotConfirmSale:

  • GuestID (int) - особовий рахунок гостя
  • SaleID (int) - ID нарахування:
 ** Додатні значення - звичайні нарахування
 ** Від'ємні значення - позиції пакетів послуг
  • ServiceCode (int) - код послуги
  • ServiceName (string[200]) - назва послуги
  • ServiceGroupCode (string[50]) - код групи послуг
  • ServiceGroupName (string[50]) - назва групи послуг
  • Quantity (string "d6.d3") - кількість нарахованої послуги
  • UsedQuantity (string "d6.d3") - кількість підтвердженої послуги
  • Price (string "d15.d2") - ціна послуги

Алгоритм пошуку нарахувань

1. Пошук гостя та нарахувань

  • За GuestID знаходимо гостя
  • Отримуємо список не анульованих нарахувань, де він є споживачем

2. Фільтрація по даті

  • Фільтруємо нарахування по ConsumptionDate
  • Якщо є період споживання - додаткова фільтрація по часу

3. Фільтрація по групам послуг

  • Якщо вказано ServiceGroupCodes - фільтрація по коду групи послуг
  • Використовується поле Code з таблиці db_pms.ServiceTypes

4. Формування результату

  • Для залишкового списку формуємо результуючий список
  • Нарахування пакетів послуг заміняються на позиції пакетів


SetConfirmSale

SetConfirmSale - функція підтвердження кількості нарахованої послуги.

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

  • SaleID (int) - обов'язковий:
    • Ідентифікатор нарахування послуги
  • UsedQuantity (string) - обов'язковий:
    • Кількість наданої послуги у поточній сесії
    • Формат: "d6.d3"

Алгоритм підтвердження нарахувань:

1. Пошук нарахування

  • За SaleID знаходимо нарахування послуги
  • Перевіряємо, що нарахування не було анульоване

2. Перевірка кількості

  • Перевіряємо, щоб сума:
 ** UsedQuantity (параметр) 
 ** + UsedQuantity (наявне значення)
  • Не перевищувала Quantity нарахування

3. Оновлення

  • Якщо перевірки успішні:
    • Оновлюємо UsedQuantity новим значенням
    • (UsedQuantity параметра + UsedQuantity нарахування)

Обмеження та загальний опис

Система має такі обмеження:

1. Реалізація сервісу

  • Всі функції реалізовані на протоколі WCF Soap XML Service

2. Форматування чисел

  • Числа з плаваючою комою використовують роздільник "." (крапка)

3. Обробка помилок

  • При виникненні помилки функція:
    • Припиняє роботу
    • Повертає опис помилки через статус відповіді

4. Валютні операції

  • Всі операції проводяться у базовій валюті "готеля"

5. Кодування

  • Всі текстові параметри представлені в кодуванні UTF-8
Отримано з http://wiki.expertsolution.com.ua/index.php?title=API_Протокол_обміну_даними_між_системами_Servio_HMS_та_Servio_Restaurant&oldid=8158