Shopserver. Схема обміну даними

Інженерне мистецтво полягає в пошуку вдалого компромісу. І в нашому випадку це компроміс між потребою реалізувати складну систему, але взаємодіяти з нею простими засобами. Як відомо, HTTP пропонує нам наступні методи для взаємодії GET, POST, PUT, PATCH, DELETE. І розробники REST API залюбки їх використовують. Ідеологія REST полягає в тому, що методами (командами, що треба зробити) виступають як раз ці Get, Post, Put і т.д. А все інше в URL-рядку виступає в якості параметрів. Тобто в середині URL назва методу явно не фігурує. використовуються певні домовленості. Приклад класичної реалізації REST можна подивитись тут. Чи варто безумовно притримуватись стилю REST? На думку автора, тобто на мою думку - ні. 

Як ще спростити наш API? Як зменшити кількість потрібних методів? А ще як зменшити кількість помилок розробників-інтеграторів, які будуть використовувати наш API? А потрібно врахувати специфіку задачі. Отже починаємо говорити конкретно про API касового сервера Shopserver.

Фактично маємо дві інтеграції, які працюють в обидва боки - інтеграцію облікової системи з касовим сервером, та інтеграцію робочого місця касира також з касовим сервером. Розглянемо послідовно обидві інтеграції.

Маємо задачу - вивантажити дані для кас на касовий сервер, та отримати від кас чеки, замовлення, повернення, z-звіти та документи інших типів.

Для кас потрібен набір довідників, а також залишки та ціни по товарах на торгових точках. Маємо задачу максимально спростити таке вивантаження. По перше, зменшуємо до необхідого мінімуму кількість веб-методів, по друге, зменшуємо до мінімально потрібного обсяг даних для вивантаження. Розглянемо, яким чином це досягається.

Зазвичай, класично, для вивантаження кожного довідника створюється окремий веб-метод. Наприклад, вивантаження довідника одиниць виміру, чи довідника груп товарів, чи покупців, чи касирів. Тобто потрібно створити багато різних методів, які передають різні дані. Одразу виникає просто ідея - вивантажувати дані у вигляді єдиного пакета, який ми назвемо контейнером реплікації. Отже, один метод - один пакет. В API для цього використовуємо метод /api/v1/AccountingSystem/SendReplication Структура самого контейнера реплікації детально описана в наданому посиланні. 

Що стосується зменшення обсягів даних - використовуємо стару перевірену реплікацію. Тобто передаємо не весь обсяг даних, а лише ті дані, що змінились, або додались з моменту попередньої реплікації. Зазвичай, на боці облікової системи це робиться наступним чином - для таблиці кожного довідника створюємо поле, де фіксуємо дату-час останнього змінення даних в конкретному рядку. Назвемо його, наприклад, LastModified. Після цього робимо запит, за яким відбираємо лише ті записи, що змінились з моменту попередньої реплікації. Включаємо такі записи до пакету реплікації і відправляємо на касовий сервер. Як показує досвід, довідники змінюються відносно рідко, на відміну від товарних залишків (колекція InventoryRecords в контейнері реплікації).

Часто питають, як видалити ті чи інші записи на касовому сервері. Відповідь проста і категорична - ніяк. Бо це реплікація. Дані, які ви вивантажили на касовий сервер, вже були завантажені касами, і каси їх вже використовують. Тому видалення цих даних на касовому сервері втрачає сенс, вони залишаться на касах. Коли може виникнути потреба видалення окремих даних?

Я перебрав варіанти з минулого досвіду, і щось нічого актуального пригадати не можу. 

Розглянемо типові ситуації. Наприклад, некоректно назвали товар в довіднику облікової системи. Або віднесли товар до іншої групи. В цьому випадку просте виправлення даних в картці товару змінить дату-час в полі LastModified, товар буде включений до наступного контейнера реплікації і нормально оновиться на касовому сервері.

Зробили товару на іншу торгову точку? Оператори можуть, вони такі. Відкотили прихід в обліковій системі, але він вже потрапив на касовий сервер до таблиці InventoryRecords для "некоректної" каси, і, відповідно, на саму касу, куди потрапляти не потрібно. Як потім виловлювати ці "чужі" залишки і видаляти їх на касі?

Варіант може бути лише один - "початкова реплікація". Тобто, щоб бути впевненим, що на касовий сервер після всіх "ремонтів" облікової системи вивантажаться коректні дані, і вони розійдуться по касах, треба вивантажити повний комплект довідників з особливою ознакою в контейнері реплікації IsInitialReplication=true

В цьому випадку сервер попередньо видалить всі дані компанії і запише нові дані з контейнера реплікації. Це гарантує повну узгодженість даних між обліковою системою та касовим сервером, а потім - між касовим сервером та касами. Це своєрідний екстрений ремонтний режим. Використовувати потрібно лише у випадку нагальної потреби.

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

2. Для кожного довідника в таблиці створюємо поле LastModified і пишемо туди дату-час останнього оновлення або додавання даних в цей рядок таблиці.

3. Формуємо контейнер реплікації. Для цього читаємо дані довідників, що змінились з часу останньої успішної реплікації (поле LastModified) і пишемо їх в контейнер.

4. Авторизуємось методом /api/v1/AccountingSystem/Login та отримаємо дані користувача, яким працює ваша облікова система на касовому сервері. Нам в подальшому буде потрібен Bearer-токен з цього об'єкта (поле BearerToken). Зверніть увагу, що пароль користувача ми не передаємо у відкритому вигляді, ми передаємо лише його MD5-відбиток. Алгоритм отримання MD5-відбитку є стандартним і широко відомим. Скоріш за все знайдете або зразок коду, або готову бібліотеку.

Замість методу /api/v1/AccountingSystem/SendReplication можна використати аналогічний метод /api/v1/AccountingSystem/SendReplicationZip, за яким можна відправити контейнер репліакації, стиснутий GZIP-алгоритмом. Для цього берем json контейнера реплікації, стискаємо його за GZIP алгоритмом та формуємо з отриманого масиву байтів Base64 рядок. Цей рядок передаємо методом POST. Рядок обов'язково повинен бути обгорнутий подвійними лапками.

У разі успішної реплікації ми можемо побачити довідник товарів на касовому сервері в кабінеті користувача за цим посиланням. Товарні залишки по торгових точках за цим посиланням. Перелік касирів та інші довідники. 

Каси відправляють до касового сервера чеки, повернення, замовлення покупців та інші документи у вигляді контейнерів документів (не плутати з контейнерами реплікації). Контейнер документів може вміщувати один документ, наприклад, замовлення покупця, або декілька пов'язаних між собою. Наприклад, чек, який вміщує видаткову накладну на покупця та прибутковий касовий ордер, як оплату за товар від покупця). Більш детально про контейнер документів можна почитати за посиланням.

Наше завдання - імпортувати документи, що надходять з кас, до облікової системи.

Типовий алгоритм знову ж таки повинен задіяти періодичну реплікацію, але вже в протилежний бік - треба імпортувати нові документи з касового сервера до облікової системи. Розпишемо оптимальну поведінку.

1. В обліковій системі нам потрібно мати змінну, яка зберігає максимальний Id контейнера документів, який був отриманий під час останньої успішної реплікації. Початкове значення буде 0, тип даних long (він же bigint, він же Int64, тобто ціле, 8 байтів).

2. Імпортуємо певну кількість контейнерів документів, наприклад, 128 штук. Варто зауважити, що це ми запитаємо максимальну кількість для отримання, в сервера може стільки і не бути, і сервер поверне, наприклад, 5 контейнерів, але не більше 128. Для цього скористаємось методом API /api/v1/AccountingSystem/DownloadContainers

Нам треба передати ряд параметрів
formId - це Id останнього контейнера, який був отриманий в попередньому сеансі реплікації (описаний в пункті 1 алгоритму).

recordCount - маскимальна кількість контейнерів, які хочемо отримати

appVersion - назва та версія облікової системи, яка зробила запит. Обов'язково вказуйте, вона журналізується, і в розділі сеансів будете бачити, який контейнер коли і якою системою був імпортований.

Accept-Language - параметр, що передається в розділі Headers http-запиту, для визначення мови, в якій бажаєте отримувати повідомлення про виключну ситуацію. Можна ігнорувати.

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

4. Коли ми обробили контейнер документів, бажано відправити до касового сервер звіт про таку обробку за допомогою метода /api/v1/AccountingSystem/SendApproveResult. Таким чином касовий сервер отримає звіт від облікової системи про результат проведення конкретного контейнера документів.

5. Серед пакету імпортованих контейнерів знаходимо контейнер з максимальним ContainerId та запам'ятаємо значення в змінній (див. пункт 1).

6. Через певний проміжок часу, наприклад, 5 хвилин, знову запускаємо цикл реплікації, починаючи з першого пункту.

Для цього використовується веб-метод /api/v1/Bridge/SendFiles.

Через цей метод потрібно відправити колекцію документів, які накопичились з моменту минулого сеансу. Формат контейнера документів можна подивитись тут. На касових робочих місцях є певна специфіка. Інтернет може бути не завжди стабільним. Тому проведені касиром документи зберігаються у вигляді zip-файлів, а окремий незалежний процес періодично опитує теку зберігання і відправляє на касовий сервер накопичені файли у вигляді колекції. Назви та сенс полів описані та зрозумілі, тому не будемо повторюватись. Варто зупинитись на полі Content. Кожен контейнер документів є нормальним звичайним zip-архівом. Тому в поле Content нашого об'єкта зберігаємо масив байтів прочитаного файлу. Далі, серіалізуємо колекцію об'єктів (навіть якщо в колекції один об'єкт), наприклад, за допомогою NewtonSoft Json, і відправляємо на касовий сервер.

Документи, що були відправлені на касовий сервер, можна подивитись за посиланням.