Стандартна послідовність роботи з ПРРО включає в себе наступні етапи:
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та можливо платити штраф.
При роботі у офлайн режимі ВАЖЛИВО передавати всі транзакції послідовно, так, щоб мітка дати/часу fiscal_date у запитах офлайн переходу, створення зміни, створення чеку/чеків, закриття зміни відповідали наступним вимогам:
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції. З повним переліком методів (без деталізованого опису) ви зможете переглянути за посиланнями:
Swagger
ReDoc
Також радимо ознайомитись із графічною схемою, яка показує принципи, по яким можна побудувати АПІ інтеграцію. Можливо, вона також допоможе розібратися з якимись питаннями, в якості доповнення до документації.
Опис Request Headers, які зустрічаються найчастіше у запитах:
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-Access-Key: <ключ доступу інтеграції (не використовується зараз)>
X-Device-ID: <ID RRO Agent або мобільного пристрою каси (не використовується для API інтеграцій)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Існує 2 способи авторизації користувача у API Checkbox:
Для отримання токену доступу до API Checkbox потрібно у тілі POST запиту /api/v1/cashier/signin вказати логін та пароль касира.
Додатково у заголовку запиту можна вказати назву вашої інтеграції та її версію (опціонально).
У відповідь на запит ви отримаєте jwt токен авторизації, підставляючи який у заголовки запитів інших методів зможете їх використовувати від імені касира, яким була виконана авторизація.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Content-Type: application/json
{
"login": "логін касира",
"password": "пароль касира"
}
Приклад
POST "https://api.checkbox.ua/api/v1/cashier/signin" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Content-Type: application/json" -d "{\"login\":\"testuser37\",\"password\":\"123456\"}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 330
content-type: application/json
date: Mon,16 May 2022 19:38:11 GMT
server: nginx
x-correlation-id: 9264e013486e4e5a9b7d2792dde6782a
x-request-id: 9a971359-c9d7-48ee-9116-aec093aba127
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"type": "bearer",
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiM2U3MDk4OTYtOGM4YS00ZTcwLThhNGYtZWRlZmYyZThlMjBkIiwic3ViIjoiNmZhOGEZNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjUyNzI5ODkxLCJpYXQiOjE2NTI3Mjk4OTF9.ReYF8FicTFZiyi9s6NF6n3Y-VInbYa7_VatIs58Vwq0"
}
Для отримання токену доступу до API Checkbox потрібно у заголовку POST запиту /api/v1/cashier/signinPinCode вказати ключ ліцензії каси, а у тілі запиту - PIN код касира.
Кожного разу при новій авторизації - ви будете отримувати новий токен доступу (при цьому, старі токени - активні). Для деактивації токену доступу необхідно виконати завершення сессії користувача методом POST /api/v1/cashier/signout із токеном, який ви хочете деактивувати.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Content-Type: application/json
{
"pin_code": "PIN код касира"
}
Приклад
POST "https://api.checkbox.ua/api/v1/cashier/signinPinCode" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: 8f9eebd34c0a4c98d6d991cd" -H "Content-Type: application/json" -d "{\"pin_code\":\"5604037840\"}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 330
content-type: application/json
date: Wed,18 May 2022 11:16:12 GMT
server: nginx
x-correlation-id: 8bbb680a99d34ead8bf4714f8a6118f5
x-request-id: b3d44d96-38d8-4ad8-9723-c71236b2ceff
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"type": "bearer",
"token_type": "bearer",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eYJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiMmI0YjZkNTktNDNlNS00Yzg3LWI3NjktMWZhZWM1ZWQ0ZWFiIiwic3ViIjoiNmzhOGEzNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjUyODcyNTcyLCJpYXQiOjE2NTI4NzI1NzJ9.1hr8I1I6RR4OPbEldfD0Qz7x1AY--IjwRQ9NGn28vow"
}
За замовчуванням варто максимум часу працювати у онлайн режимі, оскільки існує законодавче обмеження на використання офлайну не більше 36 годин підряд та суммарно не більше 186 годин на місяць. Офлайн режим може бути корисним, якщо у вас нестабільне з'єднання з мережею та виникає потреба передати правильною датою чеки, які були сформовані раніше за поточну дату.
Сервіс Checkbox у випадку, якщо сервер податкової перестає відповідати на запити, автоматично переводить касу у офлайн режим, створюючи відповідні транзакції.
Щоб визначити, в якому режимі зараз працює каса, потрібно виконати запит на отримання інформації про ПРРО
/api/v1/cash-registers/info. Параметр "offline_mode" повідомить нам про поточний статус онлайн/офлайн. Для онлайн режиму цей параметр має значення false, а для офлайн режиму - true
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
GET "https://api.checkbox.ua/api/v1/cash-registers/info" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: test2c0e33cc27b429fca6bc7236"
connection: close
content-length: 409
content-type: application/json
date: Sun,26 Jun 2022 17:05:54 GMT
server: nginx
x-correlation-id: f73f566b70b6435da46bfc2e4aed523b
x-request-id: 49953880-e8f6-4c30-8e64-e806d627c36b
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "cb6905fd-5296-45ba-be4d-79302cf43a59",
"fiscal_number": "TEST373378",
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2022-06-26T17:57:06+00:00",
"address": "УКРАЇНА, М.КИЇВ ГОЛОСІЇВСЬКИЙ Р-Н, Тестова, 41а",
"title": "",
"offline_mode": false,
"stay_offline": false,
"has_shift": true,
"documents_state": {
"last_receipt_code": 30,
"last_report_code": 0,
"last_z_report_code": 16
}
}
"id" - унікальний ідентифікатор каси ПРРО у форматі UUID
"fiscal_number" - фіскальний номер каси
"created_at" - дата створення каси
"updated_at" - дата останнього оновлення (зміни) облікових даних каси
"address" - адреса розміщення каси
"title" - назва
"offline_mode" - офлайн режим. false означає, що каса зараз у онлайні, а true означає, що каса працює у офлайн режимі.
"stay_offline" - якщо даний параметр true, то це означає, що перехід у офлайн був виконаний на стороні клієнта (шляхом відправки запиту go offline, а не завдяки автоматичному офлайн переходу, який відбувається, коли не відповідає сервер ДПС)
"has_shift" - параметр показує, чи має дана каса активну відкриту зміну
"documents_state" - блок даних з інформацією про останній порядковий номер чека, звіта або z-звіта
"last_receipt_code" - останній порядковий номер чека
"last_report_code" - останній порядковий номер звіта, який не є z-звітом
"last_z_report_code" - останній порядковий номер z-звіта
Якщо каса вже знаходиться у потрібному вам режимі - можна переходити до наступного кроку і відкривати зміну. У випадку ж, якщо потрібно переключити ПРРО у онлайн або офлайн режим - скористайтеся відповідними методами, які будуть описані далі.
POST метод /api/v1/cash-registers/go-online дозволяє відправити команду на початок переходу ПРРО у онлайн режим. Зверніть увагу, що сама по собі відправка цієї команди не означає, що каса буде одразу переведена у онлайн режим. Якщо в черзі на відправку у ДПС багато офлайн чеків, то одного запиту може бути недостатньо. Після відправки go-online варто через декілька секунд перевірити статус каси запитом Get Cash Register Info. Параметр "offline_mode" покаже поточний статус. У онлайні він буде false, а у офлайні true. Якщо каса не перейшла у онлайн - варто відправити go-online ще раз та знову перевірити через декілька секунд статус каси, повторюючи дії в циклі, поки каса не вийде у онлайн.
Врахуйте, що методи створення чеку у офлайн режимі вимагають виконання офлайн-переходу, ініційованого саме з боку вашої інтеграції. Перевірити, чи був поточний офлайн перехід ініційований інтеграцією, можна за флагом "stay_offline". Якщо він true, значить, у офлайн касу перевела інтеграція, якщо false, значить перехід був автоматичний на стороні сервера і потрібно спочатку відправити go-offline з fiscal_date не раніше, ніж дата/час останньої транзакції на сервері Checkbox.
Рекомендований тайм-аут між повторними запитами go-online становить 10-15 секунд, але якщо у вас чеки створюються постійно та у великій кількості, то його доведеться зменшити.
Якщо ви відправили команду go-online вже більше разів, ніж у вас створено невідправлених у ДПС офлайн транзакцій, або вже тривалий час не можете перейти у онлайн, незважаючи на постійні спроби відправки go-online - перевірте наявність зв'язку з ДПС методом 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}"
>
яка говорить про недоступність сервера ДПС, а перехід у онлайн не відбувається - зверніться у технічну підтримку Checkbox за консультацією.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
POST "https://api.checkbox.ua/api/v1/cash-registers/go-online" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: 8f9eebd34c0a4c98d6d991cd" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiMmZkZjU1OWMtZWE0OS00YWQyLTkwYmQtZmY5YWViYWY5Mzk4Iiwic3ViIjoiNmZhOGEzNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjU0MjU5MzAwLCJpYXQiOjE2NTQyNTkzMDB9.NlA9S8GpnEnZSSIC8lQpmLlJOjTgAXhEPLZBh9oDWD4" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 15
content-type: application/json
date: Fri,03 Jun 2022 14:02:21 GMT
server: nginx
x-correlation-id: f982274d74164680b97eafe009aeda43
x-request-id: 4384fe98-a8da-4bcd-a271-863928542b3a
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"status": "ok"
}
"status" - статус отримання команди на ініціалізацію переходу у онлайн режим. Даний статус завжди повертає значення ok у випадку успішного виконання запиту, проте не означає, що ПРРО одразу ж перейде у онлайн. Саме тому потрібно через декілька секунд перевірити статус каси запитом Get Cash Register Info, який буде описаний нижче. Параметр "offline_mode" покаже поточний статус. У онлайні він буде false, а у офлайні true. Після того, як каса перейде у онлайн, потрібно зупинити повторну відправку go-online, щоб не створювати зайве навантаження на сервер.
Для перевірки зв'язку з сервером податкової можна скористатися методом /api/v1/cash-registers/ping-tax-service. Відправка команди PING також ініціалізує відправку чеків у податкову з подальшим виходом каси у онлайн режим (якщо вона знаходиться у офлайні).
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
POST "https://api.checkbox.ua/api/v1/cash-registers/ping-tax-service" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: 3eb6543793d8e613944e0099" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiYWY1NmYxMGUtODljMy00YWExLWI4Y2QtOGM5MzllNTgwYmJjIiwic3ViIjoiNjI2Mjk1NDktNTFhMS00NDMyLTgwODItMjcwNDgyYmU3ZjU4IiwibmJmIjoxNjU0Mjc3NjA1LCJpYXQiOjE2NTQyNzc2MDV9.SiFMK2HI5X8wqsEuV5d4_Dw4_mQs5uCj-2RZ9NRD1W4" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 30
content-type: application/json
date: Fri,03 Jun 2022 17:35:24 GMT
server: nginx
x-correlation-id: b60bdebc726b42b2b50205102478757c
x-request-id: 1f54e69e-736f-48d0-a2c1-94d1758cf2cc
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"status": "DONE",
"error": null
}
"status" - статус транзакції відправки запиту PING. Може мати статуси CREATED/PENDING/SIGNED/DELIVERED/DONE або ERROR
"error" - текстовий опис помилки, яку повернає сервер ДПС. Якщо помилки немає, цей параметр прийме значення null
У полі "error" може повертатись і помилка виду
{
"status": "DONE",
"error": "ERROR_BAD_HASH_PREV store bdfdc222d0a015519e269292d58b5690a7f02d9b65a0eae79b6241b7a9ea153f chk ad10bda2a97f4674dbb052a0ff0e401175d8425bd85f9bf9247ddba1ff73421e"
}
Вона ніяк не вплине на роботу безпосередньо (команда PING призначена для перевірки наявності зв'язку з ДПС, а не для передачі і збереження транзакції зміни/чека/офлайн-онлайн переходу, тому не важливо, пройде чи ні PING перевірку на відповідність хешу попереднього чеку. Будь-яка відповідь від ДПС означатиме, що зв'язок з податковою є).
Ситуація з помилкою вище виникає у випадку, коли з сервера Checkbox відправляється PING, але він до сервера ДПС потрапляє раніше, ніж масив чеків, створених у офлайн режимі, які ще не потрапили до ДПС. В кожному чеку міститься хеш попереднього. PING - це, по суті, також своєрідний службовий чек. У прикладі вище PING мав хеш ad10bda2a97f4674dbb052a0ff0e401175d8425bd85f9bf9247ddba1ff73421e, це хеш останнього офлайн чеку, який був сформований перед відправкою PING до ДПС. Останній чек, який вже був прийнятий сервером ДПС, мав хеш bdfdc222d0a015519e269292d58b5690a7f02d9b65a0eae79b6241b7a9ea153f. PING обробляється раніше, ніж починають передаватися офлайн чеки, тому ДПС очікує хеш bdfdc222d0a015519e269292d58b5690a7f02d9b65a0eae79b6241b7a9ea153f замість ad10bda2a97f4674dbb052a0ff0e401175d8425bd85f9bf9247ddba1ff73421e, тому і повертає помилку.
Якщо сервер ДПС у даний момент недоступний, ви отримаєте помилку виду:
_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 тільки коли каса знаходиться у ОНЛАЙН режимі. Після виконання запиту ці номери зберігаються на нашому сервері і стають доступними для отримання методом /api/v1/cash-registers/get-offline-codes.
Після виконання запиту на офлайн коди відправляти будь-які офлайн транзакції (зміни, чеки, офлайн переходи) можна тільки з датою/часом fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу виконання запиту /api/v1/cash-registers/ask-offline-codes
Відправити запит на офлайн фіскальні коди можна синхронно або асинхронно, що врегульовується відповідним параметром у запиті (sync). Кількість кодів, яку користувач бажає отримати, задається у параметрі count запиту. Асинхронний режим одразу поверне статус "status": "OK"(або ERROR, якщо на етапі формування запиту відбулася помилка), незалежно від того, чи запит успішно досяг сервера податкової. Синхронний режим обробляє запит повністю і передає остаточний статус DONE, якщо запит успішно досяг сервера ДПС, або TIMEOUT, якщо сервер ДПС не відповів у визначений строк.
Важливо - номер перестає повертатися сервером ДПС (вважається "використаним") лише після відправки до ДПС транзакції з цим номером. До того часу ДПС повертає фіскальний номер при кожному виклику. Наприклад, зробивши до ДПС перший запит на 100 номерів, отримаємо 100 нових вільних фіскальних номерів для відповідного ПРРО. Але зробивши після цього запит ще на 200 номерів, отримаємо 100 тих самих номерів та ще 100 наступних за ними. Виклик метода Ask Offline Codes можна робити лише тоді, коли ПРРО знаходиться в онлайн режимі.
GET "https://api.checkbox.ua/api/v1/cash-registers/ask-offline-codes?count=<кількість кодів>&sync=<true/false (синхронний/асинхронний)>"
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
GET "https://api.checkbox.ua/api/v1/cash-registers/ask-offline-codes?count=2000&sync=false" -H "accept: */*" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: 3eb6543793d8e613944e0099" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiZGMyNzBkNDQtMDUyZC00YjVlLWFkNDItZGNkMWEyZGQ4OWRlIiwic3ViIjoiNjI2Mjk1NDktNTFhMS00NDMyLTgwODItMjcwNDgyYmU3ZjU4IiwibmJmIjoxNjU1MTI1Nzg5LCJpYXQiOjE2NTUxMjU3ODl9.7YbH0YNgXK2B5lxCbdHgGSq3V6qX-eRskEoTyXQjGSg"
connection: close
content-length: 15
content-type: application/json
date: Mon,13 Jun 2022 13:12:57 GMT
server: nginx
x-correlation-id: a6fdae1e24cd48e18ea045937d2a289b
x-request-id: dd5ad22b-f8bf-42db-908f-cadb29dc8b55
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"status": "OK"
}
"status" - статус запиту. Для асинхронного режиму завжди буде ОК або ERROR, для синхронного - приймає значення DONE у випадку успішного запиту, TIMEOUT, якщо перевищено ліміт очікування відповіді від сервера ДПС або ERROR, якщо виникла помилка.
Врахуйте, що у асинхронному режимі ОК не означає успішне виконання запиту, а тільки його успішну відправку.
"error" - текстовий опис помилки.
Якщо попередньо ПРРО раніше вже отримало список офлайн фіскальних кодів за допомогою метода ASK OFFLINE CODES, то за допомогою метода /api/v1/cash-registers/get-offline-codes ви зможете завантажити необхідну кількість невикористаних на даний момент фіскальних номерів з сервера Checkbox, навіть якщо сервер ДПС недоступний.
Будь-який фіскальний код можна використати лише 1 раз на створення офлайн транзакції відкриття/закриття зміни, офлайн переходу або чеку. Врахуйте, що на стороні серверу Checkbox реалізовано функцію автоматичного переходу у офлайн режим у випадку тайм-ауту відповіді від ДПС. Тобто, сервер автоматично створить транзакцію офлайн переходу та почне створювати чеки у офлайн режимі, підставляючи у них доступні офлайн коди, навіть якщо ви зі свого боку відправляєте чеки як онлайнові. Тобто, перед відправкою до Checkbox офлайн чеків варто синхронізувати пул доступних для використання фіскальних кодів, інакше на певних чеках може виникнути помилка виду "[offline_mode_exception#error] Offline code '<офлайн код>' was used before!".
Метод GET OFFLINE CODES можна використовувати тільки якщо зміна відкрита.
GET "https://api.checkbox.ua/api/v1/cash-registers/get-offline-codes?count=<кількість офлайн кодів>"
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
GET "https://api.checkbox.ua/api/v1/cash-registers/get-offline-codes?count=3" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiZGMyNzBkNDQtMDUyZC00YjVlLWFkNDItZGNkMWEyZGQ4OWRlIiwic3ViIjoiNjI2Mjk1NDktNTFhMS00NDMyLTgwODItMjcwNDgyYmU3ZjU4IiwibmJmIjoxNjU1MTI1Nzg5LCJpYXQiOjE2NTUxMjU3ODl9.7YbH0YNgXK2B5lxCbdHgGSq3V6qX-eRskEoTyXQjGSg"
connection: close
content-length: 433
content-type: application/json
date: Mon,13 Jun 2022 17:34:06 GMT
server: nginx
x-correlation-id: 1bd1a005815c492d80d9513725006147
x-request-id: 10c5c68c-2219-435b-aaea-8b5c498e06b7
x-robots-tag: noindex,nofollow,nosnippet,noarchive
[
{
"cash_register_id": "fb75cd7e-0f7b-4de3-b185-4a60c8b0123c",
"serial_id": 1,
"created_at": "2021-12-01T18:17:40.035386",
"fiscal_code": "lDKJSU6ZQtk"
},
{
"cash_register_id": "fb75cd7e-0f7b-4de3-b185-4a60c8b0123c",
"serial_id": 2,
"created_at": "2021-12-01T18:17:40.035573",
"fiscal_code": "Rsj3rQ21l1I"
},
{
"cash_register_id": "fb75cd7e-0f7b-4de3-b185-4a60c8b0123c",
"serial_id": 3,
"created_at": "2021-12-01T18:17:40.035763",
"fiscal_code": "CwLgtUPD6uA"
}
]
Для кожного фіскального коду метод поверне масив даних, який включає в себе:
"cash_register_id" - id обраної каси у форматі UUID
"serial_id" - порядковий номер фіскального коду
"created_at" - дата створення фіскального коду
"fiscal_code" - фіскальний код
Якщо на сервері немає фіскальних кодів, то масив буде порожнім. У випадку, якщо ви відправите у запиті параметр count, який буде перевищувати кількість доступних офлайн кодів, то сервер поверне у тілі відповіді стільки кодів, скільки є у наявності.
POST метод /api/v1/cash-registers/go-offline дозволяє відправити команду на перехід ПРРО у офлайн режим. Для переходу у офлайн достатньо виконати 1 успішний запит go-offline. Поточний статус онлайн/офлайн ПРРО можна визначити за допомогою запиту Get Cash Register Info, який буде описаний нижче. Параметр "offline_mode" покаже поточний статус онлайн/офлайн. У онлайні він буде false, а у офлайні true.
У тілі запиту є можливість вказати часову мітку офлайн переходу (саме такою датою/часом буде зареєстрований у ДПС перехід у офлайн). Зверніть увагу, що перейти у офлайн можливо з міткою дати/часу fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу останньої успішно доставленої у ДПС транзакції (чеку/відкриття/закриття зміни/переходу у онлайн). Передача невірної дати/часу призведе до застрягання каси у офлайн режимі та ПОЛОМКИ КАСИ. У параметрі "fiscal_code" потрібно передати фіскальний код, який раніше ще не був використаний.
Первинне отримання масиву фіскальних кодів відбувається з використанням методу ASK OFFLINE CODES (буде описаний нижче), після успішного виконання ASK OFFLINE CODES отримати список ще не використаних на сервері фіскальних кодів можна за допомогою метода GET OFFLINE CODES (також буде описаний далі). Саме ним бажано користуватись, аж допоки запас офлайн кодів не зменшиться до кількості, яку ви встановите для себе критичною (наприклад, до 500). Метод GET OFFLINE CODES дозволяє набагато швидше отримати вільні, вже отримані раніше фіскальні коди для обраного ПРРО, не чекаючи відповідь від сервера податкової.
Якщо в тілі запиту на перехід у офлайн не передати параметр "fiscal_code", то сервер зі свого боку автоматично підставить один з вільних фіскальних кодів і виконає переведення ПРРО у офлайн режим. Врахуйте, що якщо ви спробуєте потім відправити чек з офлайн кодом, який був автоматично підставлений у офлайн перехід, то виникне помилка, оскільки кожен код можна використати лише один раз. Також, якщо у тілі запиту не вказувати "go_offline_date", то офлайн перехід відбудеться з поточною міткою дати/часу. Тобто, якщо вас влаштовує, що офлайн код буде автоматично підставлено сервером, а дата/час переходу будуть поточні, то можете лишити тіло запиту на перехід у офлайн взагалі порожнім.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"go_offline_date": "2022-06-03T14:26:45+03:00",
"fiscal_code": "lRvyZSJLrC4"
}
Приклад
POST "https://api.checkbox.ua/api/v1/cash-registers/go-offline" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: 8f9eebd34c0a4c98d6d991cd" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiMmZkZjU1OWMtZWE0OS00YWQyLTkwYmQtZmY5YWViYWY5Mzk4Iiwic3ViIjoiNmZhOGEzNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjU0MjU5MzAwLCJpYXQiOjE2NTQyNTkzMDB9.NlA9S8GpnEnZSSIC8lQpmLlJOjTgAXhEPLZBh9oDWD4" -H "Content-Type: application/json" -d "{\"go_offline_date\":\"2022-06-03T14:26:45+03:00\",\"fiscal_code\":\"lRvyZSJLrC4\"}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 59
content-type: application/json
date: Fri,03 Jun 2022 14:52:30 GMT
server: nginx
x-correlation-id: d8fe950b62714777bf4b83729ec7eb35
x-request-id: 5da9b8f6-5931-474c-bf57-27535a1f38f6
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"status": "ok",
"id": "e9896d03-cbe9-4f0c-8d38-2d827e2c4cb9"
}
"status" - статус виконання запиту. Успішний запит завжди матиме статус ok
"id" - унікальний ідентифікатор транзакції у форматі UUID
Відкрити зміну можна за допомогою запиту /api/v1/shifts. Відкрити зміну можна у онлайн або офлайн режимі. Для відкриття зміни у офлайн режимі потрібно спочатку виконати команду GO OFFLINE, яка буде описана далі, а після цього в тілі запиту на створення зміни потрібно вказати вільний фіскальний код та фіскальну дату. Механізм отримання таких фіскальних кодів для створення офлайн транзакцій буде описаний в методі ASK OFFLINE CODES. Також можна задати зміні унікальний ідентифікатор у форматі UUID. Якщо у тілі запиту не буде цього ідентифікатора, то після передачі запиту на сервер Checkbox зміні буде автоматично присвоєно UUID. Для створення зміни у онлайн режимі не потрібно вказувати фіскальний код та фіскальну дату. Дата автоматично буде вказана поточна.
За замовчуванням варто працювати максимум часу у онлайн режимі, оскільки існує обмеження на використання офлайну - 36 годин підряд та не більше 168 годин на місяць. Слідкувати за дотриманням цієї норми потрібно клієнту, який використовує API.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"id": "унікальний ідентифікатор зміни у форматі UUID",
"fiscal_code": "<фіскальний код>",
"fiscal_date": "<фіскальна дата у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>"
}
Приклад
POST "https://api.checkbox.ua/api/v1/shifts" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "X-License-Key: test2c0e33cc27b429fca6bc7236" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiNDFkMjQyNDItOWJmMC00NjRhLThmOWQtNWE5MzM4NGY2YzczIiwic3ViIjoiMTlmZjk2ZTAtOTkzYi00NDAzLWEzOWYtNDIyNzQ0ODRlM2E5IiwibmJmIjoxNjU1ODk5ODY0LCJpYXQiOjE2NTU4OTk4NjR9.a75gxvB-XdldXfWw58Mn2FmxrG9hmjp3U6ZIyaFXzT0" -H "Content-Type: application/json" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 3338
content-type: application/json
date: Wed,22 Jun 2022 12:22:09 GMT
server: nginx
x-correlation-id: 48b0a66ea6034c5d831f40d38b115450
x-request-id: 5b544891-5595-4dc3-939e-9a9c07319e2d
{
"id": "a8d6cd50-b151-4598-8259-5b5e15655eb0",
"serial": 10,
"status": "CREATED",
"z_report": null,
"opened_at": null,
"closed_at": null,
"initial_transaction": {
"id": "93e42158-66dd-4831-ac7a-165d96658b67",
"type": "SHIFT_OPEN",
"serial": 43,
"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": "2022-06-22T12:22:09.202431+00:00",
"updated_at": "2022-06-22T12:22:09.202431+00:00",
"previous_hash": "2c78452055ec4fe1bd62a20e8872736ee42c93ac105f734323b7e53b47a38a9b"
},
"closing_transaction": null,
"created_at": "2022-06-22T12:22:09.202431+00:00",
"updated_at": null,
"balance": {
"initial": 455000,
"balance": 455000,
"cash_sales": 0,
"card_sales": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": null
},
"taxes": [
{
"id": "95535f70-e856-47b5-a227-8a18ff48f002",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "64cbdf80-3e96-4f96-a196-b9981e0558e6",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "57534a14-9496-402b-93c1-31cb0f7d0b1a",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "01ade340-c74f-40cb-81db-8eda9e6a2f46",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "2235c08d-98c8-4da5-83e8-ed0d064917ff",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "df413d52-550b-40e5-b109-36f1e8ffed4e",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "2bd0537b-50ea-414f-b1f3-a45fa0496d43",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "0ea863cc-72ea-4802-8b53-fdd020896823",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"cash_register": {
"id": "cb6905fd-5296-45ba-be4d-79302cf43a59",
"fiscal_number": "TEST373378",
"active": true,
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2022-06-21T17:57:13+00:00"
},
"cashier": {
"id": "19ff96e0-993b-4403-a39f-42274484e3a9",
"full_name": "Тестовий кассир",
"nin": "000000000",
"key_id": "test_6323DqORy38jv2mu",
"signature_type": "TEST",
"permissions": null,
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2021-12-28T11:40:05+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" - блок з інформацією про першу транзакцію обраної зміни
GET метод /api/v1/cashier/shift дозволяє отримати розгорнуту інформацію про поточну активну зміну касира, яким був виконаний вхід на портал.
Якщо у касира є активна поточна зміна, то у відповіді від сервера ви отримаєте інформацію про цю зміну.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
GET "https://api.checkbox.ua/api/v1/cashier/shift" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiOWY2ODFhYTctZGZiNi00ZGZiLTk1ZDMtMGQ2NWM0YWJlNGI0Iiwic3ViIjoiNmZhOGEzNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjU0MjUyMzQ1LCJpYXQiOjE2NTQyNTIzNDV9.VcJLfw_yyaBTLfT-TLHcrBEDPIWWQ1MyOmgQVYK8_Lw"
connection: close
content-length: 3112
content-type: application/json
date: Tue,31 May 2022 17:52:22 GMT
server: nginx
x-correlation-id: 3e8cc0c122164e36b2adc80d6d7974b1
x-request-id: 542ab607-6b3e-4142-8ad4-fd17d47d8587
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "c4cdff4a-8583-4cc5-9648-f1f444ff5582",
"serial": 158,
"status": "OPENED",
"z_report": null,
"opened_at": "2022-05-31T17:50:58.909803+00:00",
"closed_at": null,
"initial_transaction": {
"id": "675a9113-f477-4f39-a2a2-6d966584ab2c",
"type": "SHIFT_OPEN",
"serial": 2063,
"status": "DONE",
"request_signed_at": "2022-05-31T17:51:02.536171+00:00",
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": "pjevQBsu0GQ",
"created_at": "2022-05-31T17:50:58.909803+00:00",
"updated_at": "2022-05-31T17:51:02.612778+00:00",
"previous_hash": "0464ce0194d621d6c6ac55fac73436ef710e59d3acd3581086f6031f7da3a6cb"
},
"closing_transaction": null,
"created_at": "2022-05-31T17:50:58.909803+00:00",
"updated_at": "2022-05-31T17:51:02.622897+00:00",
"balance": {
"initial": 0,
"balance": 0,
"cash_sales": 0,
"card_sales": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": null
},
"taxes": [
{
"id": "62116438-4732-4d6a-996a-886e66aae5aa",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-04T11:53:47+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "72ea0e31-1090-4b9c-be62-839f310326d2",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "7fa25ddf-6670-46b2-9d65-dfb6b6a14d0d",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "e5bc4129-8059-4b05-ba3d-40020babbba7",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "049f8685-4a07-4300-9739-ee7422fbda3f",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "9f03160c-650a-4cb6-b8b9-58ee14b6ba91",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "b0a5f11c-3574-475b-a374-49083d12e756",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "8ce09b2d-ec32-4593-a251-4e79c5432b3d",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"cash_register": {
"id": "6c8297a5-6003-47c0-b31e-cb0c84a5eb91",
"fiscal_number": "4000108640",
"active": true,
"created_at": "2021-08-04T09:51:11+00:00",
"updated_at": "2022-05-09T17:57:19+00:00"
}
}
"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" - блок з інформацією про першу транзакцію обраної зміни
Метод /api/v1/receipts/service дозволяє створити чек службового внесення або вилучення готівки. Для коректного створення такого чеку потрібно обов'язково передати у тілі запиту параметри type (має бути CASH за замовчуванням), value та label (має бути "Готівка" за замовчуванням).
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"payment": {
"type": "CASH",
"value": <сума у копійках, для створення чеку службового вилучення перед сумою має бути - >,
"label": "Готівка"
}
}
Приклад
POST "https://api.checkbox.ua/api/v1/receipts/service" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiZGJlMDFiOTAtYjI1ZS00NWJiLTkwZTEtYjkyNDQxMmNlYzhmIiwic3ViIjoiMTlmZjk2ZTAtOTkzYi00NDAzLWEzOWYtNDIyNzQ0ODRlM2E5IiwibmJmIjoxNjU2MjM0NTc3LCJpYXQiOjE2NTYyMzQ1Nzd9.K4NJXg2jk5ujlKo5Q5yk3H9qBh9fgxnMWidVY4kt3dc" -H "Content-Type: application/json" -d "{\"payment\":{\"type\":\"CASH\",\"value\":10,\"label\":\"Готівка\"}}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 4197
content-type: application/json
date: Sun,26 Jun 2022 09:19:16 GMT
location: https://api.checkbox.ua/api/v1/receipts/30b05eb7-a31c-4c52-818e-98239d0ec5b1
server: nginx
x-correlation-id: b8a2e74e4cf04d4da3f8ce0b434dc266
x-request-id: d448ce82-aa72-4639-8ff8-2394a96f3e6f
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "30b05eb7-a31c-4c52-818e-98239d0ec5b1",
"type": "SERVICE_IN",
"transaction": null,
"serial": 20,
"status": "DONE",
"goods": [],
"payments": [
{
"type": "CASH",
"pawnshop_is_return": null,
"value": 10,
"label": "Готівка"
}
],
"total_sum": 10,
"sum": 10,
"total_payment": 10,
"total_rest": 0,
"rest": 0,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2022-06-26T09:19:16.804027+00:00",
"updated_at": null,
"taxes": [],
"discounts": [],
"order_id": null,
"header": null,
"footer": null,
"barcode": null,
"custom": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": null,
"technical_return": false,
"currency_exchange": null,
"shift": {
"id": "aaea6117-89b4-41ea-b16c-a5923d0b197c",
"serial": 14,
"status": "OPENED",
"z_report": null,
"opened_at": "2022-06-26T09:10:41.535645+00:00",
"closed_at": null,
"initial_transaction": {
"id": "d19213ff-fa19-41cd-a476-55fe9e7961b4",
"type": "SHIFT_OPEN",
"serial": 47,
"status": "DONE",
"request_signed_at": "2022-06-26T09:10:41.652640+00:00",
"request_received_at": "2022-06-26T09:10:41.741785+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-O8xj8M",
"offline_id": null,
"created_at": "2022-06-26T09:10:41.535645+00:00",
"updated_at": "2022-06-26T09:10:41.773288+00:00",
"previous_hash": "5e81f9f94f6a315b795a81048b8bd82b38417a1191643fdab35402420ffd1ce7"
},
"closing_transaction": null,
"created_at": "2022-06-26T09:10:41.535645+00:00",
"updated_at": "2022-06-26T09:10:41.781972+00:00",
"balance": {
"initial": 455000,
"balance": 455020,
"cash_sales": 0,
"card_sales": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 20,
"service_out": 0,
"updated_at": "2022-06-26T09:19:16.804027+00:00"
},
"taxes": [
{
"id": "89e5ea23-8db7-49c3-b2b0-225e48d49f57",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "eb8cfde1-b31c-44d2-87d3-e99de7010909",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "a9710e9f-a5b3-454f-99b4-ce72b6e4b77f",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "c96591ea-c26b-471d-b428-14044af457d0",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "f008896b-6ed9-461f-9750-be4e60e7924f",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "3586cfd7-f6ea-488c-954b-289c1c1fac9c",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4ecd37bf-a063-4779-860b-cbf379d7bd79",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "1cd13551-ba7a-4705-b275-f34f3d789ff1",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"cash_register": {
"id": "cb6905fd-5296-45ba-be4d-79302cf43a59",
"fiscal_number": "TEST373378",
"active": true,
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2022-06-23T17:57:11+00:00"
},
"cashier": {
"id": "19ff96e0-993b-4403-a39f-42274484e3a9",
"full_name": "Тестовий кассир",
"nin": "000000000",
"key_id": "test_6323DqORy38jv2mu",
"signature_type": "TEST",
"permissions": {
"orders": true
},
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2021-12-28T11:40:05+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека, SERVICE_IN/SERVICE_OUT (СЛУЖБОВЕ ВНЕСЕННЯ/СЛУЖБОВЕ ВИЛУЧЕННЯ)
"transaction" - інформація про транзакцію чека. Оскільки службовий чек не відправляється у ДПС то за замовчуванням даний параметр буде мати значення null
"serial" - порядковий номер чека
"status" - статус чека
"goods" - блок даних з переліком товарів. Для службового чека цей перелік буде пустим.
"payments" - блок даних з інформацією про платежі
"total_sum" та "sum" - сума вартості товарів у чеку
"total_payment" - сума оплати за товари у чеку
"rest" та "total_rest" - сума здачі
"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" - блок з даними кастомізації чека. Докладніше про параметри, які можуть відображатись в даному блоці можете дізнатись тутcustom_check
"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
"currency_exchange" - блок даних, який стосується операцій валютного обміну. Не є актуальним для службового чека.
"shift" - блок з даними про поточну зміну
"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
"balance" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
"cash_register" - блок даних з інформацією про касу, на якій було створено чек
"cashier" - блок даних з інформацією про касира, який створив чек
"control_number" - контрольне число. Заповнюється сервером для фіскальних чеків, службовий матиме за замовчуванням даний параметр у null
Чек можна створити як у офлайн, так і у онлайн режимі. Метод /api/v1/receipts/sell призначений для створення чека як у онлайн, так і у офлайн режимі (але без можливості явно вказати офлайн фіскальний код або офлайн фіскальну дату. Якщо каса у офлайні, то сервер автоматично підставить поточну дату та вільний офлайн код). Метод /api/v1/receipts/sell-offline призначений для створення чека у офлайні і дозволяє явно вказати як фіскальну дату, так і фіскальний код.
Мінімальний набір даних для створення чека продажу включає в себе код товару, назву товару, ціну, кількість, тип оплати та суму оплати. Але взагалі чек може містити багато додаткових параметрів, які будуть описані у прикладі.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"id": "<UUID чека>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":
[
{
"good":
{
"code": "<Код товару>",
"name": "<Назва товару>",
"barcode": "<Штрих-код товару>",
"excise_barcode": "<цифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<Хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>"
}
]
},
{
"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": "<назва знижки або надбавки>"
}
]
},
"payments":
[
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
},
{
<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>
}
],
"rounding": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"order_id": "<UUID замовлення (вказується у випадку роботи з API у режимі замовлень)>",
"related_receipt_id": "<UUID пов'язаного чека>",
"previous_receipt_id": "<UUID попереднього чека>",
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"context": {
"additionalProp1": "<додаткова властивість 1>",
"additionalProp2": "<додаткова властивість 2>",
"additionalProp3": "<додаткова властивість 3>"
},
"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 візуалізацій>"
}
}
Приклад
POST "https://api.checkbox.ua/api/v1/receipts/sell" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiMTNiNzU0MmUtMDU3ZC00ZWI1LThmNGYtMTlhZmM5ZjBlNTgwIiwic3ViIjoiMTlmZjk2ZTAtOTkzYi00NDAzLWEzOWYtNDIyNzQ0ODRlM2E5IiwibmJmIjoxNjU2MzA4OTc3LCJpYXQiOjE2NTYzMDg5Nzd9.z1c4tq0BpdJHxs8xIK1j9Ak5NNfx0DDjOnckjcUxrGo" -H "Content-Type: application/json" -d "{\"id\":\"5b7d533c-97c8-4db7-8f5f-4b3aaca44a77\",\"cashier_name\":\"Ім'я касира\",\"departament\":\"Назва відділу\",\"goods\":[{\"good\":{\"code\":\"Код товару 1\",\"name\":\"Назва товару 1\",\"barcode\":\"A12345\",\"excise_barcodes\":[\"B12345\",\"C12345\"],\"header\":\"Хедер товару 1\",\"footer\":\"Футер товару 1\",\"price\":123,\"tax\":[1,8],\"uktzed\":\"0701\"},\"good_id\":\"cca43968-0bc9-4bb4-a6bd-cba39f81b039\",\"quantity\":1000,\"is_return\":false,\"discounts\":[{\"type\":\"DISCOUNT\",\"mode\":\"VALUE\",\"value\":1,\"tax_codes\":[1,8],\"name\":\"назва знижки\"}]},{\"good\":{\"code\":\"Код товару 2\",\"name\":\"Назва товару 2\",\"barcode\":\"A6789\",\"excise_barcodes\":[\"B12345\",\"C12345\"],\"header\":\"Хедер товару 2\",\"footer\":\"Футер товару 2\",\"price\":456,\"tax\":[8],\"uktzed\":\"0701\"},\"good_id\":\"45afc0ec-882d-48f0-9418-b398356395fc\",\"quantity\":1000,\"is_return\":false,\"discounts\":[{\"type\":\"EXTRA_CHARGE\",\"mode\":\"PERCENT\",\"value\":1,\"tax_codes\":[8],\"name\":\"назва надбавки\"}]}],\"delivery\":{\"email\":\"[email protected]\",\"phone\":\"380987777777\"},\"discounts\":[{\"type\":\"DISCOUNT\",\"mode\":\"PERCENT\",\"value\":5,\"tax_code\":8,\"name\":\"назва знижки на чек\"}],\"payments\":[{\"type\":\"CASH\",\"pawnshop_is_return\":false,\"value\":50,\"label\":\"Готівка\"},{\"type\":\"CASHLESS\",\"pawnshop_is_return\":false,\"value\":500,\"label\":\"Карта\",\"code\":1,\"commission\":1,\"card_mask\":\"**** **** **** 5555\",\"bank_name\":\"Приватбанк\",\"auth_code\":\"7777\",\"rrn\":\"98765\",\"payment_system\":\"LiqPay\",\"owner_name\":\"Покупець 1\",\"terminal\":\"Термінал 1\",\"acquirer_and_seller\":\"Privatbank\",\"receipt_no\":\"123456\",\"signature_required\":true}],\"rounding\":true,\"header\":\"хедер чека\",\"footer\":\"футер чека\",\"barcode\":\"AB12345\",\"related_receipt_id\":\"0642065e-c205-41aa-8376-7064be42183e\",\"previous_receipt_id\":\"0642065e-c205-41aa-8376-7064be42183e\",\"technical_return\":false,\"is_pawnshop\":false,\"custom\":{\"html_global_header\":\"<div style=\\\"border: solid; border-color: green; background: aqua; padding: 5px; text-align: center;\\\">\Receipt header\</div>\",\"html_global_footer\":\"<div style=\\\"border: solid; border-color: green; background: aqua; padding: 5px; text-align: center;\\\">\Receipt Footer\</div>\",\"html_body_style\":\"background: rgb(0,91,188);\background: linear-gradient(179deg, rgba(0,91,188,1) 49%, rgba(87,110,255,1) 50%, rgba(255,214,0,1) 51%);\",\"html_receipt_style\":\"background: white !important;\border-radius: 0 !important;\box-shadow: 1px 2px 13px 7px #c1e5e5;\color: #005bbc;\",\"html_ruler_style\":\"color: red !important;\",\"html_light_block_style\":\"color: #ffd600 !important;\",\"text_global_header\":\"Example\---\===\--\Header\",\"text_global_footer\":\"Footer\---\===\--\Example\"}}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 7274
content-type: application/json
date: Mon,27 Jun 2022 08:24:46 GMT
location: https://api.checkbox.ua/api/v1/receipts/5b7d533c-97c8-4db7-8f5f-4b3aaca44a77
server: nginx
x-correlation-id: 1717d46998f64cd999d1396b15febba8
x-request-id: 0ff6b120-b0c5-4c40-9c35-28c32f5b3baa
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "5b7d533c-97c8-4db7-8f5f-4b3aaca44a77",
"type": "SELL",
"transaction": {
"id": "0e79f4df-aa59-4c49-a683-94d0b9aa17d4",
"type": "RECEIPT",
"serial": 72,
"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": "2022-06-27T08:24:46.501940+00:00",
"updated_at": "2022-06-27T08:24:46.501940+00:00",
"previous_hash": "484994e69cd42fd21d8a00611aac1b2c4fca34a7325c0580c0650a1580f8b346"
},
"serial": 40,
"status": "CREATED",
"goods": [
{
"good": {
"code": "Код товару 1",
"barcode": "A12345",
"name": "Назва товару 1",
"excise_barcodes": [
"B12345",
"C12345"
],
"header": "Хедер товару 1",
"footer": "Футер товару 1",
"uktzed": "0701",
"price": 123
},
"good_id": "cca43968-0bc9-4bb4-a6bd-cba39f81b039",
"sum": 123,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "15e6a708-3a82-4a1e-9353-93f6912ebc16",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"value": 19,
"extra_value": 0
},
{
"id": "77815b4c-1f8f-47dc-b9f3-fbfab212c71f",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 1,
"tax_code": null,
"tax_codes": [
1,
8
],
"name": "назва знижки",
"sum": -1
}
]
},
{
"good": {
"code": "Код товару 2",
"barcode": "A6789",
"name": "Назва товару 2",
"excise_barcodes": [
"B12345",
"C12345"
],
"header": "Хедер товару 2",
"footer": "Футер товару 2",
"uktzed": "0701",
"price": 456
},
"good_id": "45afc0ec-882d-48f0-9418-b398356395fc",
"sum": 456,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "9f528c6f-4a5e-4068-bb3e-12cc20a68880",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "EXTRA_CHARGE",
"mode": "PERCENT",
"value": 1,
"tax_code": null,
"tax_codes": [
8
],
"name": "назва надбавки",
"sum": 5
}
]
}
],
"payments": [
{
"type": "CASH",
"pawnshop_is_return": false,
"value": 50,
"label": "Готівка"
},
{
"type": "CASHLESS",
"pawnshop_is_return": false,
"code": 1,
"value": 500,
"commission": null,
"label": "Карта",
"card_mask": "**** **** **** 5555",
"bank_name": "Приватбанк",
"auth_code": "7777",
"rrn": "98765",
"payment_system": "LiqPay",
"owner_name": "Покупець 1",
"terminal": "Термінал 1",
"acquiring": "Privatbank",
"acquirer_and_seller": "Privatbank",
"receipt_no": "123456",
"signature_required": true
}
],
"total_sum": 554,
"sum": 554,
"total_payment": 550,
"total_rest": 0,
"rest": 0,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2022-06-27T08:24:46.501940+00:00",
"updated_at": null,
"taxes": [
{
"id": "13072f5d-06b1-44fb-8e45-23dbd8992e67",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"value": 19,
"extra_value": 0
},
{
"id": "e47a1102-1884-43d4-9a13-8568d9822459",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "PERCENT",
"value": 5,
"tax_code": null,
"tax_codes": [
8
],
"name": "назва знижки на чек",
"sum": -29
}
],
"order_id": null,
"header": "хедер чека",
"footer": "футер чека",
"barcode": "AB12345",
"custom": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": "0642065e-c205-41aa-8376-7064be42183e",
"technical_return": false,
"currency_exchange": null,
"shift": {
"id": "b992a702-9aec-4bc6-86fc-9030eda4b8ee",
"serial": 17,
"status": "OPENED",
"z_report": null,
"opened_at": "2022-06-26T15:29:47.864936+00:00",
"closed_at": null,
"initial_transaction": {
"id": "ba54df9e-305d-4bad-a405-049c761c4608",
"type": "SHIFT_OPEN",
"serial": 57,
"status": "DONE",
"request_signed_at": "2022-06-26T15:29:47.974951+00:00",
"request_received_at": "2022-06-26T15:29:48.036582+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-odtJgB",
"offline_id": null,
"created_at": "2022-06-26T15:29:47.864936+00:00",
"updated_at": "2022-06-26T15:29:48.061802+00:00",
"previous_hash": "7cff99f6c2fe224bf6c975f02dc7cc03a75643e2bc054d05a269a5439a448da2"
},
"closing_transaction": null,
"created_at": "2022-06-26T15:29:47.864936+00:00",
"updated_at": "2022-06-26T15:29:48.070090+00:00",
"balance": {
"initial": 455020,
"balance": 455114,
"cash_sales": 94,
"card_sales": 456956,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2022-06-27T08:21:46.112322+00:00"
},
"taxes": [
{
"id": "13072f5d-06b1-44fb-8e45-23dbd8992e67",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"sales": 19,
"returns": 0,
"sales_turnover": 116,
"returns_turnover": 0
},
{
"id": "948549a0-e719-4d52-ae44-f50787b3351f",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "f1e49ad9-533d-4b5c-a1ec-935db06d8f02",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "4cf3f4e1-1190-46da-b2cc-fdeb35f4f6da",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "78d89ba8-cc0a-450a-9ccf-3e6014d7da2d",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "8c57764a-28a8-48e6-9071-a5875655f045",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "fd3f4573-58f2-4499-9fb9-2fecd0e08c64",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "e47a1102-1884-43d4-9a13-8568d9822459",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 454054,
"returns_turnover": 0
}
],
"cash_register": {
"id": "cb6905fd-5296-45ba-be4d-79302cf43a59",
"fiscal_number": "TEST373378",
"active": true,
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2022-06-26T23:40:03+00:00"
},
"cashier": {
"id": "19ff96e0-993b-4403-a39f-42274484e3a9",
"full_name": "Тестовий кассир",
"nin": "000000000",
"key_id": "test_6323DqORy38jv2mu",
"signature_type": "TEST",
"permissions": {
"orders": true
},
"created_at": "2021-12-27T03:30:50+00:00",
"updated_at": "2021-12-28T11:40:05+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека, SERVICE_IN/SERVICE_OUT (СЛУЖБОВЕ ВНЕСЕННЯ/СЛУЖБОВЕ ВИЛУЧЕННЯ)
"transaction" - інформація про транзакцію чека.
"taxes" - блок даних з інформацією про податкові ставки, які використовувались для товару в чеку
"discounts" - блок даних про знижки по товару.
"payments" - блок даних з інформацією про платежі
"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" - блок даних про податки, які використовувались для всього чеку
"discounts" - блок даних про знижки, які застосовувались до всього чеку.
"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" - блок з даними про поточну зміну
"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
"balance" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
"cash_register" - блок даних з інформацією про касу, на якій було створено чек
"cashier" - блок даних з інформацією про касира, який створив чек
"control_number" - контрольне число, яке отримує офлайн чек після обробки сервером. Чек, створений у онлайн режимі згідно діючого законодавства не має містити такого реквізиту, а отже значення буде null для онлайн чеку.
Перед створенням офлайн чеку касу потрібно перевести у офлайн режим, інакше ви отримаєте від API помилку виду "message": "Cash register should be in manual offline mode!". Метод переходу у офлайн описаний у відповідному розділі даного документу.
Від методу /api/v1/receipts/sell метод /api/v1/receipts/sell-offline відрізняється наявністю полів "fiscal_code" та "fiscal_date":, які є обов'язковими та вказуються наприкінці пейлоаду чеку.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"id": "<UUID чека>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":
[
{
"good":
{
"code": "<Код товару>",
"name": "<Назва товару>",
"barcode": "<Штрих-код товару>",
"excise_barcode": "<цифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<Хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>"
}
]
},
{
"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": "<назва знижки або надбавки>"
}
]
},
"payments":
[
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
},
{
<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>
}
],
"rounding": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"order_id": "<UUID замовлення (вказується у випадку роботи з API у режимі замовлень)>",
"related_receipt_id": "<UUID пов'язаного чека>",
"previous_receipt_id": "<UUID попереднього чека>",
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"context": {
"additionalProp1": "<додаткова властивість 1>",
"additionalProp2": "<додаткова властивість 2>",
"additionalProp3": "<додаткова властивість 3>"
},
"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>"
}
Приклад
POST "https://api.checkbox.ua/api/v1/receipts/sell-offline" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiNGU3ZmIzOGYtMGRhMi00YzRkLWJlNWItMjdjOGQ3MGM4YmIwIiwic3ViIjoiYmM4N2IwOTMtNmFmYy00Zjk2LTk1OGUtYzdjZGQxZTc3ZTIwIiwibmJmIjoxNjU2ODI4MjYyLCJpYXQiOjE2NTY4MjgyNjJ9.EjjIiRP8qhgVOZSp_CegdVdeyCQHusnMJOBZHAUk294" -H "Content-Type: application/json" -d "{\"id\":\"f189bc49-1a52-4176-96ea-732f76f14aad\",\"cashier_name\":\"Ім'я касира\",\"departament\":\"Назва відділу\",\"goods\":[{\"good\":{\"code\":\"Код товару 1\",\"name\":\"Назва товару 1\",\"barcode\":\"A12345\",\"excise_barcodes\":[\"B12345\",\"C12345\"],\"header\":\"Хедер товару 1\",\"footer\":\"Футер товару 1\",\"price\":123,\"tax\":[1,8],\"uktzed\":\"0701\"},\"good_id\":\"cca43968-0bc9-4bb4-a6bd-cba39f81b039\",\"quantity\":1000,\"is_return\":false,\"discounts\":[{\"type\":\"DISCOUNT\",\"mode\":\"VALUE\",\"value\":1,\"tax_codes\":[1,8],\"name\":\"назва знижки\"}]},{\"good\":{\"code\":\"Код товару 2\",\"name\":\"Назва товару 2\",\"barcode\":\"A6789\",\"excise_barcodes\":[\"B12345\",\"C12345\"],\"header\":\"Хедер товару 2\",\"footer\":\"Футер товару 2\",\"price\":456,\"tax\":[8],\"uktzed\":\"0701\"},\"good_id\":\"45afc0ec-882d-48f0-9418-b398356395fc\",\"quantity\":1000,\"is_return\":false,\"discounts\":[{\"type\":\"EXTRA_CHARGE\",\"mode\":\"PERCENT\",\"value\":1,\"tax_codes\":[8],\"name\":\"назва надбавки\"}]}],\"delivery\":{\"email\":\"[email protected]\",\"phone\":\"380980337777\"},\"discounts\":[{\"type\":\"DISCOUNT\",\"mode\":\"PERCENT\",\"value\":5,\"tax_code\":8,\"name\":\"назва знижки на чек\"}],\"payments\":[{\"type\":\"CASH\",\"pawnshop_is_return\":false,\"value\":50,\"label\":\"Готівка\"},{\"type\":\"CASHLESS\",\"pawnshop_is_return\":false,\"value\":500,\"label\":\"Карта\",\"code\":1,\"commission\":1,\"card_mask\":\"**** **** **** 5555\",\"bank_name\":\"Приватбанк\",\"auth_code\":\"7777\",\"rrn\":\"98765\",\"payment_system\":\"LiqPay\",\"owner_name\":\"Покупець 1\",\"terminal\":\"Термінал 1\",\"acquirer_and_seller\":\"Privatbank\",\"receipt_no\":\"123456\",\"signature_required\":true}],\"rounding\":true,\"header\":\"хедер чека\",\"footer\":\"футер чека\",\"barcode\":\"AB12345\",\"related_receipt_id\":\"2e8b57cf-d500-4f29-9fd4-9b9954ad4daf\",\"previous_receipt_id\":\"2e8b57cf-d500-4f29-9fd4-9b9954ad4daf\",\"technical_return\":false,\"is_pawnshop\":false,\"custom\":{\"html_global_header\":\"<div style=\\\"border: solid; border-color: green; background: aqua; padding: 5px; text-align: center;\\\">\Receipt header\</div>\",\"html_global_footer\":\"<div style=\\\"border: solid; border-color: green; background: aqua; padding: 5px; text-align: center;\\\">\Receipt Footer\</div>\",\"html_body_style\":\"background: rgb(0,91,188);\background: linear-gradient(179deg, rgba(0,91,188,1) 49%, rgba(87,110,255,1) 50%, rgba(255,214,0,1) 51%);\",\"html_receipt_style\":\"background: white !important;\border-radius: 0 !important;\box-shadow: 1px 2px 13px 7px #c1e5e5;\color: #005bbc;\",\"html_ruler_style\":\"color: red !important;\",\"html_light_block_style\":\"color: #ffd600 !important;\",\"text_global_header\":\"Example\---\===\--\Header\",\"text_global_footer\":\"Footer\---\===\--\Example\"},\"fiscal_code\":\"TEST-Xd-V3m\",\"fiscal_date\":\"2022-07-03T09:39:19.497+03:00\"}"
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 7497
content-type: application/json
date: Sun,03 Jul 2022 06:44:06 GMT
location: https://api.checkbox.ua/api/v1/receipts/f189bc49-1a52-4176-96ea-732f76f14aad
server: nginx
x-correlation-id: 411ee33d7d7649808f6490bb8659e026
x-request-id: 84dc42a7-41f7-4115-b662-418523b9f877
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "f189bc49-1a52-4176-96ea-732f76f14aad",
"type": "SELL",
"transaction": {
"id": "2643daf4-a66f-4d96-b88e-a0985f674932",
"type": "RECEIPT",
"serial": 52,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": "TEST-Xd-V3m",
"created_at": "2022-07-03T06:44:06.385318+00:00",
"updated_at": "2022-07-03T06:44:06.385318+00:00",
"previous_hash": "5b7d8faf10df12069585384fb6aec59e0f01daf99b50429b2fd90cd8c99f6e32"
},
"serial": 4,
"status": "DONE",
"goods": [
{
"good": {
"code": "Код товару 1",
"barcode": "A12345",
"name": "Назва товару 1",
"excise_barcodes": [
"B12345",
"C12345"
],
"header": "Хедер товару 1",
"footer": "Футер товару 1",
"uktzed": "0701",
"price": 123
},
"good_id": "cca43968-0bc9-4bb4-a6bd-cba39f81b039",
"sum": 123,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "8e177128-b6a0-4012-b74b-579d5805eec7",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"value": 19,
"extra_value": 0
},
{
"id": "c386b92b-d9ee-4791-ac80-cf4efcbe82e7",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 1,
"tax_code": null,
"tax_codes": [
1,
8
],
"name": "назва знижки",
"sum": -1
}
]
},
{
"good": {
"code": "Код товару 2",
"barcode": "A6789",
"name": "Назва товару 2",
"excise_barcodes": [
"B12345",
"C12345"
],
"header": "Хедер товару 2",
"footer": "Футер товару 2",
"uktzed": "0701",
"price": 456
},
"good_id": "45afc0ec-882d-48f0-9418-b398356395fc",
"sum": 456,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "5741d215-1303-4010-9fa8-c8fb91bdf165",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "EXTRA_CHARGE",
"mode": "PERCENT",
"value": 1,
"tax_code": null,
"tax_codes": [
8
],
"name": "назва надбавки",
"sum": 5
}
]
}
],
"payments": [
{
"type": "CASH",
"pawnshop_is_return": false,
"value": 50,
"label": "Готівка"
},
{
"type": "CASHLESS",
"pawnshop_is_return": false,
"code": 1,
"value": 500,
"commission": null,
"label": "Карта",
"card_mask": "**** **** **** 5555",
"bank_name": "Приватбанк",
"auth_code": "7777",
"rrn": "98765",
"payment_system": "LiqPay",
"owner_name": "Покупець 1",
"terminal": "Термінал 1",
"acquiring": "Privatbank",
"acquirer_and_seller": "Privatbank",
"receipt_no": "123456",
"signature_required": true
}
],
"total_sum": 554,
"sum": 554,
"total_payment": 550,
"total_rest": 0,
"rest": 0,
"fiscal_code": "TEST-Xd-V3m",
"fiscal_date": "2022-07-03T06:39:19.497000+00:00",
"delivered_at": null,
"created_at": "2022-07-03T06:39:19.497000+00:00",
"updated_at": "2022-07-03T06:44:06.849246+00:00",
"taxes": [
{
"id": "0f833d8f-b5f5-467d-a1a2-9db0f811feee",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"value": 19,
"extra_value": 0
},
{
"id": "8fa1e5f4-9015-4aee-885f-7c835f3c2967",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "PERCENT",
"value": 5,
"tax_code": null,
"tax_codes": [
8
],
"name": "назва знижки на чек",
"sum": -29
}
],
"order_id": null,
"header": "хедер чека",
"footer": "футер чека",
"barcode": "AB12345",
"custom": null,
"is_created_offline": true,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": "https://cabinet.tax.gov.ua/cashregs/check?id=TEST-Xd-V3m&date=20220703&time=09%3A39%3A19&fn=TEST074280&mac=5b7d8faf10df12069585384fb6aec59e0f01daf99b50429b2fd90cd8c99f6e32",
"related_receipt_id": "2e8b57cf-d500-4f29-9fd4-9b9954ad4daf",
"technical_return": false,
"currency_exchange": null,
"shift": {
"id": "c267c19f-6b75-4875-be0d-961698bfe27c",
"serial": 3,
"status": "OPENED",
"z_report": null,
"opened_at": "2022-07-03T06:05:28.837973+00:00",
"closed_at": null,
"initial_transaction": {
"id": "b1cb570c-34a2-4fd3-a64b-68d68d4fe569",
"type": "SHIFT_OPEN",
"serial": 45,
"status": "DONE",
"request_signed_at": "2022-07-03T06:05:28.960977+00:00",
"request_received_at": "2022-07-03T06:05:29.039861+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-RDWLn5",
"offline_id": null,
"created_at": "2022-07-03T06:05:28.837973+00:00",
"updated_at": "2022-07-03T06:05:29.066714+00:00",
"previous_hash": "cb6147271be7b511ddfae2186bdfe97deac1a83c762fcd6adc99c7b765de706b"
},
"closing_transaction": null,
"created_at": "2022-07-03T06:05:28.837973+00:00",
"updated_at": "2022-07-03T06:05:29.075163+00:00",
"balance": {
"initial": 0,
"balance": 1350,
"cash_sales": 1350,
"card_sales": 1500,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2022-07-03T06:44:06.385318+00:00"
},
"taxes": [
{
"id": "0f833d8f-b5f5-467d-a1a2-9db0f811feee",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"sales": 57,
"returns": 0,
"sales_turnover": 348,
"returns_turnover": 0
},
{
"id": "e5320055-802d-4360-99b3-ae1bd9f5ed45",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "aa644d08-5087-4af5-9f58-690489d21a57",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "912d65e5-7c71-4de0-9959-c7d9d5ddd972",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "c65eb036-3129-4585-b9ab-7371c70d50d7",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "bea8a848-20de-4d67-bc04-7bb0ed0d767c",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "c41f99f4-4717-4e1a-8ef9-ac79be5f4dbc",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "8fa1e5f4-9015-4aee-885f-7c835f3c2967",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 2862,
"returns_turnover": 0
}
],
"cash_register": {
"id": "09e2cbe6-dd38-4655-9d8b-4fc58b10530e",
"fiscal_number": "TEST074280",
"active": true,
"created_at": "2021-12-27T03:30:51+00:00",
"updated_at": "2022-06-29T17:57:12+00:00"
},
"cashier": {
"id": "bc87b093-6afc-4f96-958e-c7cdd1e77e20",
"full_name": "Тестовий кассир",
"nin": "000000000",
"key_id": "test_RY8XfV3aMJRKcsnQ",
"signature_type": "TEST",
"permissions": null,
"created_at": "2021-12-27T03:30:51+00:00",
"updated_at": "2021-12-28T11:40:05+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": "4901"
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека, SERVICE_IN/SERVICE_OUT (СЛУЖБОВЕ ВНЕСЕННЯ/СЛУЖБОВЕ ВИЛУЧЕННЯ)
"transaction" - інформація про транзакцію чека.
"taxes" - блок даних з інформацією про податкові ставки, які використовувались для товару в чеку
"discounts" - блок даних про знижки по товару.
"payments" - блок даних з інформацією про платежі
"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" - блок даних про податки, які використовувались для всього чеку
"discounts" - блок даних про знижки, які застосовувались до всього чеку.
"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" - блок з даними про поточну зміну
"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
"balance" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
"cash_register" - блок даних з інформацією про касу, на якій було створено чек
"cashier" - блок даних з інформацією про касира, який створив чек
"control_number" - контрольне число, яке отримує офлайн чек після обробки сервером. Чек, створений у онлайн режимі згідно діючого законодавства не має містити такого реквізиту, а отже значення буде null для онлайн чеку.
X та Z звіти дуже схожі за своєю структурою, проте між ними є принципова різниця - створення Z - звіту означає закриття поточної касової зміни. X - звіт, в свою чергу, зміну не закриває.
Для створення X-звіту потрібно використовувати метод /api/v1/reports Create X Report
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
POST "https://api.checkbox.ua/api/v1/reports" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiNGU3ZmIzOGYtMGRhMi00YzRkLWJlNWItMjdjOGQ3MGM4YmIwIiwic3ViIjoiYmM4N2IwOTMtNmFmYy00Zjk2LTk1OGUtYzdjZGQxZTc3ZTIwIiwibmJmIjoxNjU2ODI4MjYyLCJpYXQiOjE2NTY4MjgyNjJ9.EjjIiRP8qhgVOZSp_CegdVdeyCQHusnMJOBZHAUk294" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 2747
content-type: application/json
date: Sun,03 Jul 2022 07:04:10 GMT
location: https://api.checkbox.ua/api/v1/reports/adad2993-3359-499e-a8de-34c5753e8918
server: nginx
x-correlation-id: d24682316e5b4fbd80fcd94ab1ca1470
x-request-id: 7049e63d-851d-47f0-9931-0c4a16823083
x-robots-tag: noindex,nofollow,nosnippet,noarchive
{
"id": "adad2993-3359-499e-a8de-34c5753e8918",
"serial": 1,
"is_z_report": false,
"payments": [
{
"id": "d2a7f7fe-1604-4561-9695-f88eabeb9421",
"code": null,
"type": "CASH",
"label": "Готівка",
"sell_sum": 1350,
"return_sum": 0,
"service_in": 0,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
},
{
"id": "8875f3e4-f3cc-4e73-9f30-e4b684ac3896",
"code": 1,
"type": "CASHLESS",
"label": "Карта",
"sell_sum": 1500,
"return_sum": 0,
"service_in": 0,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
}
],
"taxes": [
{
"id": "6bb3f68a-bdc4-4705-8928-592ce9e22241",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"sell_sum": 57,
"return_sum": 0,
"sales_turnover": 348,
"returns_turnover": 0,
"created_at": "2022-05-31T23:34:24+00:00",
"setup_date": "2022-05-31T23:34:24+00:00"
},
{
"id": "3f1d8e76-43be-43f8-8722-8308d4d60730",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:25:00+00:00",
"setup_date": "2022-02-16T13:25:00+00:00"
},
{
"id": "ffa01bd5-9f22-40f8-8843-d2beff3c1045",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-17T23:51:18+00:00",
"setup_date": "2022-02-17T23:51:18+00:00"
},
{
"id": "6dfb516c-1dd6-47f2-917e-9f1d76cf3e21",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-03-22T15:19:02+00:00",
"setup_date": "2022-03-22T15:19:02+00:00"
},
{
"id": "1f145d95-7bec-40c8-914f-23e9d25925fc",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:36:10+00:00",
"setup_date": "2022-02-16T13:36:10+00:00"
},
{
"id": "833cd92f-61e9-4ba2-987a-89b191d1638b",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1.5,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:36:17+00:00",
"setup_date": "2022-02-16T13:36:17+00:00"
},
{
"id": "5b0b24bf-acff-49b2-ab9c-1e4f48e6d7f7",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-23T18:59:04+00:00",
"setup_date": "2022-02-23T18:59:04+00:00"
},
{
"id": "44f1afbc-e15e-474a-a416-66b9740e3030",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 2862,
"returns_turnover": 0,
"created_at": "2022-03-22T15:19:17+00:00",
"setup_date": "2022-03-22T15:19:17+00:00"
}
],
"sell_receipts_count": 4,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 0,
"transfers_count": 0,
"transfers_sum": 0,
"balance": 1350,
"initial": 0,
"created_at": "2022-07-03T07:04:10.319954+00:00",
"updated_at": null
}
"id" - унікальний ідентифікатор звіту у форматі UUID
"serial" - порядковий номер звіту
"is_z_report" - флаг true/false, який визначає, чи є даний звіт Z-звітом. Для X-звіту завжди false.
"payments" - блок з інформацією про платежі в рамках поточної зміни
Для створення Z-звіту потрібно використовувати метод /api/v1/shifts/close Close Shift
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
Якщо тіло запиту залишити порожнім, то всі дані по Z-звіту будуть сформовані на боці серверу. У випадку заповнення даних звіту у тілі запиту він сформується у тому вигляді, в якому ви його заповнили (з усіма можливими помилками в даних). Тобто при ручному заповнені полів z-звіту ви маєте робити всі необхідні розрахунки на своєму боці.
{
"skip_client_name_check": <true/false флаг деактивації/активації перевірки програми-клієнта, через яку відкривали зміну. Дана перевірка допомагає уникнути помилок в роботі у випадку, якщо ваш клієнт паралельно з API задумає скористатись локальним офлайн агентом Checkbox Kasa, що є неприпустимим та може мати негативні наслідки у вигляді поломки каси. За замовчуванням має лишатись false>,
"report": {
"id": "<унікальний ідентифікатор звіту у форматі UUID>",
"serial": <порядковий номер звіту>,
"payments": [
{
"type": "CASH",
"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>"
}
],
"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": "<фіскальна дата звіту (тільки для створення звіту у офлайн режимі)>"
}
Приклад
POST "https://api.checkbox.ua/api/v1/shifts/close" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiNGU3ZmIzOGYtMGRhMi00YzRkLWJlNWItMjdjOGQ3MGM4YmIwIiwic3ViIjoiYmM4N2IwOTMtNmFmYy00Zjk2LTk1OGUtYzdjZGQxZTc3ZTIwIiwibmJmIjoxNjU2ODI4MjYyLCJpYXQiOjE2NTY4MjgyNjJ9.EjjIiRP8qhgVOZSp_CegdVdeyCQHusnMJOBZHAUk294" -H "Content-Type: application/json" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 6163
content-type: application/json
date: Sun,03 Jul 2022 09:40:14 GMT
server: nginx
x-correlation-id: eacee6bc84eb42a3a6628595f16a9888
x-request-id: 7a2f015e-cb01-4a03-a65b-3225ae733e65
{
"id": "12bcd4fb-5329-4375-b6c9-33c2c2c5f3b1",
"serial": 9,
"status": "CLOSING",
"z_report": {
"id": "03be91b3-efd2-4ed0-ac9f-09b408c52e1a",
"serial": 8,
"is_z_report": true,
"payments": [],
"taxes": [
{
"id": "801507af-3990-4eaf-be18-4eaa80735709",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-05-31T23:34:24+00:00",
"setup_date": "2022-05-31T23:34:24+00:00"
},
{
"id": "9bcdf953-b436-4e9f-ad34-d695c1f42ddc",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:25:00+00:00",
"setup_date": "2022-02-16T13:25:00+00:00"
},
{
"id": "0ba602ba-8e8f-4f27-bf60-b7f6e04e8bb1",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-17T23:51:18+00:00",
"setup_date": "2022-02-17T23:51:18+00:00"
},
{
"id": "723082fe-d835-4ec0-8d8e-a7760165842b",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-03-22T15:19:02+00:00",
"setup_date": "2022-03-22T15:19:02+00:00"
},
{
"id": "146d42ec-1875-4288-81b6-e0ee8f26f9f9",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:36:10+00:00",
"setup_date": "2022-02-16T13:36:10+00:00"
},
{
"id": "92719c60-b55f-4a8b-8963-939279e87392",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1.5,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-16T13:36:17+00:00",
"setup_date": "2022-02-16T13:36:17+00:00"
},
{
"id": "2d0c5ad8-8280-47cc-9e59-801fe0647fda",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-02-23T18:59:04+00:00",
"setup_date": "2022-02-23T18:59:04+00:00"
},
{
"id": "edee1439-e4c0-4419-bbca-73a8e9595ba1",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"sell_sum": 0,
"return_sum": 0,
"sales_turnover": 0,
"returns_turnover": 0,
"created_at": "2022-03-22T15:19:17+00:00",
"setup_date": "2022-03-22T15:19:17+00:00"
}
],
"sell_receipts_count": 0,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 0,
"transfers_count": 0,
"transfers_sum": 0,
"balance": 2398,
"initial": 2398,
"created_at": "2022-07-03T09:40:13.925627+00:00",
"updated_at": null
},
"opened_at": "2022-07-03T09:40:05.411194+00:00",
"closed_at": null,
"initial_transaction": {
"id": "e85e2ed3-5bd6-419c-bf73-97f895a23b34",
"type": "SHIFT_OPEN",
"serial": 75,
"status": "DONE",
"request_signed_at": "2022-07-03T09:40:05.547557+00:00",
"request_received_at": "2022-07-03T09:40:05.624398+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-4KBb10",
"offline_id": null,
"created_at": "2022-07-03T09:40:05.411194+00:00",
"updated_at": "2022-07-03T09:40:05.651625+00:00",
"previous_hash": "83dd449f0ab99183d238d63fe0c036479bdde2eb40516423c7c19468a10d727b"
},
"closing_transaction": {
"id": "4be7fe4f-360d-44ae-91f7-fa44ae4da3a1",
"type": "Z_REPORT",
"serial": 76,
"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": "2022-07-03T09:40:13.891125+00:00",
"updated_at": null,
"previous_hash": "abca189776c642240f8fcbeb6157c1c761651f54e0733db8efda380405a49287"
},
"created_at": "2022-07-03T09:40:05.411194+00:00",
"updated_at": "2022-07-03T09:40:13.925627+00:00",
"balance": {
"initial": 2398,
"balance": 2398,
"cash_sales": 0,
"card_sales": 0,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": null
},
"taxes": [
{
"id": "75df4684-82eb-4e1c-989d-e452b082a3bc",
"code": 1,
"label": "ПДВ",
"symbol": "А",
"rate": 20,
"extra_rate": 0,
"included": true,
"created_at": "2022-05-31T23:34:24+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "7b14d411-82cd-4744-a094-b52dabcb9866",
"code": 2,
"label": "ПДВ 7%",
"symbol": "Б",
"rate": 7,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:25:00+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "a3106151-c712-4fb4-93af-44181862e46e",
"code": 3,
"label": "ПДВ 14%",
"symbol": "В",
"rate": 14,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-17T23:51:18+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "909bca5f-378b-429f-abe7-40999a3d1632",
"code": 4,
"label": "ПДВ+Акциз",
"symbol": "Г",
"rate": 20,
"extra_rate": 5,
"included": true,
"created_at": "2022-03-22T15:19:02+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "785d4023-dc46-4a05-86d2-4905c1eccba8",
"code": 5,
"label": "Акциз",
"symbol": "Д",
"rate": 0,
"extra_rate": 5,
"included": true,
"created_at": "2022-02-16T13:36:10+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "832cbecf-e39f-4531-ae9c-713fcff30c4a",
"code": 6,
"label": "ВЗ",
"symbol": "Е",
"rate": 1,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-16T13:36:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "554c8800-3980-4909-a835-002333091d13",
"code": 7,
"label": "ПДВ 0%",
"symbol": "Ж",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-02-23T18:59:04+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
},
{
"id": "050e8403-4c57-46a6-bc87-e43e84f6d6fe",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": 0,
"included": true,
"created_at": "2022-03-22T15:19:17+00:00",
"updated_at": null,
"sales": 0,
"returns": 0,
"sales_turnover": 0,
"returns_turnover": 0
}
],
"cash_register": {
"id": "09e2cbe6-dd38-4655-9d8b-4fc58b10530e",
"fiscal_number": "TEST074280",
"active": true,
"created_at": "2021-12-27T03:30:51+00:00",
"updated_at": "2022-06-29T17:57:12+00:00"
},
"cashier": {
"id": "bc87b093-6afc-4f96-958e-c7cdd1e77e20",
"full_name": "Тестовий кассир",
"nin": "000000000",
"key_id": "test_RY8XfV3aMJRKcsnQ",
"signature_type": "TEST",
"permissions": null,
"created_at": "2021-12-27T03:30:51+00:00",
"updated_at": "2021-12-28T11:40:05+00:00",
"certificate_end": null,
"blocked": null
}
}
"id" - унікальний ідентифікатор зміни у форматі UUID
"serial" - порядковий номер зміни
"status" - статус зміни CREATED/OPENED/CLOSING/CLOSED (СТВОРЕНА/ВІДКРИТА/ЗАКРИВАЄТЬСЯ/ЗАКРИТА)
"z_report" - блок з інформацією по Z-звіту
"payments" - блок з інформацією про платежі в рамках поточної зміни
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
"sell_receipts_count" - кількість чеків продажу
"return_receipts_count" - кількість чеків повернення
"cash_withdrawal_receipts_count" - кількість чеків по операціям з видачі готівкових коштів
"balance" - баланс каси у копійках на момент створення звіту
"initial" - баланс каси у копійках на момент відкриття зміни
"created_at" - мітка часу створення звіту у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - мітка часу останнього оновлення даних звіту у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm.
"initial_transaction" - - блок даних про першу транзакцію у зміні.
"closing_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" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
"cashier" - блок даних з інформацією про касира
Сам токен доступу - не має чіткого строку життя. Проте рекомендуємо його періодично змінювати для забезпечення безпеки передачі даних. Для деактивації усіх активних токенів касира достатньо виконати заміну пароля касира в особистому кабінеті Checkbox у розділі Касири.
Якщо вам потрібно завершити сесію користувача (касира) з поточним токеном доступу та скасувати токен - використайте метод POST /api/v1/cashier/signout
У випадку успішного виконання запиту ви отримаєте код 205 Successful Response.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
Тіло запиту у даному випадку має бути порожнім
Приклад
POST "https://api.checkbox.ua/api/v1/cashier/signout" -H "accept: application/json" -H "X-Client-Name: Integration" -H "X-Client-Version: 1.0" -H "X-Access-Key: _f63SZRQD5v3cdXBHRCO20D1A-TrwFDOrMWTDFGmzyNViVaVcf0XPujDoBXBpqNQ" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiQVBJIiwianRpIjoiOWY2ODFhYTctZGZiNi00ZGZiLTk1ZDMtMGQ2NWM0YWJlNGI0Iiwic3ViIjoiNmZhOGEzNDgtMGZjOC00NTViLThjMjktODk1MzNiNTM5YzQxIiwibmJmIjoxNjU0MjUyMzQ1LCJpYXQiOjE2NTQyNTIzNDV9.VcJLfw_yyaBTLfT-TLHcrBEDPIWWQ1MyOmgQVYK8_Lw" -d ""
access-control-allow-credentials: true
access-control-allow-origin: https://api.checkbox.ua
connection: close
content-length: 4
content-type: application/json
date: Wed,18 May 2022 12:09:02 GMT
server: nginx
x-correlation-id: 18e60a7cc58447e6ada26f4c51f38c80
x-request-id: fe3d15e3-3cfa-4168-b40d-77e20cd69d37
Тіло відповіді від сервера при успішному виконанні запиту буде порожнім
200 Перевищений ліміт на повторне використання запиту
Якщо серед останніх 10 відправлених транзакцій 6 - це запити на офлайн коди, то спрацює автоматичне блокування і ви отримаєте відповідь виду:
{
"status": "ERROR",
"error": "Занадто часто виконується запит отримання офлайн кодів"
}
400 Error: Bad Request
Якщо підпис касира не запущений, то ви отримаєте помилку 400 Error: Bad Request з повідомленням:
{
"message": "CheckBox Підпис неактивний, запустіть його, будь ласка"
}
Ви можете використовувати її на захищеному хмарному сервісі, або встановити локально.
400 Error: Bad Request
Якщо ви виконаєте запит на перехід в офлайн режим, акаса вже знаходиться у офлайн режимі на момент отримання запиту сервером - ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Каса вже в режимі оффлайн"
}
400 Error: Bad Request
Якщо ви спробуєте відправити офлайн транзакцію із датою меньше, ніж остання передана, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Вказана дата транзакції <YYYY-MM-DD> не може бути меншою, ніж дата створення останньої транзакції <YYYY-MM-DD>."
}
400 Error: Bad Request
Якщо ви спробуєте відправити запит на перехід у офлайн з офлайн кодом, який вже був раніше використаний на іншу транзакцію, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "[offline_mode_exception#error] Offline code 'lRvyZSJLrC4' was used before!"
}
400 Error: Bad Request
За замовченням дозволено перебувати в офлайн режимі роботи не більше 36 годин. Якщо ви перевищете цей ліміт, ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Зі вказаною міткою часу час перебування в офлайн режимі є більшим ніж дозволено (36 год.)"
}
В такому випадку роботу каси буде заблоковано, поки вона не перейде в онлайн режим роботи. Якщо ви відправляєте запити GO-ONLINE, але при перевірці стану каси вона тривалий час знаходиться в офлайн режимі - будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом.
400 Error
Якщо ви спробуєте виконати запит у закритій зміні, а його можна виконати тільки у відкритій зміні - ви отримаєте помилку 400 Error з повідомленням у тілі відповіді:
{
"message": "Зміну не відкрито"
}
400 Error
Якщо ви відправите повторний запит на відкриття зміни, а касову зміну вже відкрито (має кінцевий статус OPENED) - ви 400 Error з повідомленням:
{
"message": "Касир вже працює з даною касою"
}
400 Error
Якщо є транзакції у проміжному статусі на сервері Checkbox, то ви отримаєте помилку 400 Error з повідомленням:
{
"message": "Знайдено ще неопрацьовані транзакції у рамках поточної зміни. Зачекайте, будь ласка, завершення обробки та повторіть запит ще раз або якщо помилка повторюється тривалий час зверніться в техпідтримку"
}
Перевірте, чи запущено підпис касира в особистому кабінеті Checkbox. Якщо впродовж 10 хвилин ви продовжите отримувати помилку, а підпис касира запущено - будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом.
400 Error
Генерація фіскального Z-звіту можлива лише після отримання його фіскального номера. Якщо цього ще не відбулось, то ви отримаєте помилку 400 Error з повідомленням:
{
"message": "Звіт ще не був фіскалізований в ДПС"
}
Для того щоб успішно отримувати візуалізацію звіту, після відправлення команди закриття зміни потрібно перевіряти статус зміни, поки вона не отримає кінцевий статус CLOSED. Зазвичай це відбувається за декілька секунд. Якщо ДПС не відповідає, ми перегенеруємо онлайн закриття в офлайн режимі і самі підставимо фіскальний код, тому довго чекати не доведеться.
400 Error: Bad Request
Якщо ви спробуєте вилучити з каси більше коштів, ніж є у наявності, то отримаєте у відповідь помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>)"
}
400 Error: Bad Request
Якщо ви вкажете некоректний або неіснуючий номер замовлення, то отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Вказано невідомий ідентифікатор замовлення"
}
400 Error: Bad Request
Якщо ви вкажете для чека uuid, який вже був раніше використаний для створення іншого чека, то отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Вказаний id чеку вже існує"
}
Задаючи uuid чека при його створенні на своїй стороні, ви зможете убезпечити себе від повторної помилкової фіскалізації одного і того ж чека, оскільки повторна відправка запиту на створення чека з uuid, ідентичним до раніше використаного призведе до помилки і запит виконаний не буде.
400 Error: Bad Request
Якщо в запиті невірно вказаний uuid попереднього чеку, то ви отримаєте помилку 400 Error: Bad Request із повідомленням у тілі відповіді:
{
"message": "id попереднього чеку відрізняється від останнього збереженого чеку"
}
передача цього uuid у пейлоад чека є опціональною. Вона дозволяє контролювати ланцюжок чеків, які ви передаєте на сервер Checkbox і бути впевненим, що попередній чек вже потрапив на сервер, а ланцюжок передачі транзакцій лишився цілісним і послідовність не порушено.
400 Error: Bad Request
Якщо у блоці платежів вказати суму меншу, ніж ціна товару, то ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Сума платежів не може бути меньшою ніж сума чеку"
}
400 Error: Bad Request
Якщо у чеку поверненя в блоці платежів вказати суму, що відрізняється від загальної ціни товарів, то ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Сума платежів повинна дорівнювати сумі чеку повернення (4544.00)"
}
400 Error
Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, а вказаного коду товару в чеку продажу немає, то ви отримаєте помилку 400 Error з повідомленням у тілі відповіді:
{
"message": "Товарів з кодами: <код товару> не існує у чеку продажу."
}
400 Error
Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, і намагаєтесь повернути більшу кількість товарів ніж є в чеку продажу, то ви отримаєте помилку 400 Error з повідомленням у тілі відповіді:
{
"message": "Товарів з кодами: <код товару> більше, ніж у чеку продажу."
}
400 Error
Якщо під час створення чека повернення ви вказуєте пов'язаний uuid чека продажу, і ви вже зробили повернення цього чека, то ви отримаєте помилку 400 Error з повідомленням у тілі відповіді:
{
"message": "Товари чеку вже були повністю повернені"
}
Щоб виконати повторне повернення чека продажу, будь ласка, зв'яжіться із службою підтримки Checkbox pheyxbv для вас способом або не вказуйте uuid пов'язаного чека продажу.
400 Error: Bad Request
Якщо буде допущено помилку у формуванні вмісту тіла запиту і сервер не зможе його розпарсити, то ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "There was an error parsing the body"
}
400 Error: Bad Request
Якщо у заголовку запиту ви вкажете ключ ліцензії каси, на якій вже відкрита зміна іншим касиром, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді:
{
"message": "Каса зайнята іншим касиром"
}
401 Error: Unauthorized
Якщо ж ви вкажете неправильний ключ ліцензії каси - то у відповідь від сервера отримаєте помилку 401 Error: Unauthorized з повідомленням у тілі відповіді:
{
"message": "Невірний ключ ліцензії каси"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді:
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
У випадку, якщо PIN-код касира був вказаний невірно, ви отримаєте відповідну помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Невірний пінкод"
}
403 Error: Forbidden
У випадку, якщо облікові дані касира були вказані невірно, ви отримаєте помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Невірний логін або пароль"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Невірний ключ доступу"
}
403 Error: Forbidden
У випадку, якщо термін дії ключа касира скінчився, ви отримаєте помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Термін дії ключа закінчився <YYYY-MM-DD HH:MM:SS>."
}
Для продовження роботи вам необхідно отримати новий ключ та зареєструвати нового касира.
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error
Якщо касира було заблоковано на сторноні Checkbox (наприклад, сертифікат ключа відізвано ДПС або АЦСК, яким його було видано) - сервер поверне помилку 403 Error з повідомленням у тілі відповіді:
{
"message": "Касира заблоковано: <причина блокування>"
}
Будь ласка, зв'яжіться із службою підтримки Checkbox зручним для вас способом для вирішення питання.
403 Error: Forbidden
У випадку, якщо ви не користувались касою тривалий період - вона автоматично заморожується, щоб не нараховувалась абонплата.
{
"message": "Касу заблоковано через відсутність чеків за попередній період, необхідно сплатити за послуги користування касою для автоматичного розблокування або залишити заявку на веб-порталі https://my.checkbox.in.ua"
}
Для розморозки - необхідно сплатити рахунок за користування касами та звернутись до служби підтримки Checkbox зручним для вас способом.
403 Error
Якщо ви не оплатили послуги Checkbox завчасно, усі каси організації буде заблоковано, сервер поверне помилку 403 Error з повідомленням у тілі відповіді:
{
"message": "Для видачі чеків, будь ласка, оплатіть рахунок за користування касами."
}
Будь ласка, зверніться до служби підтримки Checkbox, що б ми оперативно розблокували роботу кас та надіслали вам актуальний рахунок.
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden з повідомленням у тілі відповіді:
{
"message": "Not authenticated"
}
405 Error
Якщо ви виконуєте запит, який потребує обов'язкової передачі X-Client-Name у заголовку, а ви його залишите пустим - сервер поверне помилку 405 Error з повідомленням у тілі відповіді:
{
"message": "Ваша версія агенту підпису застаріла та більше не підтримується, оновіть його будь ласка.\nОновлення можна отримати на веб-порталі: https://my.checkbox.in.ua/"
}
409 Error
У випадку, якщо зміну було відкрито через іншу інтеграцію, для якої встановлені обмеження (наприклад, Checkbox Каса, використання якої одночасно з прямою API інтеграцією може призвести до серйозних помилок в роботі ПРРО), API поверне помилку виду:
{
"message": "Зміну відкрито за допомогою CheckBox Kasa, виконання дії через іншу інтеграцію призведе до непередбачуваних помилок в роботі каси"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
429 Too Many Requests
За замовченням для каси стоїть rate-limit на кількість запитів за проміжок часу. Якщо ви робите більше 2-х запитів в 1 секунду, то ви отримаєте помилку 429 Too Many Requests з повідомленням:
{
"message": "Занадто часто виконуються запити, повторіть спробу через <n> секунд"
}
На цей час блокуються запити з конкретної каси (а не IP-адреси). Якщо на системному рівні ви перевищуєте заданий ліміт часу - ми вимушені блокувати IP-адреси, поки ви не виправите власну інтеграцію та зв'яжетесь із нами для зняття блокування.
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{
"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."
}
503 Error
Якщо у момент запиту на сервер Checkbox - сервер тимчасово не доступний, ви отримаєте помилку з кодом 503 та повідомленням виду:
{
"message": "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"
}
Будь ласка, спробуйте повторити свій запит через 2 хвилини.
524 Timeout Occured
Якщо у момент запиту на сервер Checkbox - сервер не відповів і з'єднання було закрито через завершення часу очікування, ви отримаєте помилку з кодом 524 та повідомленням виду:
{
"message": "524 Timeout Occured"
}
Будь ласка, спробуйте повторити свій запит через 2 хвилини.
Приклад api запитів на php від нашого клієнта.
Приклад api запитів на java від нашого клієнта.
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.