Про Cashdesk API

Базовий опис

інформація

API — спосіб, яким ваша система програмно обмінюється даними з CashDesk.

Endpoint / URI — адреса конкретного методу API (наприклад, /authenticate чи /check/sale).

JSON — формат даних для тіла запиту та відповіді.

API-токен — ключ авторизації, який підтверджує права доступу до методів API.

Повний глосарій термінів

API реалізовано REST, обмін - у форматі JSON.

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

Мінімальна кількість 7 методів API:

Авторизація

• /authenticate — Отримати токен.

Зміна

• /shift — Відкрити / Закрити зміну (Z-звіт)
• /shift/xReport — Отримати X-звіт
• /shift/lastCheck — Отримати останній чек.

Чеки

• /check/sale — Реалізація / Повернення
• /check/service — Службове внесення / Службова видача
• /checks/:id/text — Отримати представлення чека

Якщо не використовується SmartConnect, то необхідно також інтегрувати метод /shift/ping — повідомлення ДПС що ПРРО на зв'язку.

Детальніше про роботу API, використання всіх методів описано на сторінці Опис роботи API

Режими роботи та фіскалізації

Онлайн-режим

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

У цьому режимі чеки одразу підписуються та відправляються до податкової.

• Якщо електронний підпис відсутній, використайте SmartSign для підписання чека.
• У разі нестабільного зв'язку, необхідно встановити модуль SmartConnect.

Офлайн

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

Для роботи в офлайн-режимі обов'язково потрібно встановити модуль SmartConnect. При використанні SmartConnect можлива фіскалізація чеків в офлайн режимі. SmartConnect дозволяє пробивати чеки навіть при відсутності інтернет-з'єднання. Чеки накопичуються локально і відправляються в ДПС, як тільки інтернет-зв'язок відновлюється.

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

1. Повноцінний онлайн / офлайн режим

Клієнт самостійно реалізовує необхідний набір функцій, сам стежить за переходом онлайн / офлайн. Тільки через взаємодію з онлайн-сервером. Найскладніший варіант.

2. Онлайн API / десктопний сервер

Всю логіку онлайн / офлайн перебирає десктопний додаток — локальний веб сервер. Розробнику необхідно реалізувати лише онлайн функції фіскалізації. Рекомендований варіант.

3. Мінімальний варіант

Підходить для онлайн систем / магазинів / СРМ — там де формуються чеки (або інші типи документів) через онлайн системи. А ключові бухгалтерські / касові операції виконуються у веб-кабінеті CashDesk (закриття зміни або відкладені чеки). Розробник сам вирішує які типи документів необхідно реалізувати.

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

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

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

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

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

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

Сервера 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 в тілі кожного запиту

порада

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

Потрібно більше пояснень?

Перегляньте глосарій термінів CashDesk, де простими словами пояснені основні терміни.