Інструкція розробника Cashdesk api

Інструкція розробника

• Базовий опис
• Режими роботи
• Режими фіскалізації чеків
• Види АPІ за обсягом реалізації функцій
• Способи підписання
• Сервера API
• Авторизація в API

Базовий опис

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

Повний опис

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

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

1. Онлайн

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

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

2. Офлайн

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

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

Чеки/документи одразу підписуються та відправляються до податкової. У разі відсутності підпису видається помилка. У разі відсутності зв'язку з податковою видається помилка. Можливий перехід в режим офлайн, при використанні SmartConnect.

Ідеально підходить для заміни класичних РРО.

У цьому режимі обов'язково необхідний модуль підпису Smart Sign - web або десктоп версії.

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

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

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

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

Користувач (касир) у браузері на будь-якому пристрої відкриває закладку.

Авторизується ключем/токеном КЕП/ЕЦП або через хмарне сховище. І залишає вкладку у браузері відкритою.

Після цього підписання відбувається у вікні браузера в автоматі, без відволікання користувача від робочого процесу.

Наприкінці робочого дня/зміни користувач просто закриває закладку в браузері.

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

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

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

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

Сервера API

1. Web сервер – робочий

Цей сервер є основним для онлайн та офлайн роботи.

Підключено робочий фіскальний сервер податкової.

Робота реальними ключами КЕП та справжня фіскалізація чеків.

2. Web сервер – тестовий

Тестовий сервер, версія коду release candidate.

Підключено тестовий сервер податкової.

Робота реальними ключами КЕП – але формуватимуться тестові чеки у податковій.

Приклад

3. Десктопний сервер

Такий веб-сервер встановлюється у вигляді десктопної програми. Інсталятор та інструкції користувача можна взяти на веб-кабінеті CashDesk. Встановлюється на localhost. Установки порту виконуються в програмі. API відповідає онлайн API в основній документації. Є робоча версія і для цілей розробки.

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

Два варіанти – на вибір.

1. API ключ

Ключ можна отримати в особистому кабінеті CashDesk.

API ключ видається під кожного користувача індивідуально.

Ключ необхідно передавати POST змінною api_token у кожному запиті.

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

Тимчасовий токен видається в результаті виконання API запиту URI: /api/v2/authenticate

Авторизація робиться за логіном та паролем, який сформував користувач при реєстрації.

Цей токен необхідно надсилати в заголовку (header)

Формат:

Authorization: Bearer