Перейти до основного вмісту

Опис роботи API

Службові операції з ПРРО через API​

Використання всіх методів API відбувається без функції підписання. Для підписання чеків (використання КЕП) потрібно встановити додаток SmartSign і налаштувати декілька методів API.

Увага

Для роботи з API необхідно в кожному запиті передавати токен авторизації та заголовки.
В методі /authenticate передавати токен авторизації не потрібно.

  1. На початку зміни для автентифікації за логіном і паролем від CashDesk виконується метод POST /authenticate. У разі вдалої автентифікації відповідь буде містити тимчасовий токен авторизації token.

  2. Для отримання списку доступних РРО виконується метод POST /tax_objects. Відповідь буде включати детальну інформацію про доступні РРО.

  3. Для отримання останнього зареєстрованого чека з сервера ДПС необхідно виконати метод POST /shift/lastCheck. Якщо використовується SmartConnect, то у відповіді буде останній фіскальний чек (поле local_number матиме дані) або службовий чек (поле local_number буде зі значенням null). У випадку якщо у зміні не було операцій, то всі поля матимуть значення null.

  4. Для проведення операцій з касою необхідно відкрити зміну. Для відкриття зміни виконується метод POST /shift.
    В параметрі запиту action_type необхідно передати значення OPEN_SHIFT

  5. Необхідно повідомляти ДПС що РРО на зв'язку. Для цього необхідно виконати метод POST /shift/ping. Якщо не виконувати запит щонайменше 1 раз на 30 хвилин, то ДПС може автоматично перевести РРО в офлайн режим і в подальшому заблокувати його.

    ⚠️ Тільки для використання API без взаємодії зі SmartConnect

  6. Для отримання статусу РРО виконується метод GET /tax_objects. Відповідь буде включати детальну інформацію про обраний РРО.

  7. Реалізація товару виконується за допомогою метода POST /check/sale. Для реалізації товару, в параметрі запиту action_type необхідно передати значення Z_SALE, а для повернення - RETURN.

  8. Відправка чека покупцю виконується за допомогою метода POST /check/send-to-customer. Метод дозволяє надіслати чек клієнту через СМС, Email або Viber, що вказується в параметрі запиту action_type (SMS — надіслати чек через СМС, EMAIL — надіслати чек по Email, VIBER — надіслати чек через Viber).

  9. Для отримання PDF представлення чека виконується метод GET /checks/:id/pdf.

  10. Для отримання текстового представлення чека виконується метод GET /checks/:id/text.

  11. Для отримання JSON представлення чека виконується метод GET /checks/:id/json.

  12. Отримати QR кода чека реалізації та повернення виконується метод GET /checks/:id/qr.

  13. Для отримання Х-звіту виконується метод POST /shift/xReport. У випадку якщо зміна не відкрита, звіт буде згенеровано з нульовими значеннями.

  14. Для закриття зміни та формування Z-звіту виконується метод POST /shift. В параметрі запиту action_type необхідно передати значення Z_REPORT.

Робота з модулем SmartSign через API​

SmartSign — це ключовий компонент для електронного підписання чеків. Він отримує запит на підпис через API, підписує його вашим електронним ключем, а потім відправляє готовий чек на сервер CashDesk для передачі до ДПС.

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

Робота з модулем SmartConnect через API​

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

Модуль SmartConnect підтримує ті самі методи, що й CashDesk.

Як налаштувати роботу з API:

  1. Ваше програмне забезпечення, що надсилає запити (наприклад, 1С), має знаходитись в тій самій локальній мережі, що й SmartConnect.

  2. Для тестового середовища використовуйте адресу http://localhost:8000/, а для робочого — http://localhost:8001/. Якщо SmartConnect і ваше ПЗ встановлені на різних комп'ютерах, замість localhost потрібно вказати IP-адресу комп'ютера, де інстальовано SmartConnect.

  3. Для авторизації зі SmartConnect використовується API-ключ (токен), згенерований в особистому кабінеті CashDesk і прив'язаний до касира. SmartConnect передає цей токен із чеком на сервер, який потім використовує його для пошуку активного модуля SmartSign для підпису.