Про Cashdesk API

Базовий опис

API реалізовано у вигляді REST запитів, обмін у форматі JSON.

Запити можна робити як на онлайн сервер - так і на локальний веб-сервер (десктопний додаток).

Режими роботи

Онлайн

Коли система користувача завжди буде знаходитися онлайн і сервер CashDesk завжди доступний.

Ідеально підходить для дрібного бізнесу, де мала кількість транзакцій та швидкість/можливість пробити чек “прямо зараз” відсутня. Підходить для інтернет продаж, коли завжди доступний інтернет, або коли можна робити відкладені чеки.

Офлайн

Коли важлива безперебійна робота касового обладнання, коли висока інтенсивність чеків та затримка пробивання чека критична. Необхідне встановлення модуля SmartConnect.

Режими фіскалізації чеків

Онлайн

• Чеки одразу підписуються та відправляються до податкової
• У разі відсутності підпису видається помилка
• У разі відсутності зв'язку з податковою видається помилка

Офлайн

• При використанні SmartConnect можлива фіскалізація чеків в офлайн режимі
• У цьому режимі обов'язково необхідний модуль підпису Smart Sign

Види інтеграції API за обсягом реалізації функцій

1. Повноцінний онлайн/офлайн режим. Клієнт самостійно реалізовує необхідний набір функцій, сам стежить за переходом онлайн/офлайн. Тільки через взаємодію з онлайн-сервером. Найскладніший варіант.
2. Онлайн API/десктопний сервер. Всю логіку онлайн/офлайн перебирає десктопний додаток - локальний веб сервер. Розробнику необхідно реалізувати лише онлайн функції фіскалізації. Рекомендований варіант.
3. Мінімальний варіант. Підходить для онлайн систем/магазинів/СРМ - там де формуються чеки (або інші типи документів) через онлайн системи. А ключові бухгалтерські/касові операції виконуються у веб-кабінеті CashDesk (закриття зміни або відкладені чеки). Розробник сам вирішує які типи документів необхідно реалізувати.

Способи підписання

1. Web модуль підпису Smart Sign

   • Користувач (касир) у браузері на будь-якому пристрої відкриває сторінку https://sign.smart-era.ua/
   • Авторизується ключем/токеном КЕП/ЕЦП або через хмарне сховище і залишає вкладку у браузері відкритою
   • Після цього підписання відбувається у вікні браузера автоматично, без відволікання користувача від робочого процесу
   • Наприкінці робочого дня/зміни користувач просто закриває сторінку в браузері

   Для роботи з тестовим сервером необхідно використовувати тестовий сервер модуля підпису

2. Десктопний модуль підпису (Рекомендований)

   • Модуль завантажується з веб-кабінету CashDesk
   • Встановлюється на комп'ютері, де є доступ до ключів користувача
   • Виконується налаштування та активація ключів (інструкція користувача)
   • Після цього програма відпрацьовує запити на підпис для зазначених власників ключів
   • Деактивація кожного ключа відбувається користувачем індивідуально наприкінці дня/зміни

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

Сервера API

1. https://api.cashdesk.com.ua – робочий

   • Цей сервер є основним для онлайн та офлайн роботи
   • Підключено робочий фіскальний сервер податкової
   • Робота реальними ключами КЕП та справжня фіскалізація чеків
   Приклад продового чека

   

2. https://test.cashdesk.com.ua – тестовий

   • Тестовий сервер, версія коду release candidate
   • Підключено тестовий сервер податкової
   • Робота реальними ключами КЕП - але формуватимуться тестові чеки в податковій
   Приклад тестового чека

   

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

3. Тестовий веб-сервер для локального запуску API

   • Даний веб-сервер встановлюється у вигляді десктопної програми
   • Інсталятор та інструкції користувача можна взяти в веб-кабінеті CashDesk
   • Сервер встановлюється на localhost
   • Налаштування порта виконуються у додатку
   • Даний локальний веб-сервер працює аналогічно онлайн версії API

Авторизація в API

Для роботи з API необхідно в кожному запиті передавати API ключ, який має два варіанти:

1. Тимчасовий API токен (OAuth)

   • Тимчасовий токен видається в результаті виконання API запиту URI: /api/v2/authenticate
   • Авторизація виконується з логіном та паролем, який сформував користувач під час реєстрації
   • Після кожної авторизації видається новий токен
   • Токен необхідно надсилати в заголовку (header)
   • Формат: Authorization: Bearer

2. Постійний API ключ

   • Ключ можна згенерувати в особистому кабінеті CashDesk
   • API ключ видається під кожного користувача індивідуально
   • Ключ необхідно передавати POST змінною api_token в тілі кожного запиту

Заголовки

• До кожного запиту потрібно додати заголовок developer-id вказавши назву вашої платформи, компанії тощо (у випадку відсутності заголовка буде відбуватися блокування запиту)
• Кожен запит повинен містити заголовок Accept: application/json
• Кожен запит повинен містити заголовок Content-Type: application/json
• У випадку використання передачі даних як application/x-www-form-urlencoded, значення які повинні бути TRUE/FALSE слід передавати як 1/0 відповідно!
• Заголовок Shift-state у відповідь на кожен запит який містить num_fiscal має значення true/false, що відповідає відкритій/закритій зміні на момент відповіді

tip

Postman колекція (Онлайн каса): https://documenter.getpostman.com/view/12128952/TVRj5U1d
Postman колекція (Обмін валюти): https://documenter.getpostman.com/view/12128952/TWDanvq5