Checkbox – сервіс програмної реєстрації розрахункових операцій (далі - ПРРО).
Цей документ описує частину аспектів підключення сервісу ПРРО Checkbox для eCommerce порталу або будь-якого іншого додатку, що потребує реалізації функції реєстрації розрахункових операцій (фіскалізації) у вигляді відкритого RESTful API.
Сервіс складається з особистого кабінету, транзакційного процесингу, агентів підпису та фронт-агентів.
Через особистий кабінет виконується реєстрація торговця в системі і управління його точками продажу, касами та касирами.
Транзакційний процессинг забезпечує взаємодію із ДПС, взаємодію із агентами підпису та реалізує API інтерфейс для роботи фронт-агентів через які кінцевий користувач і створює чеки.
Фронт-агентами можуть бути:
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції. З повним переліком методів (без деталізованого опису) ви зможете ознайомитись за посиланнями Swagger та ReDoc.
Із загальною схемою архітектури сервісу ви можете ознайомитись за посиланням.
OPENEDOPENING - будь ласка, зв'яжіться із службою підтримки checkboxDONECANCELLED або ERROR, перевірити причину та усунутиCREATED - будь ласка, зв'яжіться із службою підтримки checkboxDONE)Також радимо ознайомитись із графічною схемою, яка показує принципи, по яким можна побудувати АПІ інтеграцію. Можливо, вона також допоможе розібратися з питаннями, в якості доповнення до цієї документації.
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та можливо платити штраф.
*.checkbox.ua*.checkbox.in.uae1.o.lencr.orge1.i.lencr.orgocsp.pki.googpki.googХост: https://api.checkbox.ua - єдина адреса (для тестування та фіскальної роботи).
Порт: 443
Тестування - використовуються дані тестового касира та каси з сайту Checkbox (див. Тестування)
Фіскальні дані - для фіскальної роботи використовуються дані бойового касира та каси. (для цього потрібно в ДПС зареєструвати касу та касира - див. Реєстарція)
Будь-який HTTPS-запит починається зі строки METHOD URI, де METHOD — це метод доступу (GET, PUT и т.д.), а URI — адреса запитуваного ресурсу (https://api.checkbox.ua).
З початку запиту йдуть заголовки - текстові рядки виду key: value. Після передається пустий рядок, який означає кінець секції заголовків, після цього - тіло запиту (якщо воно вимагається).
У відповідь прийде рядок з версією HTTPS, кодом та рядковим статусом відповіді, далі - тестові заголовки, пустий рядок, потім тіло відповіді. Кодування для всіх запитів і відповідей — тільки UTF-8. Усі дані, окрім URI та двійкових файлів передаються в форматі JSON. Для рядків використовуються тільки подвійні лапки.
У відповідях 2хх з не пустим тілом та при запиті з тілом обов'язково має бути заголовок:
Content-Type: application/json
Інші можливі заголовки:
Authorization: Bearer <токен авторизації>
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-Access-Key: <ключ доступу інтеграції (не використовується зараз)>
X-Device-ID: <ID RRO Agent або мобільного пристрою каси (не використовується для API інтеграцій)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Додаткові параметри вибірки для спискових запитів (фільтрація, сортування, паджинація і тд.), форматуються за правилами HTTPS параметрів params opt.
Якщо успішно, сервер повертає 200 ОК з полями об'єкта в форматі JSON в тілі відповіді (без додаткового оберту в будь-який об'єкт). У випадку, якщо об'єкта із таким UUID не існує, сервер поверне відповідь 404 Not Found.
Якщо успішно, сервер поверне 2хх ОК з масивом об'єкта в форматі JSON в тілі відповіді (тобто починається з [ і закінчується ] ). Якщо масив вийшов пустим, все одно повертається 2хх ОК з пустим масивом в тілі відповіді.
У тілі запиту мають бути перелічені поля об'єкта в форматі JSON без додаткового оберту (тобто {"field1":"value","field2":10}). У випадку успіху сервер має повернути 2хх Created з тілом, аналогічним запиту getByID, з усіма полями зміненого об'єкта.
У запиті мають бути перелічені тільки поля, які мають бути змінені. У випадку успіху сервер поверне 2хх ОК з тілом, аналогічним запиту getByID, з усіма полями зміненого об'єкта.
У випадку успіху повертає 2хх No Data з порожнім тілом, так як повертати немає чого.
Експрес-накладні в системі checkbox - це проект фіскального чека, який повʼязаний із накладною Нової Пошти та буде фіскалізовано автоматично після отримання покупцем посилки.
❗️ Важливо: щоб опція створення проектів експрес-накладних стала доступною, спершу активуйте її у вашому особистому кабінеті checkbox за інструкцією.
❗️ Увага: дані методи API checkbox - не створюють саму ТТН в Новій Пошті. Продавцю необхідно створити окремо або через бізнес-кабінет, або на відділені саму ТТН (ІЗ КОНТРОЛЕМ ОПЛАТИ В ОБОХ ВИПАДКАХ) і після цього вже створювати проект експрес-накладної в системі checkbox.
ТЕСТОВИХ ДАНИХ - НЕ ІСНУЄ.
ПІДКЛЮЧИТИ ТОКЕН НОВОЇ ПОШТИ МОЖЛИВО ТІЛЬКИ НА БОЙОВУ (РЕАЛЬНУ) ФІСКАЛЬНУ КАСУ.
ТЕСТУВАННЯ МОЖЛИВЕ ТІЛЬКИ НА РЕАЛЬНІЙ ФІСКАЛЬНІЙ КАСІ ІЗ РЕАЛЬНОЮ НАКЛАДНОЮ НОВОЇ ПОШТИ.
Розробник інтеграції може або використовувати методи інтеграції checkbox, або може самостійно реалізувати інтеграцію з НП, і вже до checkbox відправляти фіскальний чек після отримання посилки покупцем. Схема роботи при самостійній інтеграціх має виглядати так:
Звіти, які доступні в особистому кабінеті checkbox - частково доступні в глобальному API. Наразі доступні наступні звіти:
Розділ Товарів особистого кабінету також частково доступний по API. Методами API доступне:
Замовлення в системі checkbox - це проект фіскального чека, який необхідно фіскалізувати курʼєру після доставки замовлення покупцеві та його оплати.
Розділ замовлень доступний лише в мобільному додатку checkbox на android та після увімкнення відповідного функціоналу для касира службою технічної підтримки checkbox.
Після увімкнення відповідного функціоналу в мобільному додатку буде доступний розділ Замовлення бокового меню, де відбувається робота із створеними по REST API із зовнішньої системи замовленнями.
Щоб отримувати оновлення в режимі реального часу про сутності (зміни та фіскальні чеки), вам слід правильно налаштувати webhook. У цій інструкції наведено основні методи роботи з webhook.
| Responce body 🖥️ | Description ✍🏻 | ||
|---|---|---|---|
| 200 | { |
Якщо серед останніх 10 відправлених транзакцій 6 - це запити на офлайн коди, то спрацює автоматичне блокування | |
| 400 | CheckBox Підпис неактивний, запустіть його, будь ласка | Якщо підпис касира не запущений, то ви отримаєте помилку 400. Ви можете використовувати його на захищеному хмарному сервісі, або встановити локально. | |
| 400 | Каса вже в режимі оффлайн | Якщо ви виконаєте запит на перехід в офлайн режим, а каса вже знаходиться в офлайн режимі на момент отримання запиту сервером - ви отримаєте помилку 400 | |
| 400 | Codes can be asked only if cash register is online! | Якщо ви спробуєте виконати запит на отримання нових офлайн кодів від ДПС методом /api/v1/cash-registers/ask-offline-codes, але каса знаходиться в офлайн режимі, ви отримаєте помилку 400 | |
| 400 | { |
Якщо ви спробуєте виконати запит перевірки зв'язку із ДПС методом /api/v1/cash-registers/ping-tax-service, але увімкнено загальний офлайн режим - ви отримаєте помилку 400 | |
| 400 | Вказана дата транзакції <YYYY-MM-DD> не може бути меншою, ніж дата створення останньої транзакції <YYYY-MM-DD> |
Якщо ви спробуєте відправити офлайн транзакцію із датою менше, ніж остання передана, то отримаєте від сервера помилку 400 | |
| 400 | [offline_mode_exception#error] Offline code 'lRvyZSJLrC4' was used before! | Якщо ви спробуєте відправити запит на перехід у офлайн з офлайн кодом, який вже був раніше використаний на іншу транзакцію, то отримаєте від сервера помилку 400 | |
| 400 | Зі вказаною міткою часу час перебування в офлайн режимі є більшим ніж дозволено (36 год.) | За замовченням дозволено перебувати в офлайн режимі роботи не більше 36 годин. Якщо ви перевищите цей ліміт, ви отримаєте помилку 400.В такому випадку роботу каси буде заблоковано, поки вона не перейде в онлайн режим роботи. Якщо ви відправляєте запити GO-ONLINE, але при перевірці стану каси вона тривалий час знаходиться в офлайн режимі - будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом. | |
| 400 | Зміну не відкрито | Якщо ви спробуєте виконати запит у закритій зміні, а його можна виконати тільки у відкритій зміні - ви отримаєте помилку 400 | |
| 400 | Зміну не відкрито, потрібно дочекатись завершення відкриття | Якщо ви спробуєте виконати запит у зміні зі статусом OPENING - ви отримаєте помилку 400. Потрібно дочекатись завершення відкриття, як правило це триває декілька секунд |
|
| 400 | Зміну відкрито понад 24 години тому, для продовження роботи закрийте діючу зміну і відкрийте нову | Касова зміна має бути закрита в той день, коли вона відкрита і не може тривати більше 24х годин. | |
| 400 | Касир вже працює з даною касою | Якщо ви відправите повторний запит на відкриття зміни, а касову зміну вже відкрито (має кінцевий статус OPENED) - ви отримаєте помилку 400 |
|
| 400 | Знайдено ще неопрацьовані транзакції у рамках поточної зміни. Зачекайте, будь ласка, завершення обробки та повторіть запит ще раз або якщо помилка повторюється тривалий час зверніться в техпідтримку | Якщо є транзакції у проміжному статусі на сервері Checkbox, то ви отримаєте помилку 400. Перевірте, чи запущено підпис касира в особистому кабінеті Checkbox. Якщо впродовж 10 хвилин ви продовжите отримувати помилку, а підпис касира запущено - будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом | |
| 400 | Візуалізація не фіскалізованого чеку неможлива, зачекайте доки чек буде фіскалізовано і повторіть запит. | Якщо ви спробуєте отримати візуалізацію чека, але чого статус не набув кінцевого DONE - ви отримаєте помилку 400 |
|
| 400 | Звіт ще не був фіскалізований в ДПС | Генерація фіскального Z-звіту можлива лише після отримання його фіскального номера. Якщо цього ще не відбулось, то ви отримаєте помилку 400. Для того, щоб успішно отримувати візуалізацію звіту, після відправлення команди закриття зміни потрібно перевіряти статус зміни, поки вона не отримає кінцевий статус CLOSED. Зазвичай це відбувається за декілька секунд. Якщо ДПС не відповідає, ми перегенеруємо онлайн закриття в офлайн режимі і самі підставимо фіскальний код, тому довго чекати не доведеться |
|
| 400 | Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>) |
Якщо ви спробуєте вилучити з каси більше коштів, ніж є у наявності, то отримаєте у відповідь помилку 400 | |
| 400 | Вказано невідомий ідентифікатор замовлення | Якщо ви вкажете некоректний або неіснуючий номер замовлення, то отримаєте помилку 400 | |
| 400 | Вказаний id чеку вже існує | Якщо ви вкажете для чека uuid, який вже був раніше використаний для створення іншого чека, то отримаєте помилку 400. Задаючи uuid чека при його створенні на своїй стороні, ви зможете убезпечити себе від повторної помилкової фіскалізації одного і того ж чека, оскільки повторна відправка запиту на створення чека з uuid, ідентичним до раніше використаного призведе до помилки і запит виконаний не буде. | |
| 400 | Receipt not found | Якщо при пошуку чека ви вкажете uuiod чека, який раніше не був зареєстрований в системі checkbox, ви отримаєте помилку 400 | |
| 400 | id попереднього чеку відрізняється від останнього збереженого чеку | Якщо в запиті невірно вказаний uuid попереднього чеку, то ви отримаєте помилку 400. Передача цього uuid у пейлоад чека є опціональною. Вона дозволяє контролювати ланцюжок чеків, які ви передаєте на сервер Checkbox і бути впевненим, що попередній чек вже потрапив на сервер, а ланцюжок передачі транзакцій лишився цілісним і послідовність не порушено. | |
| 400 | Максимальну кількість спроб перевищено, повторіть через 300 секунд | У випадку, якщо на метод встановлено rate-limit і ви його перевищите - на насу або касира (в залежності від метода) буде встновлено обмеження на повторне виконання методу | |
| 400 | Сума платежів не може бути меншою ніж сума чеку | Якщо у блоці платежів вказати суму меншу, ніж ціна товару, то ви отримаєте помилку 400. | |
| 400 | Сума платежів повинна дорівнювати сумі чеку повернення (4544.00) | Якщо у чеку повернення в блоці платежів вказати суму, що відрізняється від загальної ціни товарів, то ви отримаєте помилку 400 | |
| 400 | Загальна сума чеку має бути більшою нуля | Якщо ви спробуєте виконати створення чека методом /api/v1/receipts/sell, вказавши при цьому і товар продажу, і товар повернення, де сума чека < 0, ви отримаєте помилку 400 | |
| 400 | Решта не може бути використана для безготівкової оплати (решта = 560.00) | Якщо ви намагаєтесь виконати створення чека продажу, але сума оплати відрізняється від загальної суми товарів, ви отримаєте помилку 400 (тільки для безготівкових платежів) | |
| 400 | Товарів з кодами: <код товару> не існує у чеку продажу |
Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, а вказаного коду товару в чеку продажу немає, то ви отримаєте помилку 400 | |
| 400 | Товарів з кодами: <код товару> більше, ніж у чеку продажу |
Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, і намагаєтесь повернути більшу кількість товарів ніж є в чеку продажу, то ви отримаєте помилку 400 | |
| 400 | Неможливо створювати чеки змішаного типу (одночасний продаж та повернення)' | Якщо в одному чеку під час його створення одночасно для різних товарів вказати "is_return" true та false, ви отримаєте помилку 400 | |
| 400 | Товари чеку вже були повністю повернені | Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, і ви вже зробили повернення цього чека, то ви отримаєте помилку 400. Щоб виконати повторне повернення чека продажу, будь ласка, зв'яжіться із службою підтримки Checkbox зручним для вас способом або не вказуйте uuid пов'язаного чека продажу. | |
| 400 | Організація касира не відноситься до переданих організацій | Якщо в команді на виконання звіту по балансам зміни ви передасте унікальний ідентифікатор організації, до якої касир не належить (касир від іншої організації), то ви отримаєте відповідь 400 | |
| 400 | There was an error parsing the body | Якщо буде допущено помилку у формуванні вмісту тіла запиту і сервер не зможе його розпарсити, то ви отримаєте помилку 400 | |
| 400 | Каса зайнята іншим касиром | Якщо у заголовку запиту ви вкажете ключ ліцензії каси, на якій вже відкрита зміна іншим касиром, то отримаєте від сервера помилку 400 | |
| 400 | Даний тип чеку можна створювати тільки на ПРРО обміну валют | Перед створенням чека обміну валют, необхідно увімкнути даний функціонал через службу підтримки Checkbox. Якщо ви цього не зробите і спробуєте створити чек обміну валюти - ви отримаєте помилку 400 | |
| 400 | Курс для валюти 'UAH' не встановлено | Якщо ви спробуєте виконати операцію обміну валюти, але для цієї валюти не встановлено курс - ви отримаєте помилку | |
| 400 | Вказане замовлення відмінено | Якщо під час створення чеку продажу методом /api/v1/receipts/sell і вказуєте "order_id": "uuid" створеного раніше замовлення, яке було відмінено або не потребує фіскалізації (фіскалізовано іншим методом), ви отримаєте помилку 400 | |
| 400 | Вказане замовлення вже виконано | Якщо під час створення чеку продажу методом /api/v1/receipts/sell і вказуєте "order_id": "uuid" створеного раніше замовлення, яке вже було виконано, ви отримаєте помилку 400 | |
| 400 | Замовлення не можна закрити без фіскалізації | Якщо ви спробуєте закрити без фіскалізації замовлення, яке потребує її - ви отримаєте помилку 400 | |
| 400 | Облік товарів: task not found | Якщо ви виконаєте перевірку завдання обліку товарів, але такого "task_id": "uuid" завдання не існує, ви отримаєте помилку 400 | |
| 400 | Облік товарів: Не знайдено поставок для виконання операції | Якщо в чеку продажу ви вказуєте uuid раніше доданого товару в систему checkbox та використовуєте товарні залишки, але при цьому поставок даного товару ще не було - ви отримаєте помилку 400 | |
| 400 | Облік товарів: Не знайдено товара для списання | Якщо в чеку продажу ви вказуєте uuid раніше доданого товару в систему checkbox, але такого uuid товару не існує - ви отримаєте помилку 400 | |
| 400 | Облік товарів: Кількість списання перевищує поточну кількість товару | Якщо в чеку продажу ви вказуєте uuid раніше доданого товару в систему checkbox та кількість товару для продажу, яка перевищує кількість залишків - ви отримаєте помилку 400 | |
| 400 | Імпорт товарів підтримує виключно csv або xlsx формати | Якщо під час імпорту товарів методами API ви вкажете файл, розширення якого відрізняється від дозволених, ви отримаєте помилку 400 (дозволено виключно формати .xlsx, .csv та .json) | |
| 400 | { |
Якщо у файлі імпорту товарів допущено помилку, ви отримаєте у відповідь опис помилки із вказанням причини та місце розташування рядка помилки | |
| 401 | Невірний ключ ліцензії каси | Якщо ж ви вкажете неправильний ключ ліцензії каси - то у відповідь від сервера отримаєте помилку 401 | |
| 401 | Невірний токен доступу | Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 | |
| 403 | Невірний пінкод | У випадку, якщо PIN-код касира був вказаний невірно, ви отримаєте відповідну помилку 403 | |
| 403 | Тестовий касир не може працювати з реальною касою | Якщо ви спробуєте авторизуватись на фіскальній касі тестовим касиром - ви отримаєте помилку 403 | |
| 403 | Невірний логін або пароль | У випадку, якщо облікові дані касира були вказані невірно, ви отримаєте помилку 403 | |
| 403 | Невірний ключ доступу | У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 | |
| 403 | Термін дії ключа закінчився <YYYY-MM-DD HH:MM:SS> |
У випадку, якщо термін дії ключа касира скінчився, ви отримаєте помилку 403. Для продовження роботи вам необхідно отримати новий ключ та зареєструвати нового касира | |
| 403 | Доступ заборонено, оскільки касира деактивовано | Якщо касир деактивований користувачем, сервер поверне помилку 403. Для продовження роботи вам необхідно отримати новий ключ та зареєструвати нового касира | |
| 403 | Касира заблоковано: <причина блокування> |
Якщо касира було заблоковано на стороні Checkbox (наприклад, сертифікат ключа відізвано ДПС або АЦСК, яким його було видано) - сервер поверне помилку 403. Будь ласка, зв'яжіться із службою підтримки Checkbox зручним для вас способом для вирішення питання. | |
| 403 | Доступ заборонено, оскільки касу заблоковано | Якщо ви спробуєте виконати запит яз вказанням ключа ліцензії заблокованої або деактивованої каси - ви отримаєте помилку 403. | |
| 403 | Касу заблоковано через відсутність чеків за попередній період, необхідно сплатити за послуги користування касою для автоматичного розблокування або залишити заявку на веб-порталі https://my.checkbox.in.ua | У випадку, якщо ви не користувались касою тривалий період - вона автоматично заморожується, щоб не нараховувалась абонплата. Для розморозки - необхідно сплатити рахунок за користування касами та звернутись до служби підтримки Checkbox зручним для вас способом. | |
| 403 | Для видачі чеків, будь ласка, оплатіть рахунок за користування касами. | Якщо ви не оплатили послуги Checkbox завчасно, усі каси організації буде заблоковано, сервер поверне помилку 403. Будь ласка, зверніться до служби підтримки Checkbox, щоб ми оперативно розблокували роботу кас та надіслали вам актуальний рахунок. | |
| 400 | SMS шлюз не активовано для організації | Якщо ви спробуєте відправити чек на SMS/Viber, але даний функціонал не увімкнено в налаштуваннях кабінету організації - ви отримаєте помилку. Будь ласка, активуйте дану функцію в налаштуваннях організації та поповніть рахунок за відправку SMS/Viber згідно інструкції | |
| 403 | Not authenticated | Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 | |
| 405 | Ваша версія агенту підпису застаріла та більше не підтримується, оновіть його будь ласка.\nОновлення можна отримати на веб-порталі: https://my.checkbox.in.ua/ | Якщо ви виконуєте запит, який потребує обов'язкової передачі X-Client-Name у заголовку, а ви його залишите пустим - сервер поверне помилку 405 | |
| 409 | Зміну відкрито за допомогою CheckBox Kasa, виконання дії через іншу інтеграцію призведе до непередбачуваних помилок в роботі каси | У випадку, якщо зміну було відкрито через іншу інтеграцію, для якої встановлені обмеження (наприклад, Checkbox Каса, використання якої одночасно з прямою API інтеграцією може призвести до серйозних помилок в роботі ПРРО), API поверне помилку | |
| 409 | Каса вже використовується іншим ID агента. Ймовірно запит виконано з каси дублікату. Зверніться до підтримки | У випадку, якщо зміну було відкрито через іншу інтеграцію, для якої було передано X-Device-ID і ви виконуєте запит із іншим X-Device-ID, API поверне помилку 409 | |
| 422 | json{ |
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки | |
| 429 | Занадто часто виконуються запити, повторіть спробу через <...> секунд | За замовченням для каси стоїть rate-limit на кількість запитів за проміжок часу. Якщо ви робите більше 2-х запитів в 1 секунду, то ви отримаєте помилку 429. На цей час блокуються запити з конкретної каси (а не IP-адреси). Якщо на системному рівні ви перевищуєте заданий ліміт часу - ми вимушені блокувати IP-адреси, поки ви не виправите власну інтеграцію та зв'яжетесь із нами для зняття блокування. | |
| 503 | Maintenance work till 3:30 GMT+3. Sorry for the inconvenience. | Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 | |
| 503 | 503 Service Temporarily Unavailable. We apologise for the inconvenience. Please try again in 2 minutes. We work hard to make Checkbox the world's best prro software | Якщо у момент запиту на сервер Checkbox - сервер тимчасово не доступний, ви отримаєте помилку з кодом 503. Будь ласка, спробуйте повторити свій запит через 2 хвилини. | |
| 524 | 524 Timeout Occured | Якщо у момент запиту на сервер Checkbox - сервер не відповів і з'єднання було закрито через завершення часу очікування, ви отримаєте помилку з кодом 524. Будь ласка, спробуйте повторити свій запит через 2 хвилини |
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.