¶ Загальна інформація
При підключенні кас до хмарних облікових чи CRM систем виникає потреба в підключенні фізичних пристроїв, а саме чекодруків і терміналів для того щоб друкувати чеки та інші документи та проводити оплати по терміналу з додаванням всіх необхідних, за вимогами законодавства, даних про оплату.
Device Manager (далі ДМ) дозволяє в рамках одного застосунку фіскалізовувати чеки та керувати принтером і терміналом. Проте не всі хмарні системи можуть просто підключитись до локального застосунку який встановлено на пристрої клієнта.
У зв'язку з цим у Вчасно.Каса є рішення яке має на меті значно спростити налаштування і процес роботи хмарних систем з касами і іншими POS пристроями.
¶ Опис самої схеми роботи
Як виглядає поточна схема якщо використовувати ДМ для роботи з усіма пристроями:
Пояснення до схеми:
З облікової системи відправляється API запит, наприклад на фіскалізацію чеку, на локально встановлений ДМ. В застосунку виконуються перевірки коректності запиту, далі якщо передана оплата картою - відправляється запит на підключений термінал для оплати. Після завершення оплати відбувається фіскалізація чеку. По завершенню фіскалізації чек друкується на принтері та передається відповідь на API запит до облікової системи. В разі оплати готівкою відбувається лише фіскалізація чеку та його друк без залучення терміналу.
Як виглядає нова схема:
Пояснення до схеми:
В даному випадку API запит відправляється, наприклад на фіскалізацію чеку, на сервер Вчасно.Каса який тримає постійне підключення з ДМ та може ним керувати. З серверу запит передається на ДМ який в свою чергу виконує оплату на терміналі (якщо в чеку оплата картою), фіскалізацію чеку та його друк як описано вище.
¶ Переваги і можливості
Ключова різниця полягає в тому що:
- Облікова система може відправляти запити на сервер Вчасно.Каса без необхідності відкривати доступ до ПК клієнта "в світ".
- Не потрібно локально підключати SSL сертифікат в ДМ для роботи API по HTTPS, так як при роботі з Вчасно.Каса використовується обов'язково лише HTTPS.
- Клієнт може мати повноцінне робоче місце з ПРРО, принтером і терміналом при цьому не ускладнюючи процес налаштування і роботи.
- Спрощується процес першого налаштування для початку роботи.
Додатково нова схема відкриває можливість використовувати Android термінали 3в1 замість ПК, принтеру і терміналу.
В такому випадку android термінал заміняє собою принтер і термінал як окремі пристрої, також фіскалізує чеки, а клієнт має можливість відправляти чеки на фіскалізацію з будь якого місця з якого буде доступ до облікової системи.
ПРРО, терміналом, принтером, за потреби, можна керувати окремо, тобто окремо провести чек, окремо надрукувати чек чи якусь іншу інформацію, окремо виконати оплату на термінали чи оформити оплату частинами наприклад.
Навіть якщо уже є інтеграція з Вчасно.Каса по поточній схемі перехід на нову не займе багато часу так як структура API запиту та відповідей схожа.
Які є "нюанси":
- Схема вимагає стабільного інтернет з'єднання, що при роботі з хмарними системами не має викликати проблем, проте в разі розривів зв'язку із за нестабільного інтернет підключення можливі затримки в передачі даних на ДМ та в отриманні відповіді.
¶ Які кроки до початку роботи
Даний функціонал знаходиться на етапі beta тестування. За доступами для тестування, з пропозиціями по покращенню, питаннями та проблемами під час роботи по даній схемі можна звернутись до служби турботи Вчасно.Каса.
-
Першим етапом є реєстрація або виконання входу до кабінету Вчасно.Каса.
-
Наступним етапом є реєстрація або додавання уже зареєстрованої в ДПС торгової точки, каси, та ключа ЕЦП касира або печатки для роботи з ПРРО.
-
Виконується встановлення Device Manager на пристрій до якого буде підключено термінал та/або принтер.
У разі використання Android терміналу 3в1 процес встановлення буде відрізнятись залежно від банку та моделі терміналу, тому встановлення застосунку може бути виконане як з боку банку так і з боку постачальника/виробника терміналу. -
Після встановлення потрібно з'єднати Device Manager з кабінетом Вчасно.Каса, Для цього виконуєте дії описані в розділі: Підключення застосунків.
-
Після з'єднання біля Device Manager на сторінці
Адміністрування DMможна буде отримати його API токен. Цей токен буде використовуватись як авторизація для всіх запитів на Device Manager.
-
Подальший процес налаштування ПРРО, терміналу та принтеру може відрізнятись:
-
Налаштувати всі потрібні для роботи пристрої безпосередньо через інтерфейс Device Manager по інструкціям.
Налаштування ПРРО
Налаштування терміналу
Налаштування принтеру -
Підключити доступ до керування Device Manager для облікової програми. В такому разі облікова програма зможе виконати всі налаштування (створити ПРРО, термінал та принтер) через API, проте для цього потрібно щоб облікова програма мала реалізацію API не тільки для роботи, але й для налаштування яке доступне в Device Manager.
- Після завершення налаштування та підключення необхідних пристроїв можна починати роботу
Готово
¶ Налаштування на Android терміналі 3в1
Можливість використовувати android термінали буде доступна після 23.09. Інформацію щодо налаштування буде доповнено.
У випадку використання Android терміналу 3в1 Device Manager може бути встановлений з боку банку чи вендору та підтримує такі моделі терміналів:
- Castles Saturn 1000
- Verifone X990
Додатково згодом буде додана підтримка наступних моделей:
- Ingenico Axium DX8000
- Ingenico Axium DX4000
- Ingenico APOS A8
- Pax A910
- Tactillion P2000L
¶ API для керування ДМ
При роботі по даній схемі доступні абсолютно всі API методи Device Manager без виключення для роботи з ПРРО, принтерами та терміналами та для керування/налаштування самого Device Manager.
Додатково з'являється авторизація для доступу до Device Manager та "обгортка" навколо API DM.
Звертаємо увагу якщо в налаштуваннях застосунку увімкнено Використовувати автентифікацію для доступу до вебінтерфейсу дану схему роботи це не блокує, так як дана схема має власну авторизацію, інформація про яку подана в наступному підпункті.
Тобто при увімкненому налаштуванні, локально, доступ до інтерфейсу застосунку буде тільки через введення логіну та паролю, в той час як виконання всіх методів буде працювати без необхідності реалізації додатково логіки авторизації по логіну і паролю або через передачу x-api-key.
¶ Авторизація
Авторизація обов'язкова для всіх запитів на ДМ і здійснюється за допомогою передачі токена в значенні ключа X-AP-DM-PROXY-TOKEN в headers до запиту.
Даний токен можна отримати в кабінеті Вчасно.Каса на сторінці Адміністрування DM біля потрібного ДМ.
Згенерувати токен буде неможливо якщо у вас використовується версія DM нижче за 6.3.4, тому рекомендовано оновити версію до останньої.
Звертаємо увагу що токен прив'язаний до інсталяції ДМ. У випадку якщо пристрій, на якому встановлено ДМ вийшлов з ладу, виконано перенесення підключення ПРРО, терміналу та принтеру на інший пристрій без перенесення бази даних застосунку або виконано перевстановлення ДМ на Android пристрої зміниться токен і ДМ перестане бути доступним.
У випадку якщо ви перевстановлюєте ДМ на тому ж пристрої без видалення бази даних на Windows або Linux - токен залишається незмінним.
Для того щоб мати доступ до керування новим Device Manager потрібно буде виконати 3 кроки:
- Повторне з'єднання Device Manager з кабінетом Вчасно.Каса, Для цього виконуєте дії описані в розділі: Підключення застосунків.
- Повторне отримання API токену на сторінці
Адміністрування DM. - Заміна API токену на новий в обліковій програмі.
¶ Структура запитів
Method: POST
Host: https://kasa.vchasno.ua
Headers: Content-Type: application/json, X-AP-DM-PROXY-TOKEN: token
Endpoint: /ws/ap/dm-proxy
Body: JSON
Структура JSON body запиту:
| Ключ | Тип json даних | Зміст | Обов'язковий |
|---|---|---|---|
| method | string | Тип HTTP методу згідно потрібного запиту вказаного в url. Доступні значення: GET, POST, DELETE | + |
| url | string | Ендпоінт із доступних згідно опису API ДМ. В значення url також можна передавати query параметри до запиту, наприклад: /dm/execute-prn?dev_id=printer | + |
| headers | object | Headers для запиту вказаного в url. | - |
| body | object | Body для запиту вказаного в url. Для GET/DELETE не потрібно. | - |
Для більшого розуміння зробимо порівняння на прикладі запиту на відкриття зміни по ПРРО.
- При роботі напряму з API Device Manager повний запит виглядатиме наступним чином
curl --location --globoff 'http://localhost:3939/dm/execute' \
--header 'Content-Type: application/json' \
--data '{
"ver": 6,
"source": "API",
"device": "Магазин кафе",
"tag": "",
"type": 1,
"fiscal": {
"task": 0
}
}'
- При керуванні Device Manager через хмару Вчасно.Каса, цей же запит виглядатиме наступним чином:
curl --location 'https://kasa.vchasno.ua/ws/ap/dm-proxy' \
--header 'Content-Type: application/json' \
--header 'X-AP-DM-PROXY-TOKEN: token' \
--data '{
"method": "POST",
"url": "/dm/execute",
"body": {
"ver": 6,
"source": "API",
"device": "Магазин кафе",
"tag": "",
"type": 1,
"fiscal": {
"task": 0
}
}
}'
¶ Структура відповідей та робота з помилками
HTTP статуси:
200 - Повертається якщо запит був оброблений на стороні ДМ і доставлена відповідь.
400 - Повертається у випадках якщо в запиті відсутні обов'язкові поля, або отримано невірний формат JSON. Також повертається якщо відбувся таймаут запиту до ДМ, немає підключення до нього або запит було скасовано.
401 - Повертається у випадку якщо не було в headers до запиту передано ключа X-AP-DM-PROXY-TOKEN або значення токену недійсне/некоректне.
Зверніть увагу що статус HTTP 200 не означає що, наприклад, запит на фіскалізацію чеку виконано успішно, це означає лише успішну обробку інформації на стороні Device Manager і доставку відповіді.
Інформацію щодо розбору відповіді від ДМ можна знайти тут.
Якщо зв'язок з ДМ наявний - всі дані в body відповіді на запит будуть ідентичні відповідям як при роботі через API ДМ напряму.
Детальніше які дані повертаються у body відповіді дивіться в описі API.
У разі якщо є проблеми зі зв'язком, body відповіді буде мати наступний вигляд:
- ДМ недоступний на момент відправки запиту.
{
"reason": "Відсутнє підключення до DeviceManager",
"details": "",
"code": 1041
}
- З ДМ втрачено зв'язок в процесі виконання операції. Тобто на момент початку виконання операції зв'язок був, але його було втрачено.
{
"reason": "Таймаут при передачі запиту до DeviceManager",
"details": "",
"code": 1041
}
- З ДМ розірвано зв'язок в процесі виконання операції. В такому випадку рекомендовано зробити повтор останнього запиту.
{
"reason": "Скасовано обробку запиту до DeviceManager",
"details": "",
"code": 1041
}
В якому випадку можуть виникнути проблеми зі зв'язком з Device Manager:
- Пристрій на якому встановлено ДМ вимкнуто або застосунок було закрито (при роботі на Android).
- На пристрої на якому встановлено ДМ відсутнє інтернет з'єднання.
- З пристрою на якому встановлено ДМ блокується доступ до хмари Вчасно.Каса (kasa.vchasno.ua). Блокування може бути на стороні антивірусу, брандмауера як системного так і власного (за наявності такого), VPN, провайдера інтернету.
- З ДМ розірвано зв'язок через оновлення з боку хмари Вчасно.Каса. В такому випадку рекомендовано зробити повтор останнього запиту на ДМ.
¶ Рекомендації для стабільної роботи
Для стабільної роботи транзакційний режим обов'язковий до реалізації. Його реалізація забезпечує точне співпадіння даних в Device Manager та в касовій/обліковій програмі в разі будь яких проблем з отриманням відповіді на відправлений запит.
У разі роботи ПРРО разом з терміналом та/або принтером в пакетному режимі використовується лише "Транзакційний режим при роботі з ПРРО".
В разі роботи окремо (окремий запит на термінал, на ПРРО та на друк) необхідно виконати окремі реалізації транзакційного режиму для роботи з ПРРО та терміналом.
Для запитів на принтер (друк або відкриття грошового ящику) транзакційний режим не підтримується. Тому в разі неотримання відповіді рекомендовано виконувати друк повторно або запитувати у користувача касової/облікової програми чи потрібно виконати друк.
¶ Додаткова інформація
- В разі перебоїв в мережі інтернет під час роботи, Device Manager буде самостійно перепідключатись, для цього ніяких додаткових дій чи запитів виконувати не потрібно. Те ж саме стосується щоденного вимкнення пристрою. Орієнтовно через 60 секунд після увімкнення пристрою на якому встановлено ДМ буде виконано підключення до хмари Вчасно.Каса.
В разі відсутності мережі тривалий час, ДМ буде орієнтовно кожні 60 секунд перевіряти наявність мережі і, за її наявності, виконає підключення і знову стане доступний для керування.