¶ Вступ
Checkbox – сервіс програмної реєстрації розрахункових операцій (далі - ПРРО).
Цей документ описує частину аспектів підключення сервісу ПРРО Checkbox для eCommerce порталу або будь-якого іншого додатку, що потребує реалізації функції реєстрації розрахункових операцій (фіскалізації) у вигляді відкритого RESTful API.
Сервіс складається з особистого кабінету, транзакційного процесингу, агентів підпису та фронт-агентів.
Через особистий кабінет виконується реєстрація торговця в системі і управління його точками продажу, касами та касирами.
Транзакційний процессинг забезпечує взаємодію із ДПС, взаємодію із агентами підпису та реалізує API інтерфейс для роботи фронт-агентів через які кінцевий користувач і створює чеки.
Фронт-агентами можуть бути:
- Для Retail – спеціалізована бібліотека Checkbox Kasa Manager, що встановлюється на касовий вузол торговця
- Для eCommerce – WebAPI з адаптованою під задачі eCommerce специфікацією
- Для МСБ – мобільний додаток Checkbox для android або iOS та особистий кабінет.
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції. З повним переліком методів (без деталізованого опису) ви зможете ознайомитись за посиланнями Swagger та ReDoc.
Із загальною схемою архітектури сервісу ви можете ознайомитись за посиланням.
¶ Перед початком роботи
¶ Послідовніcть роботи
- Авторизація (отримання токену доступу)
- Перевірка режиму роботи каси (офлайн або онлайн)
- Перехід у потрібний режим роботи:
- якщо офлайн: перевірка зв'язку з ДПС → переведення каси в онлайн режим → перевірка режиму роботи каси
- якщо онлайн: перевірка доступних офлайн кодів, запит нових (якщо кількість доступних менша за мінімальну)
- Відкриття касової зміни
- Перевірка статусу відкриття зміни:
- кінцевий статус відкритої зміни
OPENED - якщо тривалий час статус
OPENING- будь ласка, зв'яжіться із службою підтримки checkbox
- кінцевий статус відкритої зміни
- Створення чеків (продаж та повернення, видача готівкових коштів держателям ЕПЗ)
- Перевірка статусу створеного чека:
- кінцевий статус створенного чека
DONE - при отриманні статусу
CANCELLEDабоERROR, перевірити причину та усунути - якщо тривалий час статус
CREATED- будь ласка, зв'яжіться із службою підтримки checkbox
- кінцевий статус створенного чека
- Отримання візуалізації створенного чека (тільки після набуття кінцевого статусу
DONE) - Створення службових чеків внесення/винесення готівки (за потреби)
- Створення Х-звіту (за потреби)
- Періодичне (раз на пів години) - перевірка режиму роботи каси (офлайн або онлайн). Якщо офлайн: перевірка зв'язку з ДПС та подальший вихід в онлайн режим
- Закриття касової зміни
- Скасування токена доступу (рекомендуємо раз на тиждень змінювати токен)
Також радимо ознайомитись із графічною схемою, яка показує принципи, по яким можна побудувати АПІ інтеграцію. Можливо, вона також допоможе розібратися з питаннями, в якості доповнення до цієї документації.
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та можливо платити штраф.
¶ Структура запитів та відповідей
¶ Доступи
*.checkbox.ua*.checkbox.in.ua
CA центрів сертифікації:e1.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: <токен авторизації>
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-Access-Key: <ключ доступу інтеграції (не використовується зараз)>
X-Device-ID: <ID RRO Agent або мобільного пристрою каси (не використовується для API інтеграцій)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Додаткові параметри вибірки для спискових запитів (фільтрація, сортування, паджинація і тд.), форматуються за правилами HTTPS параметрів params opt.
¶ Методи HTTPS
-
GET /:entity/:id— getById
Якщо успішно, сервер повертає 200 ОК з полями об'єкта в форматі JSON в тілі відповіді (без додаткового оберту в будь-який об'єкт). У випадку, якщо об'єкта із таким UUID не існує, сервер поверне відповідь 404 Not Found.
-
GET /:entity[?param1=...& param2=...]— списковий get
Якщо успішно, сервер поверне 2хх ОК з масивом об'єкта в форматі JSON в тілі відповіді (тобто починається з [ і закінчується ] ). Якщо масив вийшов пустим, все одно повертається 2хх ОК з пустим масивом в тілі відповіді.
-
POST /:entity— створення нового об'єкта типу :entity
У тілі запиту мають бути перелічені поля об'єкта в форматі JSON без додаткового оберту (тобто {"field1":"value","field2":10}). У випадку успіху сервер має повернути 2хх Created з тілом, аналогічним запиту getByID, з усіма полями зміненого об'єкта.
-
PATCH /:entity/:id— зміна окремих полів об'єкта
У запиті мають бути перелічені тільки поля, які мають бути змінені. У випадку успіху сервер поверне 2хх ОК з тілом, аналогічним запиту getByID, з усіма полями зміненого об'єкта.
-
DELETE /:entity/:id— видалення об'єкта, якщо воно існує
У випадку успіху повертає 2хх No Data з порожнім тілом, так як повертати немає чого.
¶ Авторизація
¶ Отримання токену
Існує 2 способи авторизації користувача в API сheckbox:
- за допомогою ключа ліцензії каси та пінкоду касира (рекомендований)
- за допомогою логіна та пароля касира
1 активний касир може мати не більше 10 діючих токенів. Після отримання нового токену, старі - видаляються автоматично. У разі отримання вами помилки виду:
Невірний токен доступу- необхідно отримати і використовувати новий токен.
¶ signinPinCode
Для отримання токену доступу потрібно виконати запит /api/v1/cashier/signinPinCode та вказати ключ ліцензії каси, а у тілі запиту - пінкод касира (ці дані можна знайти у відповідних розділах особистого кабінету).
У відповідь ви отримаєте jwt токен авторизації, підставляючи який у заголовки запитів інших методів зможете їх використовувати від імені касира, яким була виконана авторизація.
Кожного разу при новій авторизації - ви будете отримувати новий токен доступу (старі токени залишаються активними). Для деактивації токену необхідно виконати деактивацію методом /api/v1/cashier/signout із токеном, який ви хочете деактивувати.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Content-Type: application/json
¶ Request body
{
"pin_code": "<пінкод касира>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cashier/signinPinCode' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Content-Type: application/json' \ -d '{ "pin_code": "2802811111"}'
¶ Responce body
{
"type": "bearer",
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiODVmOTI3YWMtY2RjMC00ZmIxLTgyYjctZDc4MmM1MTM0Y2Q3Iiwic3ViIjoiMDRkYTQwYWEtZTI4ZS00MmI3LThkNTEtNmNiNmVlODAwMjQ1IiwibmJmIjoxNjk5MDAwOTQyLCJpYXQiOjE2OTkwMDA5NDJ9.yNuS5e7ox3-_a7p2DI5OqwpYM7mVqIAkw1111111111"
}
¶ signin
Для отримання токену доступу потрібно виконати запит /api/v1/cashier/signin та вказати ЛОГІН та ПАРОЛЬ касира (пароль касира вказувався при реєстрації).
Для тестового касира пароль - це його логін.
Якщо ви не пам'ятаєте пароль касира, перейдіть в особистий кабінет checkbox → Касири → натисніть ··· навпроти касира → Редагувати → введіть новий пароль касира → натисніть Зберегти.
У відповідь ви отримаєте jwt токен авторизації, підставляючи який у заголовки запитів інших методів зможете їх використовувати від імені касира, яким була виконана авторизація.
Кожного разу при новій авторизації - ви будете отримувати новий токен доступу (старі токени залишаються активними). Для деактивації токену необхідно виконати деактивацію методом /api/v1/cashier/signout із токеном, який ви хочете деактивувати.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Content-Type: application/json
¶ Request body
{
"login": "<логін касира>",
"password": "<пароль касира>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cashier/signin' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Content-Type: application/json' \ -d '{ "login": "test_pqhb11111", "password": "test_pqhb11111"}'
¶ Responce body
{
"type": "bearer",
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiM2U3MDk4OTYtOGM4YS00ZTcwLThhNGYtZWRlZmYyZThlMjBkIiwic3ViIjoiNmZhOGEZNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjUyNzI5ODkxLCJpYXQiOjE2NTI3Mjk4OTF9.ReYF8FicTFZiyi9s6NF6n3Y-VInbYa7_V1111111111"
}
¶ Деактивація токену
Сам токен доступу - не має чіткого строку життя. Проте рекомендуємо його періодично змінювати для забезпечення безпеки передачі даних.
- якщо вам потрібно завершити сесію користувача (касира) з поточним токеном доступу та скасувати токен - використайте метод /api/v1/cashier/signout
- для деактивації всіх активних токенів касира достатньо виконати заміну пароля касира в особистому кабінеті, або скинути пін-код (розділ Касири → натиснути ··· навпроти касира → Скинути пінкод).
Також деактивація старого токену касира відбувається при використанні функції Заміни ключа касира, оскільки відбувається деактивація старого касира та реєстрація нового в Податковій Службі (хоча логін та пінкод касира в системі checkbox залишаються незмінними).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язоково)>
X-Client-Version: <версія інтеграції (обов`язоково)>
Authorization: <токен авторизації>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cashier/signout' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -d ''
¶ Responce body
null
null - у разі успішної деактивації токена авторизації
¶ Режим роботи каси
¶ Перевірка інформації про касу
Щоб отримати UUID каси, скористайтесь методом /api/v1/cash-registers.
Щоб визначити, в якому режимі зараз працює каса, потрібно виконати запит на отримання інформації про ПРРО /api/v1/cash-registers/{cash_register_id}. Параметр "offline_mode" повідомить нам про поточний статус онлайн/офлайн режиму. Для онлайн режиму цей параметр має значення false, а для офлайн режиму - true.
Максимальний режим роботи в офлайн режимі — 36 годин.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/c13876dd-e51e-433f-a61c-f2c426311111' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token'
¶ Response body
{
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-10T22:55:07+00:00",
"number": "1",
"shift": null,
"offline_mode": true,
"stay_offline": true,
"branch": null,
"address": "УКРАЇНА, М.КИЇВ ГОЛОСІЇВСЬКИЙ Р-Н, Тестова, 41а",
"type": 0
}
"id" - унікальний ідентифікатор каси у форматі UUID
"fiscal_number" - фіскальний номер каси
"active" - true/false, ідентифікатор активної каси. Для кас, деактиованих в системі checkbox цей параметр буде false
"created_at" - дата створення каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останнього оновлення (зміни) облікових даних каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"number" - порядковий номер каси
"shift" - блок даних з інформацією про зміну. Якщо касову зміну не відкрито, відповідь буде null
"offline_mode" - true/false, ідентифікатор офлайн режиму. false означає, що каса зараз у онлайні, а true означає, що каса працює у офлайн режимі.
"stay_offline" - якщо даний параметр true, то це означає, що перехід у офлайн був виконаний на стороні клієнта (шляхом відправки запиту /api/v1/cash-registers/go-offline, а не завдяки автоматичному офлайн переходу, який відбувається, коли не відповідає сервер ДПС)
"branch" - блок даних з інформацією про торгову точку. Якщо це тестова касса, значення завжди буде null
"address" - адреса торгової точки
¶ Перевірка зв'язку з ДПС
Для перевірки зв'язку з сервером Податкової Служби можна скористатися методом /api/v1/cash-registers/ping-tax-service. Відправка команди PING також ініціалізує відправку чеків у податкову з подальшим виходом каси у онлайн режим (якщо вона знаходиться у офлайні).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/ping-tax-service' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -d ''
¶ Response body
{
"status": "DONE",
"error": null
}
Якщо ви отримуєте помилку виду:
_InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.DEADLINE_EXCEEDED
details = "Deadline Exceeded"
debug_error_string = "{"created":"@1651529548.259915513","description":"Deadline Exceeded","file":"src/core/ext/filters/deadline/deadline_filter.cc","file_line":81,"grpc_status":4}"
>
Це свідчить про недоступність серерів Податкової Служби.
"status" - статус транзакції відправки запиту. Може мати статуси CREATED/PENDING/SIGNED/DELIVERED/DONE або ERROR
"error" - текстовий опис помилки, яку повернає сервер ДПС. Якщо помилки немає, цей параметр прийме значення null
У полі "error" може повертатись і помилка виду:
{
"status": "DONE",
"error": "ERROR_BAD_HASH_PREV store bdfdc222d0a015519e269292d58b5690a7f02d9b65a0eae79b6241b7a9ea153f chk ad10bda2a97f4674dbb052a0ff0e401175d8425bd85f9bf9247ddba1ff73421e"
}
Вона ніяк не вплине на роботу безпосередньо (команда PING призначена для перевірки наявності зв'язку з ДПС, а не для передачі і збереження транзакції зміни/чека/офлайн-онлайн переходу, тому не важливо, пройде чи ні PING перевірку на відповідність хешу попереднього чеку. Будь-яка відповідь від ДПС означатиме, що зв'язок з податковою є).
Ситуація з помилкою вище виникає у випадку, коли з сервера Checkbox відправляється PING, але він до сервера ДПС потрапляє раніше, ніж масив чеків, створених у офлайн режимі, які ще не потрапили до ДПС.
Якщо сервер ДПС у даний момент недоступний, ви отримаєте помилку виду:
_InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.DEADLINE_EXCEEDED
details = "Deadline Exceeded"
debug_error_string = "{"created":"@1651529548.259915513","description":"Deadline Exceeded","file":"src/core/ext/filters/deadline/deadline_filter.cc","file_line":81,"grpc_status":4}"
>
¶ Офлайн-коди
¶ Отримання нових кодів з ДПС
Отримати з Податкової Служби список фіскальних кодів для створення офлайн транзакцій можна за допомогою метода /api/v1/cash-registers/ask-offline-codes тільки коли каса знаходиться у ОНЛАЙН режимі. Після виконання запиту ці номери зберігаються на сервері Checkbox і стають доступними для отримання методом /api/v1/cash-registers/get-offline-codes.
Після виконання запиту на офлайн коди відправляти будь-які офлайн транзакції (зміни, чеки, офлайн переходи) можна тільки з датою/часом fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу виконання запиту /api/v1/cash-registers/ask-offline-codes.
Відправити запит на офлайн фіскальні коди можна синхронно або асинхронно, що регулюється відповідним параметром у запиті (sync). Кількість кодів, яку користувач бажає отримати, задається у параметрі count запиту.
Максимальна кількість кодів, яку повертає ДПС = 5000 кодів!
Асинхронний режим одразу поверне статус "status": "OK" (або "ERROR", якщо на етапі формування запиту відбулася помилка), незалежно від того, чи запит успішно досяг сервера податкової. У асинхронному режимі "ОК" не означає успішне виконання запиту, а тільки його успішну відправку. Синхронний режим обробляє запит повністю і передає остаточний статус "DONE", якщо запит успішно досяг сервера ДПС, або "TIMEOUT", якщо сервер ДПС не відповів у визначений строк.
Важливо - номер перестає повертатися сервером ДПС (вважається "використаним") лише після відправки до ДПС транзакції з цим номером. До того часу ДПС повертає фіскальний номер при кожному виклику.
Наприклад: зробивши до ДПС перший запит на 100 номерів, отримаємо 100 нових вільних фіскальних номерів для відповідного ПРРО. Але зробивши після цього запит ще на 200 номерів, отримаємо 100 тих самих номерів та ще 100 наступних за ними.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/ask-offline-codes?count=2000&sync=true' \ -H 'accept: */*' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token'
¶ Response body
{
"status": "OK"
}
"status" - статус запиту. Для асинхронного режиму завжди буде "ОК" або "ERROR", для синхронного - приймає значення "DONE" у випадку успішного запиту, "TIMEOUT", якщо перевищено ліміт очікування відповіді від сервера ДПС або "ERROR", якщо виникла помилка.
Врахуйте, що у асинхронному режимі "ОК" не означає успішне виконання запиту, а тільки його успішну відправку.
"error" - текстовий опис помилки.
¶ Отримання списку невикористаних кодів
Якщо попередньо ПРРО раніше вже отримало список офлайн фіскальних кодів за допомогою метода /api/v1/cash-registers/ask-offline-codes, то за допомогою метода /api/v1/cash-registers/get-offline-codes ви зможете завантажити необхідну кількість невикористаних на даний момент фіскальних номерів з сервера Checkbox, навіть якщо сервер ДПС недоступний.
Будь-який фіскальний код можна використати лише 1 раз на створення офлайн транзакції відкриття/закриття зміни, офлайн переходу або чеку. Врахуйте, що на стороні серверу Checkbox реалізовано функцію автоматичного переходу у офлайн режим у випадку тайм-ауту відповіді від ДПС. Тобто, сервер автоматично створить транзакцію офлайн переходу та почне створювати чеки у офлайн режимі, підставляючи у них доступні офлайн коди, навіть якщо ви зі свого боку відправляєте чеки як онлайнові. Перед відправкою до Checkbox офлайн чеків варто синхронізувати пул доступних для використання фіскальних кодів, інакше на певних чеках може виникнути помилка виду "Offline code '<офлайн код>' was used before!".
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/get-offline-codes?count=3' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token'
¶ Response body
[
{
"fiscal_code": "TEST-iA5fmb",
"serial_id": 1,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586071+00:00"
},
{
"fiscal_code": "TEST-aQ-V-c",
"serial_id": 2,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586073+00:00"
},
{
"fiscal_code": "TEST-WzSbIz",
"serial_id": 3,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586073+00:00"
}
]
Для кожного фіскального коду метод поверне масив даних, який включає в себе:
"cash_register_id" - id обраної каси у форматі UUID
"serial_id" - порядковий номер фіскального коду
"created_at" - дата створення фіскального коду
"fiscal_code" - фіскальний код
Якщо на сервері немає фіскальних кодів, то масив буде порожнім. У випадку, якщо ви відправите у запиті параметр count, який буде перевищувати кількість доступних офлайн кодів, то сервер поверне у тілі відповіді стільки кодів, скільки є у наявності.
¶ Перехід в онлайн
POST метод /api/v1/cash-registers/go-online дозволяє відправити команду на початок переходу у онлайн режим.
Cама по собі відправка цієї команди не означає, що каса буде одразу переведена у онлайн режим.
Якщо в черзі на відправку у ДПС багато офлайн чеків, то одного запиту може бути недостатньо. Після відправки /api/v1/cash-registers/go-online варто через хвилину перевірити статус каси запитом /api/v1/cash-registers/{cash_register_id} (параметр "offline_mode" має повернути поточний статус). У онлайні він буде false, а у офлайні true. Якщо каса не перейшла у онлайн - варто відправити /api/v1/cash-registers/go-online ще раз та знову перевірити через хвилину статус каси, повторюючи дії в циклі, поки каса не вийде у онлайн-режим.
Наявний rate-limit дозволяє передавати не більше 1 запиту раз на 2 хвилини. Він діє індивідуально на кожну окрему касу, а не на IP-адресу.
При систематичному порушенні ліміту ми зв'яжемось за контактами, вказаними в налаштуваннях особистого кабінету організації для вирішення питання порушення наявних лімітів.
Якщо ви відправили команду /api/v1/cash-registers/go-online вже більше разів, ніж у вас створено невідправлених у ДПС офлайн транзакцій, або вже тривалий час не можете перейти у онлайн, незважаючи на постійні спроби - перевірте наявність зв'язку з ДПС методом /api/v1/cash-registers/ping-tax-service. Якщо з податковою є зв'язок, а перехід у онлайн не відбувається - зверніться у технічну підтримку Checkbox за консультацією.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/go-online' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -d ''
¶ Response body
{
"status": "ok"
}
"status" - статус отримання команди на ініціалізацію переходу у онлайн режим. Даний статус завжди повертає значення "ok" у випадку успішного виконання запиту, проте не означає, що каса одразу ж перейде у онлайн. Саме тому радимо через хвилину перевірити статус каси запитом /api/v1/cash-registers/{cash_register_id}. Після того, як каса перейде у онлайн, потрібно зупинити повторну відправку /api/v1/cash-registers/go-online, щоб не створювати зайве навантаження на сервер Податкової Служби.
¶ Перехід в офлайн
POST метод /api/v1/cash-registers/go-offline дозволяє відправити команду на перехід ПРРО у офлайн режим. Для переходу у офлайн достатньо виконати 1 успішний запит go-offline. Поточний статус онлайн/офлайн ПРРО можна визначити за допомогою запиту /api/v1/cash-registers/{cash_register_id}. Параметр "offline_mode" покаже поточний статус онлайн/офлайн (у онлайні він буде false, а у офлайні true).
У тілі запиту є можливість вказати часову мітку офлайн переходу (такою датою/часом буде зареєстрований у ДПС перехід у офлайн).
Перейти у офлайн можливо з міткою дати/часу fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу останньої успішно доставленої у ДПС транзакції (чеку/відкриття/закриття зміни/переходу у онлайн).
Передача невірної дати/часу призведе до застрягання каси у офлайн режимі та ПОЛОМКИ КАСИ.
У параметрі "fiscal_code" потрібно передати фіскальний код, який раніше ще не був використаний.
Якщо в тілі запиту на перехід у офлайн не передати параметр "fiscal_code", то сервер зі свого боку автоматично підставить один з вільних фіскальних кодів і виконає переведення ПРРО у офлайн режим. Врахуйте, що якщо ви спробуєте потім відправити чек з офлайн кодом, який був автоматично підставлений у офлайн перехід, то виникне помилка, оскільки кожен код можна використати лише один раз. Також, якщо у тілі запиту не вказувати "go_offline_date", то офлайн перехід відбудеться з поточною міткою дати/часу. Тобто, якщо вас влаштовує, що офлайн код буде автоматично підставлено сервером, а дата/час переходу будуть поточні, то можете лишити тіло запиту на перехід у офлайн взагалі порожнім.
Первинне отримання масиву фіскальних кодів відбувається з використанням методу /api/v1/cash-registers/ask-offline-codes. Після успішного виконання /api/v1/cash-registers/ask-offline-codes отримати список ще не використаних на сервері фіскальних кодів можна за допомогою метода /api/v1/cash-registers/get-offline-codes. Саме ним бажано користуватись, аж допоки запас офлайн кодів не зменшиться до кількості, яку ви встановите для себе критичною (наприклад, до 500). Метод /api/v1/cash-registers/get-offline-codes дозволяє набагато швидше отримати вільні, вже отримані раніше фіскальні коди для обраного ПРРО, не чекаючи відповідь від сервера податкової.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Content-Type: application/json
¶ Request body
{
"go_offline_date": "<фіскальна дата у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>",
"fiscal_code": "<фіскальний код>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/go-offline' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "go_offline_date": "2023-11-29T06:14:20+0200", "fiscal_code": "TEST-aQ-V-c"}'
¶ Response body
{
"status": "ok",
"id": "4722e600-905f-4a89-9d71-801698125664"
}
"status" - статус виконання запиту. Успішний запит завжди матиме статус ok
"id" - унікальний ідентифікатор транзакції у форматі UUID
¶ Зміни
¶ Відкриття зміни
Відкриття зміни відбувається методом /api/v1/shifts. Відкрити зміну можна у онлайн або офлайн режимі. Перше відкриття зміни обов'язоко має виконвуватись в онлайн режимі.
- Для створення зміни у онлайн режимі не потрібно вказувати фіскальний код або фіскальну дату (дата відкриття зміни буде рівною дати та часу отримання сервером checkbox запиту), але потрібно вказати ключ ліцензії каси конкретного пРРО, розташованого в тій же торговій точці, що знаходиться касир.
Якщо ви відкриваєте касову зміну по API або через портал - заборонено виконання інших дій через Checkbox.Kasa або Manager, оскільки виконання дій через іншу інтеграцію призведе до непередбачуваних помилок в роботі каси, формуванню помилкових звітів і т.д
Створюється об'єкт зміни в стані CREATED та транзакція відкриття зміни (поле "initial_transaction"). Для переведення зміни в статус OPENED необхідно щоб транзакція була підписана за допомогою КЕП та доставлена в ДПС (як правило це триває декілька секунд).
За замовчуванням варто працювати максимум часу у онлайн режимі, оскільки є обмеження на використання офлайну - не більше 36 годин підряд і 168 годин на місяць. Слідкувати за дотриманням цієї норми потрібно клієнту, який використовує API.
- Для відкриття зміни у офлайн режимі потрібно спочатку виконати команду /api/v1/cash-registers/go-offline, а після цього в тілі запиту вказати не використаний раніше фіскальний код, фіскальну дату та UUID зміни.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<унікальний ідентифікатор зміни у форматі UUID>",
"fiscal_code": "<фіскальний код>",
"fiscal_date": "<фіскальна дата у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/shifts' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id": "cec5dd7e-837c-46c6-a0ba-03a61cd11111"}'
¶ Response body
{
"id": "cec5dd7e-837c-46c6-a0ba-03a61cd11111",
"serial": 43,
"status": "CREATED",
"z_report": null,
"opened_at": null,
"closed_at": null,
"initial_transaction": {
"id": "1bde6e04-31e6-41d3-9a65-4b8d46511111",
"type": "SHIFT_OPEN",
"serial": 157,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": null,
"original_datetime": "2023-11-06T14:41:30.108678+00:00",
"previous_hash": "01bec2834cba96d53bd8f930a3d6acc8a29789a70dce728ea28aa991b7111111"
},
"closing_transaction": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": null,
"balance": {
"initial": 0,
"balance": 0,
"cash_sales": 0,
"card_sales": 0,
"discounts_sum": 0,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": null
},
"taxes": [
{
"id": "b3820b97-9c13-4b6f-aa5b-98cdb3411111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "ccf0e3cb-0286-423f-a278-df9f3c611111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "22abcf11-e9b2-4f40-8c46-1a3b5cb11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4828cb2f-db1f-4174-acce-77e056111111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST551151",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-04T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
}
"id" - унікальний ідентифікатор зміни у форматі UUID
"serial" - порядковий номер зміни (рахуються і не вдалі зміни)
"status" - статус зміни (доступні: CREATED/OPENED/CLOSING/CLOSED (СТВОРЕНА/ВІДКРИТА/ЗАКРИВАЄТЬСЯ/ЗАКРИТА))
"z_report" - блок з інформацією по Z-звіту касової зміни (для відкритої зміни це значення завжди буде null)
"opened_at" - мітка часу відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"closed_at" - мітка часу закриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm (для відкритої зміни завжди буде null)
"initial_transaction" - блок з інформацією про першу транзакцію обраної зміни
"closing_transaction" - блок даних про останню транзакцію у зміні (для відкритої зміни прийматиме значення null). Якщо зміна закрита, то даний блок міститиме набір даних стосовно останньої транзакції у зміні аналогічний до "initial_transaction"
"created_at" - мітка часу створення зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - мітка часу останнього оновлення даних зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm (null - якщо дані ще ні разу не оновлювались)
"emergency_close" - мітка часу встановлення аварійного закриття зміни (для Checkbox.Manager) у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"emergency_close_details" - коментар до встановленної мітки аварійного закриття зміни (для Checkbox.Manager)
"taxes" - блок даних з інформацією про податкові ставки
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо (накладений податок використовується вкрай рідко, тому через веб-інтерфейс сайту checkbox заблокована можливість створення податкових ставок накладеного податку)
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "updated_at" - мітка часу останньої зміни податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "no_vat" - відмітка податкової ставки "Без ПДВ"
- "sales" - сума податку усіх чеків продажу у копійках
- "returns" - сума податку усіх чеків повернення у копійках
- "returns_turnover" - сума повернень з цією податковою ставкою (оборот) у копійках
- "sales_turnover" - сума продажів з цією податковою ставкою (оборот) у копійках
"balance" - блок даних по грошовому балансу зміни (всі значення передаються у копійках)
- "initial" - початковий баланс готівкових коштів
- "balance" - поточний баланс готівкових коштів
- "cash_sales" - сума готівкових продажів
- "card_sales" - сума безготівкових продажів
- "discounts_sum" - сума знижок за зміну
- "extra_charge_sum" - сума надбавок за зміну
- "cash_returns" - сума готівкових повернень
- "card_returns" - сума безготівкових повернень
- "service_in" - сума службових внесень готівкових
- "service_out" - сума службових вилучень готівкових коштів
- "updated_at" - мітка часу останнього оновлення даних балансу зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"cashier" - блок даних з інформацією про касира, який виконав дію
- "id" - унікальний ідентифікатор касира у форматі UUID
- "full_name" - ПІБ касира, вказане користувачем при його реєстрації
- "nin" - ідентифікаційний код касира у ДПС
- "key_id" - ідентификатор ключа (печатки) ЕЦП касира
- "signature_type" - тип агента підпису чеків, який використовується касиром (актуальними є:
CLOUD_SIGNATURE_3/AGENT/DEPOSITSIGN) - "created_at" - мітка часу реєстрації касира у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "updated_at" - мітка часу останнього внесення змін у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "certificate_end" - дата завершення строку дії електронного ключа (печатки) касира у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "blocked" - інформація про чинність сертифікату ключа (печатки) касира (якщо на агенті підпису активна перевірка сертифікату за OSCP протоколом, у випадку, коли користувач скасовує електронний ключ (печатку), в цьому полі буде відповідне повідомлення "blocked": "Сертифікат не чинний (при перевірці за протоколом OCSP)". Якщо ж інформації про блокування ключа (печатки) сервер не має, то за замовчуванням у відповіді сервера буде значення "blocked": null)
"permissions" - перелік додаткових дозволів для обраного касира.
- "orders" - користування функціоналом API у режимі роботи з замовленнями (тільки для кур'єрів)
- "add_discounts" - ручне додавання знижок до товару
- "editing_goods_sum" - ручна правка суми товарів
- "deferred_receipt" - створення відкладених чеків (мобільний додаток)
- "editing_good_price" - ручна правка ціни товарів
- "can_add_manual_good" - додавання товарів не з загального переліку товарів
- "service_in" - службове внесення готівки
- "service_out" - службове вилучення готівки
- "returns" - виконання повернень фіскальних чеків продажу
- "sales" - виконання фіскальних чеків продажу
- "card_payment" - прийняття оплати картою
- "cash_payment" - прийняття оплати готівкою
- "other_payment" - прийняття оплати іншими методами
- "mixed_payment" - прийняття змішаних типів оплати
- "reports_history" - дозвіл перегляд історії звітів (Х та Z-звіти в мобільному додатку)
- "additional_service_receipt" - створення чека доставки
- "free_return" - додаткове службове вилучення
"cash_register" - блок даних з інформацією про касу, на якій було створено транакцію
- "id" - унікальний ідентифікатор каси у форматі UUID
- "fiscal_number" - фіскальний номер каси
- "active" - статус каси
АКТИВНА/НЕАКТИВНА(true/false) - "created_at" - мітка часу реєстрації каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни даних каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "number" - номер каси в кабінеті checkbox
"initial_transaction" - блок з інформацією про першу транзакцію обраної зміни
- "id" - унікальний ідентифікатор транзакції у форматі UUID
- "type" - тип транзакції. Для першої транзакції зміни це значення завжди буде
SHIFT_OPEN - "serial" - порядковий номер транзакції
- "status" - статус транзакції. Може приймати значення
CREATED/PENDING/SIGNED/DELIVERED/DONE(абоERROR) (СТВОРЕНА``/НА ПІДПИСАННІ/ПІДПИСАНА/ВІДПРАВЛЕНА/ВИКОНАНА(абоПОМИЛКА)) - "request_signed_at" - мітка часу підписання запиту на відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "request_received_at" - мітка часу отримання запиту на відкриття зміни сервером ДПС у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Якщо запит ще не був доставлений у податкову, то дане значення буде null
- "response_status" - статус, отриманний від сервера ДПС у відповідь на запит. Успішний запит матиме статус OK
- "response_error_message" - текстовий опис помилки, при отриманні її від сервера ДПС у відповідь на запит.
- "response_id" - ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер)
- "offline_id" - офлайн ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер). Матиме значення null якщо транзакція відкриття зміни була створена у онлайн режимі.
- "created_at" - мітка часу створення транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "original_datetime" - мітка часу найновішої транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "previous_hash" - хеш попередньої транзакції
¶ Перевірка статусу
Після створення запиту відкриття або закриття зміни - необхідно відслідковувати статус зміни, доки він не змінится на OPENED або CLOSED.
Статус зміни можна відслідковувати за допомогою GET запиту /api/v1/shifts/{shift_id}, де {shift_id} - ідентифікатор зміни, який ви вказували при створенні зміни.
- якщо ви виконали запит на відкриття зміни і при перевірці її статус змінився на
OPENED- ви можете виконувати фіскальні операції (чеки), створювати Х-звіт і т.д - якщо ви виконали запит на відкриття зміни, але при перевірці її статус
CLOSED- це означає, що зміна не може бути відкрита. Деталізація причини відмови у створенні зміни знаходиться в полі "initial_transaciton". - якщо ви виконали запит на закриття зміни і статус змінився на
CLOSED- все добре, це кінцевий статус зміни. Після отримання цього статуту можна отримати візуалізацію Z-звіту методом /api/v1/reports/{report_id}/text.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/shifts/cec5dd7e-837c-46c6-a0ba-03a61cd11111' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token'
¶ Response body
{
"id": "cec5dd7e-837c-46c6-a0ba-03a61cd11111",
"serial": 43,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-06T14:41:30.108678+00:00",
"closed_at": null,
"initial_transaction": {
"id": "1bde6e04-31e6-41d3-9a65-4b8d46511111",
"type": "SHIFT_OPEN",
"serial": 157,
"status": "DONE",
"request_signed_at": "2023-11-06T14:41:30.171706+00:00",
"request_received_at": "2023-11-06T14:41:30.214959+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-D11111",
"offline_id": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.240628+00:00",
"original_datetime": "2023-11-06T14:41:30.108678+00:00",
"previous_hash": "01bec2834cba96d53bd8f930a3d6acc8a29789a70dce728ea28aa991b7111111"
},
"closing_transaction": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.244566+00:00",
"balance": {
"initial": 0,
"balance": 0,
"cash_sales": 0,
"card_sales": 0,
"discounts_sum": 0,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": null
},
"taxes": [
{
"id": "b3820b97-9c13-4b6f-aa5b-98cdb3411111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "ccf0e3cb-0286-423f-a278-df9f3c611111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "22abcf11-e9b2-4f40-8c46-1a3b5cb11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4828cb2f-db1f-4174-acce-77e056111111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-04T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
}
Параметри відповіді аналогічні параметрам відповіді метода створення чека, але при цьому буде змінено "status" зміни на кінцевий "OPENED" або "CLOSED".
¶ Закриття зміни
Рекомендуємо самостійно на своїй стороні реалізувати виконання методу закриття зміни і не використовувати автоматичне закриття на сайті як основний спосіб закриття касової зміни.
Після створення чеків та закінчення робочої зміни необхідно закрити касову - для цього використовується метод /api/v1/shifts/close. Перед закриттям зміни потрібно впевнитись, що всі минулі транзакції зміни мають кінцевий статус DONE. Стан зміни встановлюється як CLOSING та створюється транзакція закриття зміни (поле "closing_transaction").
Для переведення зміни в статус CLOSED необхідно щоб транзакція була підписана за допомогою КЕП та доставлена в ДПС (як правило це триває декілька секунд).
Якщо ви відкрили касову зміну по API або через портал - заборонено виконання інших дій через Checkbox.Kasa або Manager, оскільки виконання дій через іншу інтеграцію призведе до непередбачуваних помилок в роботі каси, формуванню помилкових звітів і т.д
Після закриття зміни автоматично формується Z-звіт і в її рамках більше не можливо буде виконувати дії. Для продовження роботи потрібно відкрити нову касову зміну.
- якщо тіло запиту залишити порожнім, то всі дані по Z-звіту будуть сформовані на боці серверу checkbox (рекомендовано)
- у випадку заповнення даних звіту у тілі запиту він сформується у тому вигляді, в якому ви його заповнили (з усіма можливими помилками в даних).
При формуванні звіту на стороні інтеграції - перевірка коректності розрахунку оборотів та сум продажу на стороні серверу checkbox не виконується!
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
або
{
"skip_client_name_check": <true/false, флаг деактивації/активації перевірки програми-клієнта, через яку відкривали зміну. Дана перевірка допомагає уникнути помилок в роботі у випадку, якщо ваш клієнт паралельно з API задумає скористатись локальним офлайн агентом Checkbox Kasa, що є неприпустимим та може мати негативні наслідки у вигляді поломки каси. За замовчуванням має лишатись false>,
"report": {
"id": "<унікальний ідентифікатор звіту у форматі UUID>",
"serial": <порядковий номер звіту>,
"payments": [
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"provider_type": <у разі застосування технології TAPXPHONE, дане поле буде заповнено автоматично. Можливі значення: `TAPXPHONE`, `POSCONTROL`, `TERMINAL`>,
"code": <код способу оплати>,
"label": "<текстовий опис, який має містити назву форми оплати. Наприклад, Готівка або Картка>",
"sell_sum": <сума продажів з поточною форомою оплати у копійках>,
"return_sum": <сума повернень з поточною форомою оплати у копійках>,
"service_in": <сума службових внесень з поточною форомою оплати у копійках>,
"service_out": <сума службових винесень з поточною форомою оплати у копійках>,
"cash_withdrawal": <сума операцій з видачі готівкових коштів у копійках>,
"cash_withdrawal_commission": <сума комісійних нарахувань по операціям з видачі готівкових коштів у копійках>
},
{
<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>
}
],
"taxes": [
{
"code": <цифровий код податкової ставки>,
"label": "<назва податкової ставки>",
"symbol": "<літерний код податкової ставки>",
"rate": <розмір податкової ставки у відсотках>,
"extra_rate": <розмір додаткового збору у відсотках>,
"sell_sum": <сума податку усіх чеків продажу у копійках>,
"return_sum": <загальний оборот по податку усіх чеків продажу в копійках у рамках зміни>,
"sales_turnover": <загальний оборот по податку усіх чеків продажу в копійках у рамках зміни>,
"returns_turnover": <загальний оборот по податку усіх чеків повернення в копійках у рамках зміни>,
"setup_date": "<мітка часу встановлення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>"
"included": <true/false, тип податку вкладений/накладений)>
"no_vat": <true/false, відмітка податкової ставки "Без ПДВ">
}
],
"sell_receipts_count": <кількість чеків продажу>,
"return_receipts_count": <кількість чеків повернення>,
"cash_withdrawal_receipts_count": <кількість чеків по операціям з видачі готівкових коштів>,
"last_receipt_id": "<унікальний ідентифікатор останнього чеку в рамках зміни у форматі UUID>",
"initial": <баланс каси у копійках на момент відкриття зміни>,
"balance": <баланс каси у копійках на момент створення звіту>,
"sales_round_up": <сума заокруглень в більшу сторону в чеках продажу, створених за поточну зміну>,
"sales_round_down": <сума заокруглень в меншу сторону в чеках продажу, створених за поточну зміну>,
"returns_round_up": <сума заокруглень в більшу сторону в чеках повернення, створених за поточну зміну>,
"returns_round_down": <сума заокруглень в меншу сторону в чеках повернення, створених за поточну зміну>,
"created_at": "<мітка часу створення звіту у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>"
},
"fiscal_code": "<фіскальний код звіту (тільки для створення звіту у офлайн режимі)>",
"fiscal_date": "<фіскальна дата звіту (тільки для створення звіту у офлайн режимі)>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/shifts/close' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d ''
¶ Response body
{
"id": "cec5dd7e-837c-46c6-a0ba-03a61cd11111",
"serial": 43,
"status": "CLOSING",
"z_report": {
"id": "da420f19-6b8c-4986-94ee-072e7ae11111",
"serial": 43,
"is_z_report": true,
"payments": [
{
"id": "36a774ed-f61c-4012-93f2-f9b1ed011111",
"code": null,
"type": "CASH",
"provider_type": null,
"label": "Готівка",
"sell_sum": 16420,
"return_sum": 0,
"service_in": 10000,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
},
{
"id": "19b3a9d5-4535-47d6-a119-12a58d311111",
"code": null,
"type": "CASHLESS",
"provider_type": null,
"label": "Картка",
"sell_sum": 56300,
"return_sum": 0,
"service_in": 0,
"service_out": 20000,
"cash_withdrawal": 20000,
"cash_withdrawal_commission": 0
}
],
"taxes": [
{
"id": "c7a3936a-b7a3-439b-ada3-a79ecc311111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"sell_sum": 11617,
"return_sum": 0,
"sales_turnover": 56300,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"setup_date": "2023-09-27T07:57:17.436553+00:00"
},
{
"id": "5e4428e3-5bb0-4335-9b9c-50dcc5911111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"setup_date": "2023-11-03T10:19:06.625503+00:00"
},
{
"id": "bdac00d5-62fc-4770-9aff-ebb2f9411111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"setup_date": "2023-09-27T07:57:32.979471+00:00"
},
{
"id": "509f8286-fa84-4116-845c-a56815611111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 16417,
"returns_turnover": 0,
"no_vat": true,
"advanced_code": null,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"setup_date": "2023-09-27T07:57:34.983722+00:00"
}
],
"sell_receipts_count": 2,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 1,
"transfers_count": 0,
"transfers_sum": 0,
"balance": 6420,
"initial": 0,
"sales_round_up": 3,
"sales_round_down": 0,
"returns_round_up": 0,
"returns_round_down": 0,
"created_at": "2023-11-06T15:40:16.662236+00:00",
"updated_at": null,
"discounts_sum": 5583,
"extra_charge_sum": 0,
"transaction_fail": false
},
"opened_at": "2023-11-06T14:41:30.108678+00:00",
"closed_at": null,
"initial_transaction": {
"id": "1bde6e04-31e6-41d3-9a65-4b8d46511111",
"type": "SHIFT_OPEN",
"serial": 157,
"status": "DONE",
"request_signed_at": "2023-11-06T14:41:30.171706+00:00",
"request_received_at": "2023-11-06T14:41:30.214959+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-DQYjfj",
"offline_id": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.240628+00:00",
"original_datetime": "2023-11-06T14:41:30.108678+00:00",
"previous_hash": "01bec2834cba96d53bd8f930a3d6acc8a29789a70dce728ea28aa991b7111111"
},
"closing_transaction": {
"id": "835c2736-2b3d-48fe-a697-83e104c11111",
"type": "Z_REPORT",
"serial": 161,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": null,
"created_at": "2023-11-06T15:40:16.662236+00:00",
"updated_at": null,
"original_datetime": "2023-11-06T15:40:16.662236+00:00",
"previous_hash": "beb28cb1d8b984216ab6d41b05cceb19d7cb775fc17a8923a77b9a1634d11111"
},
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T15:40:16.662236+00:00",
"balance": {
"initial": 0,
"balance": 6420,
"cash_sales": 16420,
"card_sales": 56300,
"discounts_sum": 5583,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 10000,
"service_out": 20000,
"updated_at": "2023-11-06T15:31:38.531434+00:00"
},
"taxes": [
{
"id": "b3820b97-9c13-4b6f-aa5b-98cdb3411111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 11617,
"returns": 0,
"sales_turnover": 56300,
"returns_turnover": 0
},
{
"id": "ccf0e3cb-0286-423f-a278-df9f3c611111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "22abcf11-e9b2-4f40-8c46-1a3b5c11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4828cb2f-db1f-4174-acce-77e056111111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 16417,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-04T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
}
"z_report" - блок з інформацією по Z-звіту
- "id" - унікальний ідентифікатор Z-звіту у форматі UUID
- "serial" - порядковий номер Z-звіту
- "is_z_report" - флаг true/false, який визначає, чи є даний звіт Z-звітом. Для Z-звіту завжди true.
- "sell_receipts_count" - кількість чеків продажу
- "return_receipts_count" - кількість чеків повернення
- "cash_withdrawal_receipts_count" - кількість чеків по операціям з видачі готівкових коштів
- "balance" - баланс каси у копійках на момент створення звіту
- "initial" - баланс каси у копійках на момент відкриття зміни
- "sales_round_up" - сума заокруглень в більшу сторону в чеках продажу, створених за поточну зміну
- "sales_round_down" - сума заокруглень в меншу сторону в чеках продажу, створених за поточну зміну
- "returns_round_up" - сума заокруглень в більшу сторону в чеках повернення, створених за поточну зміну
- "returns_round_down" - сума заокруглень в меншу сторону в чеках повернення, створених за поточну зміну
- "created_at" - мітка часу створення звіту у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних звіту у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm.
- "discounts_sum" - сума знижок за зміну
- "extra_charge_sum" - сума надбавок за зміну
- "transaction_fail" - true/false, флаг успішної транзакції - false, помилкової - true
Інші параметри відповіді аналогічні параметрам відповіді метода створення чека, але при цьому буде змінено "status" зміни на кінцевий "CLOSING" або "CLOSED".
¶ Чеки
¶ Внесення та винесення готівки
Внесення і видача готівки – службові (нефіскальні) операції, коли ви вносите розмінні гроші в касу або інкасуєте готівку.
Метод /api/v1/receipts/service дозволяє створити чек службового внесення або вилучення готівки. Для коректного створення такого чеку потрібно обов'язково передати у тілі запиту параметри "id" (UUID чека), "type" (має бути CASH за замовчуванням) та "value" (сума в копійках). Назва типу оплати проставляється автоматично за замовчуванням як "Готівка".
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<генерація та передача UUID чека на стороні інтеграції є обов'язковою>",
"payment": {
"type": "CASH",
"value": <сума у копійках, для створення чеку службового вилучення перед сумою має бути - >
},
"custom": {
"html_global_header": "<глобальний хедер для чеків html/pdf візуалізацій>",
"html_global_footer": "<глобальний футер для чеків html/pdf візуалізацій>",
"html_body_style": "<фон сторінки з чеком>",
"html_receipt_style": "<стиль блоку з чеком>",
"html_ruler_style": "<стиль роздільника з зірочками між блоками чеку",
"html_light_block_style": "<стиль світлих блоків, це весь підвал чеку та клітинки з вартістю та кількістю>",
"text_global_header": "<глобальний хедер для чеків png/txt візуалізацій>",
"text_global_footer": "<глобальний футер для чеків png/txt візуалізацій>"
}
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/receipts/service' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id": "a694a13a-aaa9-46bb-930b-8bc206311111", "payment": { "type": "CASH", "value": 10000}, "custom": { "html_body_style": "background: rgb(35,32,87);\nbackground: linear-gradient(45deg, rgba(35,32,87,1) 0%, rgba(62,62,138,1) 44%, rgba(0,212,255,1) 100%);"}}'
¶ Response body
{
"id": "a694a13a-aaa9-46bb-930b-8bc206311111",
"type": "SERVICE_IN",
"transaction": null,
"serial": 84,
"status": "DONE",
"goods": [],
"payments": [
{
"type": "CASH",
"pawnshop_is_return": null,
"value": 10000,
"label": "Готівка"
}
],
"total_sum": 10000,
"sum": 10000,
"total_payment": 10000,
"total_rest": 0,
"rest": 0,
"round_sum": null,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2023-11-06T14:51:03.221535+00:00",
"updated_at": "2023-11-06T14:51:03.221535+00:00",
"taxes": [],
"discounts": [],
"order_id": null,
"header": null,
"footer": null,
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"shift": {
"id": "cec5dd7e-837c-46c6-a0ba-03a61cd11111",
"serial": 43,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-06T14:41:30.108678+00:00",
"closed_at": null,
"initial_transaction": {
"id": "1bde6e04-31e6-41d3-9a65-4b8d46511111",
"type": "SHIFT_OPEN",
"serial": 157,
"status": "DONE",
"request_signed_at": "2023-11-06T14:41:30.171706+00:00",
"request_received_at": "2023-11-06T14:41:30.214959+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-DQYjfj",
"offline_id": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.240628+00:00",
"original_datetime": "2023-11-06T14:41:30.108678+00:00",
"previous_hash": "01bec2834cba96d53bd8f930a3d6acc8a29789a70dce728ea28aa991b7111111"
},
"closing_transaction": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.244566+00:00",
"balance": {
"initial": 0,
"balance": 10000,
"cash_sales": 0,
"card_sales": 0,
"discounts_sum": 0,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 10000,
"service_out": 0,
"updated_at": "2023-11-06T14:51:03.221535+00:00"
},
"taxes": [
{
"id": "b3820b97-9c13-4b6f-aa5b-98cdb3411111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "ccf0e3cb-0286-423f-a278-df9f3c611111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "22abcf11-e9b2-4f40-8c46-1a3b5cb11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4828cb2f-db1f-4174-acce-77e056111111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-04T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека (SERVICE_IN/SERVICE_OUT (СЛУЖБОВЕ ВНЕСЕННЯ/СЛУЖБОВЕ ВИЛУЧЕННЯ)
"transaction" - інформація про транзакцію чека (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"serial" - порядковий номер чека
"status" - статус чека
"goods" - блок даних з переліком товарів (для службового чека перелік буде пустим)
"payments" - блок даних з інформацією про платежі:
- "type" - тип платежу (для службового чека внесення/вилучення готівки має бути
CASH) - "pawnshop_is_return" - параметр, який визначає даний чек як чеки видачі коштів ломбарду (за замовчуванням для звичайних чеків, створених не для ломбардів, має бути
null) - "value" - сума внесення/винесення у копійках. Для формування чеку винесення готівки потрібно перед сумою вказати знак
-
"label" - текстова мітка, яка буде розміщена на чеку
"total_sum" та "sum" - сума вартості товарів у чеку
"total_rest" та "rest" - сума здачі
"total_payment" - сума оплати за товари у чеку
"round_sum" - сума округлення
"fiscal_code" - фіскальний номер чека (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"fiscal_date" - фіскальна дата, з якою чек буде зареєстровано у ДПС (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"delivered_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час доставки чека у ДПС (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"created_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час створення чека
"updated_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час останнього оновлення даних чека (якщо чек щойно створено або інформація по ньому не оновлювалась, то дане значення буде null)
"taxes" - блок даних про податки (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція нефіскальна і до неї не застосовуються податки)
"discounts" - блок даних про знижки (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція нефіскальна і до неї не застосовуються знижки)
"order_id" - ідентифікатор замовлення у форматі UUID (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція не являє собою замовлення)
"header" - хедер чека (для службового чека внесення/вилучення готівки за замовчуванням null)
"footer" - футер чека (для службового чека внесення/вилучення готівки за замовчуванням null)
"barcode" - штрих-код (для службового чека внесення/вилучення готівки за замовчуванням null)
"custom" - блок з даними кастомізації чека (lокладніше про параметри, які можуть відображатись в даному блоці можете дізнатись в розділі Візуалізація чека)
"is_created_offline" - ознака режиму (онлайн/офлайн) у якому був створений чек. true - чек створений у офлайні, false - чек створений у онлайні.
"is_sent_dps" - ознака відправки чека у ДПС (для чека внесення/вилучення готівки за замовчуванням false, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"sent_dps_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час відправки чека у ДПС (для чека внесення/вилучення готівки за замовчуванням null, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"tax_url" - посилання на чек у кабінеті ДПС (для чека внесення/вилучення готівки за замовчуванням null, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"related_receipt_id" - id пов'язаного чека у форматі UUID. Цим параметром можна пов'язати між собою чек продажу та повернення, щоб завжди мати змогу дізнатися, на основі якого конкретно чека продажу ви робили повернення (для службового чека даний параметр не актуальний та за замовчуванням null)
"technical_return" - параметр, який відповідає за мітку технічного повернення на чеку. Технічне повернення - це повернення чеку продажу у випадку, коли чек продажу сформований невірно і для коригування балансу виникає змога провести повернення (для службового чека даний параметр не актуальний та за замовчуванням null)
"stock_code" - блок даних, який стосується операцій валютного обміну (не актуально для службового чека)
"currency_exchange" - блок даних, який стосується операцій валютного обміну (не актуально для службового чека)
"control_number" - контрольне число. Заповнюється сервером для фіскальних чеків (службовий матиме за замовчуванням даний параметр null)
Блоки даних з інформацією про:
- зміну
- баланси
- податки
- касу
- касира
- дозволи касира
¶ Продаж та повернення
¶ Онлайн
Чек можна створити як у офлайн, так і у онлайн режимі. Метод /api/v1/receipts/sell призначений для створення чека як у онлайн, так і у офлайн режимі (але без можливості явно вказати офлайн фіскальний код або офлайн фіскальну дату. Якщо каса у офлайні, то сервер автоматично підставить поточну дату та вільний офлайн код). Метод /api/v1/receipts/sell-offline призначений для створення чека у офлайні і дозволяє явно вказати як фіскальну дату, так і фіскальний код.
Мінімальний набір даних для створення чека продажу включає в себе UUID чека, код товару, назву товару, ціну, кількість, тип оплати та суму оплати. Але взагалі чек може містити багато додаткових параметрів, які будуть описані у прикладі.
Запит на отримання інформації про чек необхідно виконувати не раніше, ніж за 50 мс після отримання сервером Checkbox запиту на його створення та обробку.
Для створення чека повернення використовується той самий метод, що і для чека продажу, але при цьому в блоці даних про товар передається значення "is_return": true, яке визначає, що цей товар має бути повернуто. Додатково при цьому можна передавати UUID чека продажу в полі "related_receipt_id".
Наявний rate-limit дозволяє передавати не більше 2х чеків за одну секунду. При перевищені ліміту - передача чеків по касі буде заблоковано на 5 секунд, після чого відновиться робота каси та rate-limit. Він діє індивідуально на кожну окрему касу, а не на IP-адресу.
При систематичному порушенні ліміту ми зв'яжемось за контактами, вказаними в налаштуваннях особистого кабінету організації для вирішення питання порушення наявних лімітів.
Для створення чека з оплатою за посиланням рекомендуємо скористатись методами створення інвойсу на оплату із подальшою фіскалізацією.
Для участі в Національному кешбеці обовʼязковою умовою є передача:
- в масиві "goods":
...
"barcode": "<Штрих-код товару>"
...
- в масиві "payments":
...
"rrn": "<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції>",
"terminal": "<інформація про платіжний термінал>",
"acquirer_and_seller": "<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати>",
...
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<генерація та передача UUID v4 чека на стороні інтеграції є обов'язковою>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":[
{
"good":{
"code": "<Код товару>",
"name": "<Назва товару>",
"price": <ціна у копійках>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"barcode": "<Штрих-код товару>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<Хедер товару 1>",
"footer": "<Футер товару 1>",
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID v4 товару (якщо ви користуєтесь залишками на сайті checkbox)>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"is_winnings_payout": <флаг true/false, що визначає, чи це виплата виграшу>,
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>"
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"total_sum":<сума вартості товару>
},
{
"good":
{<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>}
}],
"delivery":{
"email": "<e-mail клієнта для відправки копії чека>",
"emails": ["<e-mail клієнта для відправки копії чека 1>","<e-mail клієнта для відправки копії чека 2>"],
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок через кому, що застосовуються для товару (якщо їх >1). Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"bonuses":[
{
"bonus_card": <інформація про бонусну картку покупця, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"value": <інформація про накопичені бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"additional_info": <додаткова інформація про бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>
}],
"payments":[{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"provider_type": "<у разі застосування технології TAPXPHONE, дане поле буде заповнено автоматично. Можливі значення: `TAPXPHONE`, `POSCONTROL`, `TERMINAL`>",
"value": <сума оплати у копійках>,
"commission": <комісія (тільки для безготівкових платежів)>,
"label": "<текстова назва форми оплати>",
"card_mask": "<маска карти (не більше 19 символів) (тільки для безготівкових платежів)>",
"bank_name": "<назва банку (тільки для безготівкових платежів)>",
"auth_code": "<код авторизації банківської операції (тільки для безготівкових платежів)>",
"rrn": "<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)>",
"payment_system": "<платіжна система (тільки для безготівкових платежів)>",
"owner_name": "<ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)>",
"terminal": "<інформація про платіжний термінал (тільки для безготівкових платежів)>",
"acquirer_and_seller": "<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)>",
"receipt_no": "<номер банківського чека (тільки для безготівкових платежів)>",
"signature_required": <true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
"tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
},
{<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>}],
"rounding": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"order_id": "<UUID v4 замовлення (вказується у випадку роботи з API у режимі замовлень). НЕ ДЛЯ ПЕРЕДАЧІ НОМЕРУ ЗАМОВЛЕНЬ ІЗ ФРОНТ-СИСТЕМ>",
"related_receipt_id": "<UUID v4 пов'язаного фіскального чеку (використовується опціонально для контролю послідовності)>",
"previous_receipt_id": "<UUID v4 попереднього фіскального чеку (використовується опціонально для контролю послідовності)>",
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"is_pawnshop": <true/false флаг, яким можна позначити, що даний чек є чеком ломбарду>,
"custom": {
"html_global_header": "<глобальний хедер для чеків html/pdf візуалізацій>",
"html_global_footer": "<глобальний футер для чеків html/pdf візуалізацій>",
"html_body_style": "<фон сторінки з чеком>",
"html_receipt_style": "<стиль блоку з чеком>",
"html_ruler_style": "<стиль роздільника з зірочками між блоками чеку",
"html_light_block_style": "<стиль світлих блоків, це весь підвал чеку та клітинки з вартістю та кількістю>",
"text_global_header": "<глобальний хедер для чеків png/txt візуалізацій>",
"text_global_footer": "<глобальний футер для чеків png/txt візуалізацій>"
}
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/receipts/sell' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id": "e51c07c6-8e8a-44bf-b594-750f7e9e3a95", "cashier_name": "Тестовий касир", "departament": "Тестова каса", "goods":[ { "good":{ "code": "500", "name": "Вино ігристе біле Вінтаж де Локсарел БН Резерва, Loxarel брют 0,125", "price": 19500, "tax": [1], "barcode": "2000000000009", "excise_barcode": "AENX936821", "uktzed": "2204109300" }, "good_id": "94433d09-c47e-48a1-8010-570099ee52e4", "quantity": 1000 }, { "good":{ "code": "501", "name": "Ромовий напій Captain Morgan Spiced Gold, 35%, 0,5 л (437392)", "price": 20900, "tax": [1], "barcode": "5000281025360", "excise_barcodes": ["ACVI735229","ACVE735293"], "uktzed": "2208906900" }, "good_id": "ce7a84e9-ff67-4c25-8d12-875134d650fe", "quantity": 2000 }], "delivery":{ "email": "[email protected]", "phone": "380500521111" }, "discounts":[{ "type": "DISCOUNT", "mode": "VALUE", "value": 5000, "tax_code": 1, "name": "Знижка" }], "payments":[{ "type": "CASHLESS", "value": 56300, "label": "Картка", "card_mask": "XXXXXXXXXXXX6734", "bank_name": "PrivetBank", "auth_code": "078111", "rrn": "305817547111", "payment_system": "VISA", "owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO", "terminal": "S1LF0EUR", "acquirer_and_seller": "PrivetBank", "receipt_no": "1", "signature_required": false }], "rounding": false, "header": "Якийсь хедер", "footer": "Якийсь футер", "custom": { "html_body_style": "background: rgb(35,32,87);\nbackground: linear-gradient(45deg, rgba(35,32,87,1) 0%, rgba(62,62,138,1) 44%, rgba(0,212,255,1) 100%);"}}'
¶ Response body
{
"id": "36ba6627-379d-4fe9-bcce-7e06ad511111",
"type": "SELL",
"transaction": {
"id": "058542fc-7437-40a4-9d8a-e44480411111",
"type": "RECEIPT",
"serial": 185,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": null,
"created_at": "2023-11-29T12:07:27.008327+00:00",
"updated_at": "2023-11-29T12:07:27.008327+00:00",
"original_datetime": "2023-11-29T12:07:27.008327+00:00",
"previous_hash": "cf0e47fef12156bd8b21a77610951cb2928c83dabea47e6b3b5d1cb31a211111"
},
"serial": 92,
"status": "CREATED",
"goods": [
{
"good": {
"code": "500",
"barcode": "2000000000009",
"name": "Вино ігристе біле Вінтаж де Локсарел БН Резерва, Loxarel брют 0,125",
"excise_barcodes": [
"AENX936821"
],
"header": null,
"footer": null,
"uktzed": "2204109300",
"price": 19500
},
"good_id": "94433d09-c47e-48a1-8010-570099e11111",
"sum": 19500,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "f6dddf31-fefd-437b-9c9f-75083d11111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 3095,
"extra_value": 929
}
],
"discounts": []
},
{
"good": {
"code": "501",
"barcode": "5000281025360",
"name": "Ромовий напій Captain Morgan Spiced Gold, 35%, 0,5 л (437392)",
"excise_barcodes": [
"ACVI735229",
"ACVE735293"
],
"header": null,
"footer": null,
"uktzed": "2208906900",
"price": 20900
},
"good_id": "ce7a84e9-ff67-4c25-8d12-875134d11111",
"sum": 41800,
"quantity": 2000,
"is_return": false,
"taxes": [
{
"id": "e74a8795-2b05-4024-aaf9-bf385b11111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 6635,
"extra_value": 1990
}
],
"discounts": []
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 56300,
"commission": null,
"label": "Картка",
"card_mask": "XXXXXXXXXXXX6734",
"bank_name": "PrivetBank",
"auth_code": "078111",
"rrn": "305817547111",
"payment_system": "VISA",
"owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO",
"terminal": "S1LF0EUR",
"acquiring": "PrivetBank",
"acquirer_and_seller": "PrivetBank",
"receipt_no": "1",
"signature_required": false,
"tapxphone_terminal": null
}
],
"total_sum": 56300,
"sum": 56300,
"total_payment": 56300,
"total_rest": 0,
"rest": 0,
"round_sum": 0,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2023-11-29T12:07:27.008327+00:00",
"updated_at": null,
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e10111111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 8936,
"extra_value": 2680
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 5000,
"tax_code": null,
"tax_codes": [
1
],
"name": "Знижка",
"privilege": null,
"sum": -5000
}
],
"order_id": null,
"header": "Якийсь хедер",
"footer": "Якийсь футер",
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"service_currency_exchange": [],
"shift": {
"id": "16a4caf5-abf7-46b3-9729-1aab84f11111",
"serial": 47,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-29T12:04:20.574746+00:00",
"closed_at": null,
"initial_transaction": {
"id": "08c48ca9-9a6d-4c70-b114-febf46f11111",
"type": "SHIFT_OPEN",
"serial": 182,
"status": "DONE",
"request_signed_at": "2023-11-29T12:04:20.651192+00:00",
"request_received_at": "2023-11-29T12:07:11.634244+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-Z11111",
"offline_id": "TEST-Z11111",
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:07:11.665850+00:00",
"original_datetime": "2023-11-29T12:04:20.574746+00:00",
"previous_hash": "f282bba44d4396cb7fc611ac3ac87d2b861e554dc97c755ac7b9ef2783311111"
},
"closing_transaction": null,
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:04:20.685550+00:00",
"balance": {
"initial": 6420,
"balance": 6420,
"cash_sales": 0,
"card_sales": 112600,
"discounts_sum": 10000,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2023-11-29T12:07:27.008327+00:00"
},
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e1011111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 23234,
"returns": 0,
"sales_turnover": 112600,
"returns_turnover": 0
},
{
"id": "ee78ddd7-979f-419b-990e-529871211111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "2df43a8c-be79-41b8-9f78-1bb1c0c11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "351551ce-4be2-4581-8184-df53b7011111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST51111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-14T22:55:08+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека, SERVICE_IN/SERVICE_OUT (СЛУЖБОВЕ ВНЕСЕННЯ/СЛУЖБОВЕ ВИЛУЧЕННЯ)
"transaction" - інформація про транзакцію чека.
- "id" - унікальний ідентифікатор транзакції у форматі UUID
- "type" - тип транзакції.
- "serial" - порядковий номер транзакції
- "status" - статус транзакції. Може приймати значення CREATED/PENDING/SIGNED/DELIVERED/DONE(або ERROR) (СТВОРЕНА/НА ПІДПИСАННІ/ПІДПИСАНА/ВІДПРАВЛЕНА/ВИКОНАНА(або ПОМИЛКА))
- "request_signed_at" - мітка часу підписання транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "request_received_at" - мітка часу отримання транзакції сервером ДПС у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Якщо запит ще не був доставлений у податкову, то дане значення буде null
- "response_status" - статус, отриманний від сервера ДПС у відповідь на запит. Успішний запит матиме статус OK
- "response_error_message" - текстовий опис помилки, при отриманні її від сервера ДПС у відповідь на запит.
- "response_id" - ідентифікатор відповіді на запит від сервера ДПС (фіскальний номер)
- "offline_id" - офлайн ідентифікатор відповіді на запит від сервера ДПС (фіскальний номер). Матиме значення null якщо транзакція була створена у онлайн режимі.
- "created_at" - мітка часу створення транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "previous_hash" - хеш попередньої транзакції
"serial" - порядковий номер чека
"status" - статус чека
"goods" - блок даних з переліком товарів. - "code" - код товару (обов'язковий параметр)
- "barcode" - штрих-код товару
- "name" - назва товару (обов'язковий параметр)
- "excise_barcodes" - цифрове позначення штихового коду акцизної марки, якщо їх >1
- "header" - хедер товару
- "footer" - футер товару
- "uktzed" - код уктзед
- "price" - ціна товару
- "good_id" - ідентифікатор товару у форматі UUID
- "sum" - сума у копійках
- "quantity" - кількість у тисячах. 1 шт = 1000
- "is_return" - true/false флаг який помічає обраний чек як чек повернення
"taxes" - блок даних з інформацією про податкові ставки, які використовувались для товару в чеку
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "value" - розмір податку
- "extra_value" - розмір додаткового збору (наприклад, для акцизу)
"discounts" - блок даних про знижки по товару.
- "type" - тип знижки "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)
- "mode" - режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)
- "value" - розмір знижки
- "tax_code"/"tax_codes" - коди податкових ставок, які використовуються для товару і були вказані при створенні знижки
- "name" - назва знижки/надбавки
- "sum" - сума знижки/надбавки
"payments" - блок даних з інформацією про платежі
- "type" - тип платежу CASH/CASHLESS
- "pawnshop_is_return" - параметр, який визначає даний чек як чеки видачі коштів ломбарду. За замовчуванням для звичайних чеків, створених не для ломбардів, має бути null
- "value" - сума внесення/винесення у копійках. Для формування чеку службового винесення потрібно перед сумою вказати
- "label" - текстова мітка, яка буде розміщена на чеку
- "code" - номер оплати (тільки для безготівкових платежів)
- "commission" - комісія (тільки для безготівкових платежів)
- "card_mask" - маска карти (не більше 19 символів) (тільки для безготівкових платежів)
- "bank_name" - назва банку (тільки для безготівкових платежів)
- "auth_code" - код авторизації банківської операції (тільки для безготівкових платежів)
- "rrn" - Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)
- "payment_system" - платіжна система (тільки для безготівкових платежів)
- "owner_name" - ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)
- "terminal" - інформація про платіжний термінал (тільки для безготівкових платежів)
- "acquirer_and_seller" - ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)
- "receipt_no" - номер банківського чека (тільки для безготівкових платежів)
- "signature_required" - true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира
"total_sum" та "sum" - сума вартості товарів у чеку
"total_payment" - сума оплати за товари у чеку
"rest" та "total_rest" - сума здачі
"fiscal_code" - фіскальний номер чека. При створенні чека у онлайні чек отримує фіскальний код згодом, після обробки та передачі його у ДПС, яка у відповідь призначає чеку офлайн код
"fiscal_date" - фіскальна дата, з якою чек буде зареєстровано у ДПС. Чек отримає фіскальну дату після завершення обробки.
"delivered_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час доставки чека у ДПС.
"created_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час створення чека
"updated_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час останнього оновлення даних чека. Якщо чек тільки що створено або якщо інформація по ньому не оновлювалась, то дане значення буде null
"taxes" - блок даних про податки, які використовувались для всього чеку
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "value" - розмір податку
- "extra_value" - розмір додаткового збору (наприклад, для акцизу)
"discounts" - блок даних про знижки, які застосовувались до всього чеку.
- "type" - тип знижки "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)
- "mode" - режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)
- "value" - розмір знижки
- "tax_code"/"tax_codes" - коди податкових ставок, які використовуються для товару і були вказані при створенні знижки
- "name" - назва знижки/надбавки
- "sum" - сума знижки/надбавки
"order_id" - ідентифікатор замовлення у форматі UUID (використовується при роботі з API замовлень).
"header" - хедер чека.
"footer" - футер чека.
"barcode" - штрих-код чека.
"custom" - блок з даними кастомізації чека. Докладніше про параметри, які можуть відображатись в даному блоці можете дізнатись тутcustom_check
"is_created_offline" - ознака режиму (онлайн/офлайн) у якому був створений чек. true - чек створений у офлайні, false - чек створений у онлайні.
"is_sent_dps" - ознака відправки чека у ДПС.
"sent_dps_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час відправки чека у ДПС.
"tax_url" - посилання на чек у кабінеті ДПС.
"related_receipt_id" - id пов'язаного чека у форматі UUID. Цим параметром можна пов'язати між собою чек продажу та повернення, щоб завжди мати змогу дізнатися, на основі якого конкретно чека продажу ви робили повернення.
"technical_return" - параметр, який відповідає за мітку технічного повернення на чеку. Технічне повернення - це повернення чеку продажу у випадку, коли чек продажу сформований невірно і для коригування балансу виникає змога провести повернення.
"currency_exchange" - блок даних, який стосується операцій валютного обміну. Не є актуальним для звичайного чека.
"shift" - блок з даними про поточну зміну
- "id" - унікальний ідентифікатор зміни у форматі UUID
- "serial" - порядковий номер зміни
- "status" - статус зміни. Може мати значення CREATED/OPENED/CLOSING/CLOSED (СТВОРЕНА/ВІДКРИТА/ЗАКРИВАЄТЬСЯ/ЗАКРИТА)
- "z_report" - блок з інформацією по z-звіту касової зміни. Для відкритої зміни це значення завжди буде null
- "opened_at" - мітка часу відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "closed_at" - мітка часу закриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Для відкритої зміни завжди буде null
"initial_transaction" - блок з інформацією про першу транзакцію обраної зміни
- "id" - унікальний ідентифікатор транзакції у форматі UUID
- "type" - тип транзакції. Для першої транзакції зміни це значення завжди буде SHIFT_OPEN
- "serial" - порядковий номер транзакції
- "status" - статус транзакції. Може приймати значення CREATED/PENDING/SIGNED/DELIVERED/DONE(або ERROR) (СТВОРЕНА/НА ПІДПИСАННІ/ПІДПИСАНА/ВІДПРАВЛЕНА/ВИКОНАНА(або ПОМИЛКА))
- "request_signed_at" - мітка часу підписання запиту на відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "request_received_at" - мітка часу отримання запиту на відкриття зміни сервером ДПС у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Якщо запит ще не був доставлений у податкову, то дане значення буде null
- "response_status" - статус, отриманний від сервера ДПС у відповідь на запит. Успішний запит матиме статус OK
- "response_error_message" - текстовий опис помилки, при отриманні її від сервера ДПС у відповідь на запит.
- "response_id" - ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер)
- "offline_id" - офлайн ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер). Матиме значення null якщо транзакція відкриття зміни була створена у онлайн режимі.
- "created_at" - мітка часу створення транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "previous_hash" - хеш попередньої транзакції
"closing_transaction" - блок даних про останню транзакцію у зміні. Для відкритої зміни прийматиме значення null. Якщо зміна закрита, то даний блок міститиме набір даних стосовно останньої транзакції у зміні аналогічний до "initial_transaction"
"created_at" - мітка часу створення зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - мітка часу останнього оновлення даних зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"balance" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
- "initial" - початковий баланс готівкових коштів
- "balance" - поточний баланс готівкових коштів
- "cash_sales" - сума готівкових продажів
- "card_sales" - сума безготівкових продажів
- "cash_returns" - сума готівкових повернень
- "card_returns" - сума безготівкових повернень
- "service_in" - сума службових внесень готівкових
- "service_out" - сума службових вилучень готівкових коштів
- "updated_at" - мітка часу останнього оновлення даних балансу зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "sales" - сума податку усіх чеків продажу у копійках
- "returns" - сума податку усіх чеків повернення у копійках
- "sales_turnover" - сума продажів з цією податковою ставкою (оборот) у копійках
- "returns_turnover" - сума повернень з цією податковою ставкою (оборот) у копійках
"cash_register" - блок даних з інформацією про касу, на якій було створено чек
- "id": - унікальний ідентифікатор каси у форматі UUID
- "fiscal_number" - фіскальний номер каси
- "active" - статус каси АКТИВНА/НЕАКТИВНА (true/false)
- "created_at" - дата реєстрації каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - дата останньої зміни даних обраної каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"cashier" - блок даних з інформацією про касира, який створив чек
- "id" - унікальний ідентифікатор касира у форматі uuid;
- "full_name" - ПІБ касира, вказане користувачем при його реєстрації;
- "nin" - ідентифікаційний код касира у ДПС;
- "key_id" - ідентификатор ключа (печатки) ЕЦП касира;
- "signature_type"- тип агента підпису чеків, який використовується касиром. Наразі актуальними є типи CLOUD_SIGNATURE_3 для ключів (печаток), підписуючих чеки на захищеному хмарному сховищі та AGENT, для ключів (печаток), які виконують підписання чеків локально, за допомогою програми Чекбокс підпис або плагіну підпису в браузері клієнтського ПК;
- "permissions" - перелік додаткових дозволів для обраного касира. У прикладі вище - "orders": true, тобто, касиру дозволено користуватися функціоналом API у режимі роботи з замовленнями. Опис цього функціоналу ви зможете знайти у відповідному розділі даної документації;
- "created_at" - дата реєстрації касира;
- "updated_at" - дата останнього внесення змін у обліковий запис даного касира;
- "certificate_end" - дата завершення строку дії електронного ключа (печатки) касира;
- "blocked" - інформація про чинність сертифікату ключа (печатки) касира. Якщо на агенті підпису активна перевірка сертифікату за OSCP протоколом, то у випадку, коли користувач скасовує електронний ключ (печатку), в цьому полі буде відповідне повідомлення "blocked": "Сертифікат не чинний (при перевірці за протоколом OCSP)". Якщо ж інформації про блокування ключа (печатки) сервер не має, то за замовчуванням у відповіді сервера буде значення "blocked": null.
"control_number" - контрольне число, яке отримує офлайн чек після обробки сервером
¶ Офлайн
Метод /api/v1/receipts/sell-offline призначений для створення чека у офлайні і дозволяє явно вказати як фіскальну дату, так і фіскальний код.
Перед створенням офлайн чеку касу потрібно перевести у офлайн режим, інакше ви отримаєте від API помилку виду "message": "Cash register should be in manual offline mode!". Метод переходу у офлайн описаний у відповідному розділі сторінки.
Від методу /api/v1/receipts/sell метод /api/v1/receipts/sell-offline відрізняється наявністю полів "fiscal_code" та "fiscal_date", які є обов'язковими та вказуються наприкінці пейлоаду чеку.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<генерація та передача UUID чека на стороні інтеграції є обов'язковою>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":[
{
"good":{
"code": "<Код товару>",
"name": "<Назва товару>",
"price": <ціна у копійках>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"barcode": "<Штрих-код товару>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<Хедер товару 1>",
"footer": "<Футер товару 1>",
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"is_winnings_payout": <флаг true/false, що визначає, чи це виплата виграшу>,
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>"
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"total_sum":<сума вартості товару>
},
{
"good":
{<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>}
}],
"delivery":{
"email": "<e-mail клієнта для відправки копії чека>",
"emails": ["<e-mail клієнта для відправки копії чека 1>","<e-mail клієнта для відправки копії чека 2>"],
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок через кому, що застосовуються для товару (якщо їх >1). Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"bonuses":[
{
"bonus_card": <інформація про бонусну картку покупця, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"value": <інформація про накопичені бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"additional_info": <додаткова інформація про бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>
}],
"payments":[{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"provider_type": "<у разі застосування технології TAPXPHONE, дане поле буде заповнено автоматично. Можливі значення: `TAPXPHONE`, `POSCONTROL`, `TERMINAL`>",
"value": <сума оплати у копійках>,
"commission": <комісія (тільки для безготівкових платежів)>,
"label": "<текстова назва форми оплати>",
"card_mask": "<маска карти (не більше 19 символів) (тільки для безготівкових платежів)>",
"bank_name": "<назва банку (тільки для безготівкових платежів)>",
"auth_code": "<код авторизації банківської операції (тільки для безготівкових платежів)>",
"rrn": "<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)>",
"payment_system": "<платіжна система (тільки для безготівкових платежів)>",
"owner_name": "<ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)>",
"terminal": "<інформація про платіжний термінал (тільки для безготівкових платежів)>",
"acquirer_and_seller": "<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)>",
"receipt_no": "<номер банківського чека (тільки для безготівкових платежів)>",
"signature_required": <true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
"tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
},
{<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>}],
"rounding": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"order_id": "<UUID замовлення (вказується у випадку роботи з API у режимі замовлень). НЕ ДЛЯ ПЕРЕДАЧІ НОМЕРУ ЗАМОВЛЕНЬ ІЗ ФРОНТ-СИСТЕМ>",
"related_receipt_id": "<UUID пов'язаного фіскального чеку (використовується опціонально для контролю послідовності)>",
"previous_receipt_id": "<UUID попереднього фіскального чеку (використовується опціонально для контролю послідовності)>",
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"is_pawnshop": <true/false флаг, яким можна позначити, що даний чек є чеком ломбарду>,
"custom": {
"html_global_header": "<глобальний хедер для чеків html/pdf візуалізацій>",
"html_global_footer": "<глобальний футер для чеків html/pdf візуалізацій>",
"html_body_style": "<фон сторінки з чеком>",
"html_receipt_style": "<стиль блоку з чеком>",
"html_ruler_style": "<стиль роздільника з зірочками між блоками чеку",
"html_light_block_style": "<стиль світлих блоків, це весь підвал чеку та клітинки з вартістю та кількістю>",
"text_global_header": "<глобальний хедер для чеків png/txt візуалізацій>",
"text_global_footer": "<глобальний футер для чеків png/txt візуалізацій>"
},
"fiscal_code": "<невикористаний офлайн код>",
"fiscal_date": "<дача/час фіскалізації чека у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/receipts/sell-offline' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id":"44395b8e-a53d-462d-9c8c-a69d05c11111", "cashier_name":"Тестовий касир", "departament":"Тестова каса", "goods":[ { "good":{ "code":"500", "name":"Вино ігристе біле Вінтаж де Локсарел БН Резерва, Loxarel брют 0,125", "price":19500, "tax":[ 1 ], "barcode":"2000000000009", "excise_barcode":"AENX936821", "uktzed":"2204109300" }, "good_id":"94433d09-c47e-48a1-8010-570099ee52e4", "quantity":1000 }, { "good":{ "code":"501", "name":"Ромовий напій Captain Morgan Spiced Gold, 35%, 0,5 л (437392)", "price":20900, "tax":[ 1 ], "barcode":"5000281025360", "excise_barcodes":[ "ACVI735229", "ACVE735293" ], "uktzed":"2208906900" }, "good_id":"ce7a84e9-ff67-4c25-8d12-875134d650fe", "quantity":2000 } ], "delivery":{ "email":"[email protected]", "phone":"380500521111" }, "discounts":[ { "type":"DISCOUNT", "mode":"VALUE", "value":5000, "tax_code":1, "name":"Знижка" } ], "payments":[ { "type":"CASHLESS", "value":56300, "label":"Картка", "card_mask":"XXXXXXXXXXXX6734", "bank_name":"PrivetBank", "auth_code":"078111", "rrn":"305817547111", "payment_system":"VISA", "owner_name":"CHEREZPLETINNOHUZADYRAISHCHENKO PETRO", "terminal":"S1LF0EUR", "acquirer_and_seller":"PrivetBank", "receipt_no":"1", "signature_required":false } ], "rounding":false, "header":"Якийсь хедер", "footer":"Якийсь футер", "custom":{ "html_body_style":"background: rgb(35,32,87);\nbackground: linear-gradient(45deg, rgba(35,32,87,1) 0%, rgba(62,62,138,1) 44%, rgba(0,212,255,1) 100%);" },"fiscal_code":"TEST-i11111", "fiscal_date":"2023-11-29T14:07:28.000000"}'
¶ Response body
{
"id": "77ccd2a5-a0c6-4328-bb84-b829574bed74",
"type": "SELL",
"transaction": {
"id": "6bd73d21-2a4e-49ab-9471-108b95d48286",
"type": "RECEIPT",
"serial": 187,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": "TEST-iA5fmb",
"created_at": "2023-11-29T12:11:28.569137+00:00",
"updated_at": "2023-11-29T12:11:28.569137+00:00",
"original_datetime": "2023-11-29T14:07:28+00:00",
"previous_hash": "5db006ff9126fcb39146c017f4f8d7e8668dee4220dce5136ff795716c483f73"
},
"serial": 93,
"status": "DONE",
"goods": [
{
"good": {
"code": "500",
"barcode": "2000000000009",
"name": "Вино ігристе біле Вінтаж де Локсарел БН Резерва, Loxarel брют 0,125",
"excise_barcodes": [
"AENX936821"
],
"header": null,
"footer": null,
"uktzed": "2204109300",
"price": 19500
},
"good_id": "94433d09-c47e-48a1-8010-570099ee52e4",
"sum": 19500,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "2dffc3b9-b638-406d-ad14-408ff0df1671",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 3095,
"extra_value": 929
}
],
"discounts": []
},
{
"good": {
"code": "501",
"barcode": "5000281025360",
"name": "Ромовий напій Captain Morgan Spiced Gold, 35%, 0,5 л (437392)",
"excise_barcodes": [
"ACVI735229",
"ACVE735293"
],
"header": null,
"footer": null,
"uktzed": "2208906900",
"price": 20900
},
"good_id": "ce7a84e9-ff67-4c25-8d12-875134d650fe",
"sum": 41800,
"quantity": 2000,
"is_return": false,
"taxes": [
{
"id": "3319723e-8eba-4c04-ae70-a9221de3a43f",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 6635,
"extra_value": 1990
}
],
"discounts": []
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 56300,
"commission": null,
"label": "Картка",
"card_mask": "XXXXXXXXXXXX6734",
"bank_name": "PrivetBank",
"auth_code": "078111",
"rrn": "305817547111",
"payment_system": "VISA",
"owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO",
"terminal": "S1LF0EUR",
"acquiring": "PrivetBank",
"acquirer_and_seller": "PrivetBank",
"receipt_no": "1",
"signature_required": false,
"tapxphone_terminal": null
}
],
"total_sum": 56300,
"sum": 56300,
"total_payment": 56300,
"total_rest": 0,
"rest": 0,
"round_sum": 0,
"fiscal_code": "TEST-iA5fmb",
"fiscal_date": "2023-11-29T14:07:28+00:00",
"delivered_at": null,
"created_at": "2023-11-29T14:07:28+00:00",
"updated_at": "2023-11-29T12:11:28.569137+00:00",
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e1004508",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 8936,
"extra_value": 2680
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 5000,
"tax_code": null,
"tax_codes": [
1
],
"name": "Знижка",
"privilege": null,
"sum": -5000
}
],
"order_id": null,
"header": "Якийсь хедер",
"footer": "Якийсь футер",
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": true,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": "https://cabinet.tax.gov.ua/cashregs/check?id=TEST-iA5fmb&date=20231129&time=16%3A07%3A28&fn=TEST551151&sm=563.00&mac=5db006ff9126fcb39146c017f4f8d7e8668dee4220dce5136ff795716c483f73",
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"service_currency_exchange": [],
"shift": {
"id": "16a4caf5-abf7-46b3-9729-1aab84fae33d",
"serial": 47,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-29T12:04:20.574746+00:00",
"closed_at": null,
"initial_transaction": {
"id": "08c48ca9-9a6d-4c70-b114-febf46fc871a",
"type": "SHIFT_OPEN",
"serial": 182,
"status": "DONE",
"request_signed_at": "2023-11-29T12:04:20.651192+00:00",
"request_received_at": "2023-11-29T12:07:11.634244+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-ZBt1ku",
"offline_id": "TEST-ZBt1ku",
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:07:11.665850+00:00",
"original_datetime": "2023-11-29T12:04:20.574746+00:00",
"previous_hash": "f282bba44d4396cb7fc611ac3ac87d2b861e554dc97c755ac7b9ef27833a4676"
},
"closing_transaction": null,
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:04:20.685550+00:00",
"balance": {
"initial": 6420,
"balance": 6420,
"cash_sales": 0,
"card_sales": 168900,
"discounts_sum": 15000,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2023-11-29T12:11:28.569137+00:00"
},
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e1004508",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 34852,
"returns": 0,
"sales_turnover": 168900,
"returns_turnover": 0
},
{
"id": "ee78ddd7-979f-419b-990e-529871241874",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "2df43a8c-be79-41b8-9f78-1bb1c0c9d731",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "351551ce-4be2-4581-8184-df53b70e9604",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c4263fbaad",
"fiscal_number": "TEST551151",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-14T22:55:08+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee800245",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjgjuwNd",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": "9933"
}
Параметри відповіді співпадають із параметрами відповіді методу /api/v1/receipts/sell.
¶ Передплата та післяплата
¶ Видача готівки держателям ЕПЗ
Метод /api/v1/receipts/cash-withdrawal призначений для створення чека видачі готівкових коштів держателю ЕПЗ (видача готівки на касі) згідно форми ФКЧ-4. Обов'язковими полями для заповнення в тілі запиту "id" та блок "payments" із даними терміналу.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id":"<генерація та передача UUID чека на стороні інтеграції є обов'язковою>",
"cashier_name":"<Ім'я касира>",
"departament":"<Назва відділу>",
"payment":{
"type":"<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return":"<true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>",
"provider_type":"<у разі застосування технології `TAPXPHONE`, дане поле буде заповнено автоматично. Можливі значення:`TAPXPHONE`,`POSCONTROL`, `TERMINAL`>",
"value":"<сума оплати у копійках>",
"commission":"<комісія (тільки для безготівкових платежів)>",
"label":"<текстова назва форми оплати>",
"card_mask":"<маска карти (не більше 19 символів) (тільки для безготівкових платежів)>",
"bank_name":"<назва банку (тільки для безготівкових платежів)>",
"auth_code":"<код авторизації банківської операції (тільки для безготівкових платежів)>",
"rrn":"<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)>",
"payment_system":"<платіжна система (тільки для безготівкових платежів)>",
"owner_name":"<ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)>",
"terminal":"<інформація про платіжний термінал (тільки для безготівкових платежів)>",
"acquirer_and_seller":"<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)>",
"receipt_no":"<номер банківського чека (тільки для безготівкових платежів)>",
"signature_required":"<true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>",
"tapxphone_terminal":"<унікальний ідентифікатор інтеграції технології `TAPXPHONE` у форм UUID>"
},
"fiscal_code":"<невикористаний офлайн код - у разі створення чека в офлайн режимі>",
"fiscal_date":"<дата/час фіскалізації чека у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm - у разі створення чека в офлайн режимі>",
"header":"<хедер чека>",
"footer":"<футер чека>",
"barcode":"<штрих-код чека>",
"delivery":{
"email":"<e-mail клієнта для відправки копії чека>",
"emails":[
"<e-mail клієнта для відправки копії чека 1>",
"<e-mail клієнта для відправки копії чека 2>"
],
"phone":"<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"previous_receipt_id":"<UUID попереднього чека>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/receipts/cash-withdrawal' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id":"9f24a762-ac88-474b-a524-bba683dfb6c1", "cashier_name":"Тестовий касир", "departament":"Тестова каса>", "payment":{ "type": "CASHLESS", "value": 20000, "label": "Картка", "card_mask": "XXXXXXXXXXXX6734", "bank_name": "PrivetBank", "auth_code": "078111", "rrn": "305817547111", "payment_system": "VISA", "owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO", "terminal": "S1LF0EUR", "acquirer_and_seller": "PrivetBank", "receipt_no": "1", "signature_required": false}}'
¶ Response body
{
"id": "9f24a762-ac88-474b-a524-bba683dfb6c1",
"type": "CASH_WITHDRAWAL",
"transaction": {
"id": "1e4e3f7e-adef-4a87-b5b2-80834bc8601b",
"type": "RECEIPT",
"serial": 160,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": null,
"created_at": "2023-11-06T15:31:38.531434+00:00",
"updated_at": "2023-11-06T15:31:38.531434+00:00",
"original_datetime": "2023-11-06T15:31:38.531434+00:00",
"previous_hash": "52b21218b70c30a298332c897472b951603c2d874876e00dd06577c39f15aa12"
},
"serial": 87,
"status": "CREATED",
"goods": [],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 20000,
"commission": null,
"label": "Картка",
"card_mask": "XXXXXXXXXXXX6734",
"bank_name": "PrivetBank",
"auth_code": "078111",
"rrn": "305817547111",
"payment_system": "VISA",
"owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO",
"terminal": "S1LF0EUR",
"acquiring": "PrivetBank",
"acquirer_and_seller": "PrivetBank",
"receipt_no": "1",
"signature_required": false,
"tapxphone_terminal": null
}
],
"total_sum": 20000,
"total_payment": 20000,
"total_rest": 0,
"round_sum": null,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2023-11-06T15:31:38.531434+00:00",
"updated_at": null,
"taxes": [],
"discounts": [],
"order_id": null,
"header": null,
"footer": null,
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"shift": {
"id": "cec5dd7e-837c-46c6-a0ba-03a61cd24c8e",
"serial": 43,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-06T14:41:30.108678+00:00",
"closed_at": null,
"initial_transaction": {
"id": "1bde6e04-31e6-41d3-9a65-4b8d4650b87a",
"type": "SHIFT_OPEN",
"serial": 157,
"status": "DONE",
"request_signed_at": "2023-11-06T14:41:30.171706+00:00",
"request_received_at": "2023-11-06T14:41:30.214959+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-DQYjfj",
"offline_id": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.240628+00:00",
"original_datetime": "2023-11-06T14:41:30.108678+00:00",
"previous_hash": "01bec2834cba96d53bd8f930a3d6acc8a29789a70dce728ea28aa991b7197bc8"
},
"closing_transaction": null,
"created_at": "2023-11-06T14:41:30.108678+00:00",
"updated_at": "2023-11-06T14:41:30.244566+00:00",
"balance": {
"initial": 0,
"balance": 6420,
"cash_sales": 16420,
"card_sales": 56300,
"discounts_sum": 5583,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 10000,
"service_out": 20000,
"updated_at": "2023-11-06T15:31:38.531434+00:00"
},
"taxes": [
{
"id": "b3820b97-9c13-4b6f-aa5b-98cdb34feb99",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 11617,
"returns": 0,
"sales_turnover": 56300,
"returns_turnover": 0
},
{
"id": "ccf0e3cb-0286-423f-a278-df9f3c643287",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "22abcf11-e9b2-4f40-8c46-1a3b5cbe6f89",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4828cb2f-db1f-4174-acce-77e05612db3e",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 16417,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c4263fbaad",
"fiscal_number": "TEST551151",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-04T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee800245",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjgjuwNd",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека (CASH_WITHDRAWAL)
"transaction" - інформація про транзакцію чека (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"serial" - порядковий номер чека
"status" - статус чека
"goods" - блок даних з переліком товарів (для службового чека перелік буде пустим)
"payments" - блок даних з інформацією про платежі:
- "type" - тип платежу (для службового чека внесення/вилучення готівки має бути
CASH) - "pawnshop_is_return" - параметр, який визначає даний чек як чеки видачі коштів ломбарду (за замовчуванням для звичайних чеків, створених не для ломбардів, має бути
null) - "value" - сума внесення/винесення у копійках. Для формування чеку винесення готівки потрібно перед сумою вказати знак
-
"label" - текстова мітка, яка буде розміщена на чеку
"total_sum" та "sum" - сума вартості товарів у чеку
"total_rest" та "rest" - сума здачі
"total_payment" - сума оплати за товари у чеку
"round_sum" - сума округлення
"fiscal_code" - фіскальний номер чека (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"fiscal_date" - фіскальна дата, з якою чек буде зареєстровано у ДПС (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"delivered_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час доставки чека у ДПС (має значення null, оскільки не стосується службових чеків або не відправляється в Податкову Службу)
"created_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час створення чека
"updated_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час останнього оновлення даних чека (якщо чек щойно створено або інформація по ньому не оновлювалась, то дане значення буде null)
"taxes" - блок даних про податки (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція нефіскальна і до неї не застосовуються податки)
"discounts" - блок даних про знижки (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція нефіскальна і до неї не застосовуються знижки)
"order_id" - ідентифікатор замовлення у форматі UUID (для чека внесення/вилучення готівки за замовчуванням null, оскільки операція не являє собою замовлення)
"header" - хедер чека (для службового чека внесення/вилучення готівки за замовчуванням null)
"footer" - футер чека (для службового чека внесення/вилучення готівки за замовчуванням null)
"barcode" - штрих-код (для службового чека внесення/вилучення готівки за замовчуванням null)
"custom" - блок з даними кастомізації чека (lокладніше про параметри, які можуть відображатись в даному блоці можете дізнатись в розділі Візуалізація чека)
"is_created_offline" - ознака режиму (онлайн/офлайн) у якому був створений чек. true - чек створений у офлайні, false - чек створений у онлайні.
"is_sent_dps" - ознака відправки чека у ДПС (для чека внесення/вилучення готівки за замовчуванням false, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"sent_dps_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час відправки чека у ДПС (для чека внесення/вилучення готівки за замовчуванням null, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"tax_url" - посилання на чек у кабінеті ДПС (для чека внесення/вилучення готівки за замовчуванням null, оскільки службові чеки нефіскальні та у ДПС не відправляються)
"related_receipt_id" - id пов'язаного чека у форматі UUID. Цим параметром можна пов'язати між собою чек продажу та повернення, щоб завжди мати змогу дізнатися, на основі якого конкретно чека продажу ви робили повернення (для службового чека даний параметр не актуальний та за замовчуванням null)
"technical_return" - параметр, який відповідає за мітку технічного повернення на чеку. Технічне повернення - це повернення чеку продажу у випадку, коли чек продажу сформований невірно і для коригування балансу виникає змога провести повернення (для службового чека даний параметр не актуальний та за замовчуванням null)
"stock_code" - блок даних, який стосується операцій валютного обміну (не актуально для службового чека)
"currency_exchange" - блок даних, який стосується операцій валютного обміну (не актуально для службового чека)
"control_number" - контрольне число. Заповнюється сервером для фіскальних чеків (службовий матиме за замовчуванням даний параметр null)
Блоки даних з інформацією про:
- зміну
- баланси
- податки
- касу
- касира
- дозволи касира
¶ Нова Пошта
Публікація методів для створення відкладеного чека Нової Пошти не планується в API.
Розробник інтеграції може самостійно реалізувати інтеграцію з НП, і вже до checkbox відправляти фіскальний чек після отримання посилки покупцем. Схема роботи має виглядати так:
¶ Перевірка статусу чека
Після створення запиту створення чека - необхідно відслідковувати статус, доки він не змінится на DONE. Статус чека можна відслідковувати за допомогою GET запиту /api/v1/receipts/{receipt_id}, де {receipt_id} - ідентифікатор чека, який ви вказували при його створенні.
Запит на отримання інформації про чек необхідно виконувати не раніше, ніж за 50 мс після отримання сервером Checkbox запиту на його створення та обробку.
- якщо ви виконали запит на створення чека і при перевірці його статус змінився на DONE - ви можете виконувати фіскальні операції (чеки), створювати Х-звіт і т.д
- якщо ви виконали запит на створення чека, але при перевірці його статус ERROR - це означає, що чек не може бути створено. Деталізація причини відмови у створенні зміни знаходиться в полі "response_error_message". Потрібно усунти причину помилки та повторно відправити запит на фіскалізацію чека вже із новим UUID.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/receipts/36ba6627-379d-4fe9-bcce-7e06ad11111' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token'
¶ Response body
{
"id": "36ba6627-379d-4fe9-bcce-7e06ad511111",
"type": "SELL",
"transaction": {
"id": "058542fc-7437-40a4-9d8a-e44480411111",
"type": "RECEIPT",
"serial": 185,
"status": "DONE",
"request_signed_at": "2023-11-29T12:07:27.074811+00:00",
"request_received_at": "2023-11-29T12:07:27.113181+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-eL11111",
"offline_id": null,
"created_at": "2023-11-29T12:07:27.008327+00:00",
"updated_at": "2023-11-29T12:07:27.136771+00:00",
"original_datetime": "2023-11-29T12:07:27.008327+00:00",
"previous_hash": "cf0e47fef12156bd8b21a77610951cb2928c83dabea47e6b3b5d1cb31a211111"
},
"serial": 92,
"status": "DONE",
"goods": [
{
"good": {
"code": "500",
"barcode": "2000000000009",
"name": "Вино ігристе біле Вінтаж де Локсарел БН Резерва, Loxarel брют 0,125",
"excise_barcodes": [
"AENX936821"
],
"header": null,
"footer": null,
"uktzed": "2204109300",
"price": 19500
},
"good_id": "94433d09-c47e-48a1-8010-57009911111",
"sum": 19500,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "f6dddf31-fefd-437b-9c9f-75083d311111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 3095,
"extra_value": 929
}
],
"discounts": []
},
{
"good": {
"code": "501",
"barcode": "5000281025360",
"name": "Ромовий напій Captain Morgan Spiced Gold, 35%, 0,5 л (437392)",
"excise_barcodes": [
"ACVI735229",
"ACVE735293"
],
"header": null,
"footer": null,
"uktzed": "2208906900",
"price": 20900
},
"good_id": "ce7a84e9-ff67-4c25-8d12-8751341111",
"sum": 41800,
"quantity": 2000,
"is_return": false,
"taxes": [
{
"id": "e74a8795-2b05-4024-aaf9-bf385b811111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 6635,
"extra_value": 1990
}
],
"discounts": []
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 56300,
"commission": null,
"label": "Картка",
"card_mask": "XXXXXXXXXXXX6734",
"bank_name": "PrivetBank",
"auth_code": "078111",
"rrn": "305817547111",
"payment_system": "VISA",
"owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO",
"terminal": "S1LF0EUR",
"acquiring": "PrivetBank",
"acquirer_and_seller": "PrivetBank",
"receipt_no": "1",
"signature_required": false,
"tapxphone_terminal": null
}
],
"total_sum": 56300,
"total_payment": 56300,
"total_rest": 0,
"round_sum": 0,
"fiscal_code": "TEST-e11111",
"fiscal_date": "2023-11-29T12:07:27.008327+00:00",
"delivered_at": "2023-11-29T12:07:27.851404+00:00",
"created_at": "2023-11-29T12:07:27.008327+00:00",
"updated_at": "2023-11-29T12:07:27.851404+00:00",
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e1011111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"value": 8936,
"extra_value": 2680
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 5000,
"tax_code": null,
"tax_codes": [
1
],
"name": "Знижка",
"privilege": null,
"sum": -5000
}
],
"order_id": null,
"header": "Якийсь хедер",
"footer": "Якийсь футер",
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": "https://cabinet.tax.gov.ua/cashregs/check?id=TEST-e11111&date=20231129&time=14%3A07%3A27&fn=TEST511111&sm=563.00&mac=cf0e47fef12156bd8b21a77610951cb2928c83dabea47e6b3b5d1cb31a211111",
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"service_currency_exchange": [],
"shift": {
"id": "16a4caf5-abf7-46b3-9729-1aab84f11111",
"serial": 47,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-11-29T12:04:20.574746+00:00",
"closed_at": null,
"initial_transaction": {
"id": "08c48ca9-9a6d-4c70-b114-febf46f11111",
"type": "SHIFT_OPEN",
"serial": 182,
"status": "DONE",
"request_signed_at": "2023-11-29T12:04:20.651192+00:00",
"request_received_at": "2023-11-29T12:07:11.634244+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-Z11111",
"offline_id": "TEST-Z11111",
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:07:11.665850+00:00",
"original_datetime": "2023-11-29T12:04:20.574746+00:00",
"previous_hash": "f282bba44d4396cb7fc611ac3ac87d2b861e554dc97c755ac7b9ef278311111"
},
"closing_transaction": null,
"created_at": "2023-11-29T12:04:20.574746+00:00",
"updated_at": "2023-11-29T12:04:20.685550+00:00",
"balance": {
"initial": 6420,
"balance": 10920,
"cash_sales": 4500,
"card_sales": 168900,
"discounts_sum": 15000,
"extra_charge_sum": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2023-11-29T12:27:01.601054+00:00"
},
"taxes": [
{
"id": "42fd6c01-0d82-468a-ab78-9269e1011111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 34852,
"returns": 0,
"sales_turnover": 168900,
"returns_turnover": 0
},
{
"id": "ee78ddd7-979f-419b-990e-52987111111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "2df43a8c-be79-41b8-9f78-1bb1c0c11111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"updated_at": null,
"no_vat": false,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "351551ce-4be2-4581-8184-df53b701111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 4500,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-14T22:55:08+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee11111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": false,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": "3677"
}
Параметри відповіді співпадають із параметрами відповіді методу /api/v1/receipts/sell.
¶ Візуалізація чеків
Отримання зображення чеків доступне в текстовому, графчному та html форматі.
Для отримання графічного представлення чека, після виконання запиту на його створення необхідно виконати метод /api/v1/receipts/{reсeipt_id}/png. Для отримання html - /api/v1/receipts/{reсeipt_id}/html.
Для отримання текстового виду чека необхідно виконати запит /api/v1/receipts/{reсeipt_id}/text. Так як QR-код має графічний формат, тектосвий чек буде сформовано без QR-коду - його потрібно отримувати окремо методом /api/v1/receipts/{reсeipt_id}/qrcode.
Наявні rate-limits:
· 3 запити на секунду по UUID або ФН чеку = блокування на 10 секунд
· 1 запит на секунду - без додаткового блокування
Окремо доступна індивідуальна візуалізація графічного та html чека:
¶ Request headers
accept: text/plain або accept: */*
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
або txt
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/receipts/e51c07c6-8e8a-44bf-b594-750f7e911111/html?simple=false' \ -H 'accept: text/html' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version'
або png
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/receipts/e51c07c6-8e8a-44bf-b594-750f7e911111/png?width=30&paper_width=58&qrcode_scale=75' \ -H 'accept: */*' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version'
¶ Response body
або HTML-структура для створення стилізованого вигляду чеку. Візуалізація здійснюється за допомогою каскадних таблиць стилів (CSS).
або png зображення чеку з вказаними параметрами ширини (30 пікселів), ширини паперу (58 мм) та масштабу QR-коду (75%).
¶ Звіти
¶ Періодичний
Періодичний звіт – звіт, який містить підсумкову контрольно-звітну інформацію за будь-який період, сформовану на основі даних Z-звітів.
Періодичний звіт містить:
- період, за який формується звіт із зазначенням номерів та дати першого та останнього Z-звіта;
- номер та фіскальний код останнього фіскального чека;
- підсумок розрахункових операцій за реалізовані товари (надані послуги) за кожною окремою податковою ставкою;
- загальний підсумок одержаних коштів у розрізі форм оплат;
- інформація щодо створених чеків повернення - оборот та їх кількість;
- інформація щодо готівкових коштів в касі за обраний період;
- загальна сума виручки з урахуванням сум повернень та видачі коштів держателям ЕПЗ;
- загальний підсумок розрахункових операцій за реалізовані товари (надані послуги) за кожним окремим Z-звітом із зазначенням номера та дати Z-звіта;
- дату та час формування звіту.
Для отримання періодичного звіту використовується метод /api/v1/reports/periodical. Звіт доступний лише в текстовому форматі без перегляду за посиланням.
Параметри запиту регулюються ключами:
- "from_date" та "to_date" - проміжки часу у форматі ISO 8601,
- "width" - кількість символів у рядку,
- "is_short" - true/false (скорочений звіт не показує інформацію підсумків по Z-звітах по днях),
- "X-License-Key" - ключ ліцензії каси, по якому необхідно створити звіт.
¶ Request headers
accept: text/plain
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/reports/periodical?from_date=2023-11-01T00%3A00%3A00%2B0200&to_date=2023-11-30T00%3A00%3A00%2B0200&width=42&is_short=false' \ -H 'accept: text/plain' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111'
¶ Response body
txt представлення звіту з деталями фіскальних операцій, оборотів, операцій з готівковими коштами та іншою інформацією, яка складається з різних розділів та підсекцій
¶ Х-звіт
Х-звіт – це не фіскальний звіт, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу (відкритої касової зміни).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/reports' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token' \ -d ''
¶ Response body
{
"id": "860e6c37-43bc-498a-b801-58a927511111",
"serial": 16,
"is_z_report": false,
"payments": [
{
"id": "601194e1-1267-4012-9736-f7ccea711111",
"code": null,
"type": "CASH",
"provider_type": null,
"label": "Готівка",
"sell_sum": 16420,
"return_sum": 0,
"service_in": 10000,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
},
{
"id": "a927bd11-a885-43fd-8fed-cefba0011111",
"code": null,
"type": "CASHLESS",
"provider_type": null,
"label": "Картка",
"sell_sum": 56300,
"return_sum": 0,
"service_in": 0,
"service_out": 20000,
"cash_withdrawal": 20000,
"cash_withdrawal_commission": 0
}
],
"taxes": [
{
"id": "4cce63e6-3aa1-4341-a0e2-1372e9e11111",
"code": 1,
"label": "ПДВ + Акцизний збір",
"symbol": "А",
"rate": 20,
"sell_sum": 11617,
"return_sum": 0,
"sales_turnover": 56300,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-09-27T07:57:17.436553+00:00",
"setup_date": "2023-09-27T07:57:17.436553+00:00"
},
{
"id": "613406bb-1c12-40db-8e06-21a874d11111",
"code": 2,
"label": "Акцизний збір",
"symbol": "Б",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-11-03T10:19:06.625503+00:00",
"setup_date": "2023-11-03T10:19:06.625503+00:00"
},
{
"id": "3785ce91-ee57-465b-8689-fff521011111",
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"no_vat": false,
"advanced_code": null,
"created_at": "2023-09-27T07:57:32.979471+00:00",
"setup_date": "2023-09-27T07:57:32.979471+00:00"
},
{
"id": "2c5a16da-c101-444a-bb88-17d6dae11111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 16417,
"returns_turnover": 0,
"no_vat": true,
"advanced_code": null,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"setup_date": "2023-09-27T07:57:34.983722+00:00"
}
],
"sell_receipts_count": 2,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 1,
"transfers_count": 0,
"transfers_sum": 0,
"balance": 6420,
"initial": 0,
"sales_round_up": 3,
"sales_round_down": 0,
"returns_round_up": 0,
"returns_round_down": 0,
"created_at": "2023-11-06T15:38:45.775429+00:00",
"updated_at": null,
"discounts_sum": 5583,
"extra_charge_sum": 0,
"transaction_fail": false
}
Звіт:
"id" - унікальний ідентифікатор звіту у форматі UUID.
"serial" - порядковий номер звіту.
"is_z_report" - флаг, що визначає, чи є даний звіт Z-звітом. Для X-звіту завжди false.
"payments" - масив із списком способів оплати.
Способи оплати (payments):
"id" - унікальний ідентифікатор способу оплати у форматі UUID.
"code" - код способу оплати.
"type" - тип способу оплати (CASH/CASHLESS).
"provider_type" - тип постачальника (може бути null).
"label" - текстовий опис способу оплати.
"sell_sum" - сума продажів з даною формою оплати у копійках.
"return_sum" - сума повернень з даною формою оплати у копійках.
"service_in" - сума службових внесень з даною формою оплати у копійках.
"service_out" - сума службових винесень з даною формою оплати у копійках.
"cash_withdrawal" - сума операцій з видачі готівкових коштів у копійках.
"cash_withdrawal_commission" - сума комісійних нарахувань по операціям з видачі готівкових коштів у копійках.
Податкові ставки (taxes):
"id" - унікальний ідентифікатор податкової ставки у форматі UUID.
"code" - цифровий код податкової ставки.
"label" - назва податкової ставки.
"symbol" - літерний код податкової ставки.
"rate" - розмір податкової ставки у відсотках.
"sell_sum" - загальний оборот по податку усіх чеків продажу в копійках у рамках зміни.
"return_sum" - загальний оборот по податку усіх чеків повернення в копійках у рамках зміни.
"sales_turnover" - сума продажів з цією податковою ставкою (оборот) у копійках.
"returns_turnover" - сума повернень з цією податковою ставкою (оборот) у копійках.
"no_vat" - флаг, який позначає, чи є ця податкова ставка без ПДВ.
"advanced_code" - додатковий код (може бути null).
"created_at" - мітка часу створення податкової ставки у форматі ISO 8601.
"setup_date" - мітка часу встановлення податкової ставки у форматі ISO 8601.
Інші параметри:
"sell_receipts_count" - кількість чеків продажу.
"return_receipts_count" - кількість чеків повернення.
"cash_withdrawal_receipts_count" - кількість чеків по операціям з видачі готівкових коштів.
"transfers_count" - кількість переказів.
"transfers_sum" - сума переказів.
"balance" - баланс каси у копійках на момент створення звіту.
"initial" - початковий баланс каси у копійках на момент відкриття зміни.
"sales_round_up" - кількість округлень вгору для продажів.
"sales_round_down" - кількість округлень вниз для продажів.
"returns_round_up" - кількість округлень вгору для повернень.
"returns_round_down" - кількість округлень вниз для повернень.
"created_at" - мітка часу створення звіту у форматі ISO 8601.
"updated_at" - мітка часу останнього оновлення даних звіту у форматі ISO 8601 (може бути null).
"discounts_sum" - сума знижок.
"extra_charge_sum" - сума додаткових зборів.
"transaction_fail" - флаг, який вказує, чи були виявлені невдачі транзакцій (false - немає невдач).
¶ Візуалізація звітів
Візуалізація звітів доступна в текстовому та графчному форматі. Для отримання текстового представлення звіту, після виконання запиту на його створення необхідно виконати метод /api/v1/reports/{report_id}/txt. Для отримання зображення звіту - /api/v1/reports/{report_id}/png.
¶ Request headers
accept: text/plain або accept: */*
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
або txt
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/reports/1ec62f49-c35f-4ff9-ab46-8d2e83111111/text?width=42' \ -H 'accept: text/plain' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version'
або png
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/reports/1ec62f49-c35f-4ff9-ab46-8d2e83111111/png?width=30&paper_width=58' \ -H 'accept: */*' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version'
¶ Response body
або txt представлення звіту з деталями фіскальних операцій, оборотів, операцій з готівковими коштами та іншою інформацією, яка складається з різних розділів та підсекцій
або png зображення звіту за вказаними параметрами ширини і ширини паперу.
¶ Опис помилок
| 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 хвилини |
¶ Розширені звіти
Звіти, які доступні в особистому кабінеті checkbox - частково доступні в глобальному API. Наразі доступні наступні звіти:
- Звіт по товарам
- Звіт по Z-звітам
- Розширені звіти - по всіх касах організації:
3.1. Фактична виручка
3.2. Дані по чистому обігу
3.3. Дані по Z-звітам - Звіт по балансам зміни
¶ Товари
Розділ Товарів особистого кабінету також частково доступний по API. Методами API доступне:
- Завантаження нових товарів
- Оновлення даних (цін, штрихкодів і т.д)
- Експорт існуючих товарів
¶ Замовлення
Замовлення в системі checkbox - це проект фіскального чека, який необхідно фіскалізувати кур'єру після доставки замовлення покупцеві та його оплати.
Розділ замовлень доступний лише в мобільному додатку checkbox на android та після увімкнення відповідного функціоналу для касира службою технічної підтримки checkbox.
Після увімкнення відповідного функціоналу в мобільному додатку буде доступний розділ Замовлення бокового меню, де відбувається робота із створеними по REST API із зовнішньої системи замовленнями.
¶ Webhook
Щоб отримувати оновлення в режимі реального часу про сутності (зміни та фіскальні чеки), вам слід правильно налаштувати webhook. У цій інструкції наведено основні методи роботи з webhook.
¶ Приклади SDK
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.