Стандартна послідовність роботи з ПРРО включає в себе наступні етапи:
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та можливо платити штраф.
При роботі у офлайн режимі ВАЖЛИВО передавати всі транзакції послідовно, так, щоб мітка дати/часу fiscal_date у запитах офлайн переходу, створення зміни, створення чеку/чеків, закриття зміни відповідали наступним вимогам:
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції. З повним переліком методів (без деталізованого опису) ви зможете переглянути за посиланнями:
Swagger
ReDoc
Також радимо ознайомитись із графічною схемою, яка показує принципи, по яким можна побудувати АПІ інтеграцію. Можливо, вона також допоможе розібратися з якимись питаннями, в якості доповнення до документації.
Існує 2 способи авторизації користувача у API Checkbox:
Для отримання токену доступу до API Checkbox потрібно у тілі POST запиту /api/v1/cashier/signin вказати логін та пароль касира.
Додатково у заголовку запиту можна вказати назву вашої інтеграції та її версію (опціонально).
У відповідь на запит ви отримаєте jwt токен авторизації, підставляючи який у заголовки запитів інших методів зможете їх використовувати від імені касира, яким була виконана авторизація.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
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"
}
400 Error: Bad Request
Якщо буде допущено помилку у формуванні вмісту тіла запиту і сервер не зможе його розпарсити, то ви отримаєте помилку 400 Error: Bad Request з повідомленням:
{
"message": "There was an error parsing the body"
}
403 Error: Forbidden
У випадку, якщо облікові дані касира були вказані невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний логін або пароль" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний логін або пароль"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Error: Unprocessable Entity
У випадку, якщо ваш запит не пройде валідацію формату, ви отримаєте 422 Error: Unprocessable Entity зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"body",
"payload",
"password"
],
"msg": "ensure this value has at least 1 characters",
"type": "value_error.any_str.min_length",
"ctx": {
"limit_value": 1
}
}
],
"message": "Validation error"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Для отримання токену доступу до API Checkbox потрібно у заголовку POST запиту /api/v1/cashier/signinPinCode вказати ключ ліцензії каси, а у тілі запиту - PIN код касира.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
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"
}
400 Error: Bad Request
Якщо буде допущено помилку у формуванні вмісту тіла запиту і сервер не зможе його розпарсити, то ви отримаєте помилку 400 Error: Bad Request з повідомленням:
{
"message": "There was an error parsing the body"
}
401 Error: Unauthorized
Якщо ж ви вкажете неправильний ключ ліцензії каси - то у відповідь від сервера отримаєте помилку 401 Error: Unauthorized з повідомленням "message": "Невірний ключ ліцензії каси"
{
"message": "Невірний ключ ліцензії каси"
}
403 Error: Forbidden
У випадку, якщо PIN код касира був вказаний невірно, ви отримаєте відповідну помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний пінкод" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний пінкод"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Error: Unprocessable Entity
У випадку, якщо ваш запит не пройде валідацію формату, ви отримаєте 422 Error: Unprocessable Entity зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"body",
"payload",
"password"
],
"msg": "ensure this value has at least 1 characters",
"type": "value_error.any_str.min_length",
"ctx": {
"limit_value": 1
}
}
],
"message": "Validation error"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
За замовчуванням варто максимум часу працювати у онлайн режимі, оскільки існує законодавче обмеження на використання офлайну не більше 36 годин підряд та суммарно не більше 186 годин на місяць. Офлайн режим може бути корисним, якщо у вас нестабільне з'єднання з мережею та виникає потреба передати правильною датою чеки, які були сформовані раніше за поточну дату.
Сервіс Checkbox у випадку, якщо сервер податкової перестає відповідати на запити, автоматично переводить касу у офлайн режим, створюючи відповідні транзакції.
Щоб визначити, в якому режимі зараз працює каса, потрібно виконати запит на отримання інформації про ПРРО
/api/v1/cash-registers/info. Параметр "offline_mode" повідомить нам про поточний статус онлайн/офлайн. Для онлайн режиму цей параметр має значення false, а для офлайн режиму - true
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-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-звіта
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Якщо каса вже знаходиться у потрібному вам режимі - можна переходити до наступного кроку і відкривати зміну. У випадку ж, якщо потрібно переключити ПРРО у онлайн або офлайн режим - скористайтеся відповідними методами, які будуть описані далі.
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-Access-Key: <ключ-ідентифікатор інтеграції>
X-License-Key: <ключ ліцензії каси>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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, щоб не створювати зайве навантаження на сервер.
400 Error: Bad Request
Якщо у заголовку запиту ви вкажете ключ ліцензії каси, на якій вже відкрита зміна іншим касиром, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді "message": "Каса зайнята іншим касиром"
{
"message": "Каса зайнята іншим касиром"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Для перевірки зв'язку з сервером податкової можна скористатися методом /api/v1/cash-registers/ping-tax-service. Відправка команди PING також ініціалізує відправку чеків у податкову з подальшим виходом каси у онлайн режим (якщо вона знаходиться у офлайні).
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
X-License-Key: <ключ ліцензії каси>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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}"
>
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Отримати з ДПС список фіскальних номерів для створення офлайн транзакцій можна за допомогою метода /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-Access-Key: <ключ-ідентифікатор інтеграції>
X-License-Key: <ключ ліцензії каси>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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" - текстовий опис помилки.
200 Перевищений ліміт на повторне використання запиту
Якщо серед останніх 10 відправлених транзакцій 6 - це запити на офлайн коди, то спрацює автоматичне блокування і ви отримаєте відповідь:
{
"status": "ERROR",
"error": "Занадто часто виконується запит отримання офлайн кодів"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Якщо попередньо ПРРО раніше вже отримало список офлайн фіскальних кодів за допомогою метода 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-Access-Key: <ключ-ідентифікатор інтеграції>
X-License-Key: <ключ ліцензії каси>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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, який буде перевищувати кількість доступних офлайн кодів, то сервер поверне у тілі відповіді стільки кодів, скільки є у наявності.
400 Error
Якщо ви спробуєте виконати запит GET OFFLINE CODES у закритій зміні, то отримаєте помилку 400 Error з повідомленням у тілі відповіді "message": "Зміну не відкрито".
{
"message": "Зміну не відкрито"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
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-Access-Key: <ключ-ідентифікатор інтеграції>
X-License-Key: <ключ ліцензії каси>
Authorization: Bearer <токен авторизації>
{
"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
400 Error: Bad Request
Якщо виникла помилка під час парсингу тіла запиту, то сервер поверне помилку 400 Error: Bad Request з повідомленням у тілі відповіді "message": "There was an error parsing the body"
{
"message": "There was an error parsing the body"
}
400 Error: Bad Request
Якщо каса вже знаходиться у офлайн режимі на момент отримання запиту сервером, то ви отримаєте помилку 400 Error: Bad Request з повідомленням у тілі відповіді "message": "Каса вже в режимі оффлайн"
{
"message": "Каса вже в режимі оффлайн"
}
400 Error: Bad Request
Якщо ви спробуєте відправити запит на перехід у офлайн з офлайн кодом, який вже був раніше використаний на іншу транзакцію, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді "message": "[offline_mode_exception#error] Offline code '<офлайн код>' was used before!"
{
"message": "[offline_mode_exception#error] Offline code 'lRvyZSJLrC4' was used before!"
}
400 Error: Bad Request
Якщо у заголовку запиту ви вкажете ключ ліцензії каси, на якій вже відкрита зміна іншим касиром, то отримаєте від сервера помилку 400 Error: Bad Request з повідомленням у тілі відповіді "message": "Каса зайнята іншим касиром"
{
"message": "Каса зайнята іншим касиром"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Відкрити зміну можна за допомогою запиту /api/v1/shifts. Відкрити зміну можна у онлайн або офлайн режимі. Для відкриття зміни у офлайн режимі потрібно спочатку виконати команду GO OFFLINE, яка буде описана далі, а після цього в тілі запиту на створення зміни потрібно вказати вільний фіскальний код та фіскальну дату. Механізм отримання таких фіскальних кодів для створення офлайн транзакцій буде описаний в методі ASK OFFLINE CODES. Також можна задати зміні унікальний ідентифікатор у форматі UUID. Якщо у тілі запиту не буде цього ідентифікатора, то після передачі запиту на сервер Checkbox зміні буде автоматично присвоєно UUID. Для створення зміни у онлайн режимі не потрібно вказувати фіскальний код та фіскальну дату. Дата автоматично буде вказана поточна.
За замовчуванням варто працювати максимум часу у онлайн режимі, оскільки існує обмеження на використання офлайну - 36 годин підряд та не більше 168 годин на місяць. Слідкувати за дотриманням цієї норми потрібно клієнту, який використовує API.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
{
"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" - блок з інформацією про першу транзакцію обраної зміни
400 Error: Bad Request
Якщо підпис касира не запущений, то ви отримаєте помилку 400 Error: Bad Request з повідомленням:
{
"message": "CheckBox Підпис неактивний, запустіть його, будь ласка"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
GET метод /api/v1/cashier/shift дозволяє отримати розгорнуту інформацію про поточну активну зміну касира, яким був виконаний вхід на портал.
Якщо у касира є активна поточна зміна, то у відповіді від сервера ви отримаєте інформацію про цю зміну.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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" - блок з інформацією про першу транзакцію обраної зміни
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Метод /api/v1/receipts/service дозволяє створити чек службового внесення або вилучення готівки. Для коректного створення такого чеку потрібно обов'язково передати у тілі запиту параметри type (має бути CASH за замовчуванням), value та label (має бути "Готівка" за замовчуванням).
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
{
"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
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": "Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>)"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Чек можна створити як у офлайн, так і у онлайн режимі. Метод /api/v1/receipts/sell призначений для створення чека як у онлайн, так і у офлайн режимі (але без можливості явно вказати офлайн фіскальний код або офлайн фіскальну дату. Якщо каса у офлайні, то сервер автоматично підставить поточну дату та вільний офлайн код). Метод /api/v1/receipts/sell-offline призначений для створення чека у офлайні і дозволяє явно вказати як фіскальну дату, так і фіскальний код.
Мінімальний набір даних для створення чека продажу включає в себе код товару, назву товару, ціну, кількість, тип оплати та суму оплати. Але взагалі чек може містити багато додаткових параметрів, які будуть описані у прикладі.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
{
"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 для онлайн чеку.
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": "Вказано невідомий ідентифікатор замовлення"
}
400 Error: Bad Request
Якщо ви вкажете для чека id, який вже був раніше використаний для створення іншого чека, то отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Вказаний id чеку вже існує"
}
Задаючи id чека при його створенні на своїй стороні ви зможете убезпечити себе від повторної помилкової фіскалізації одного і того ж чека, оскільки повторна відправка запиту на створення чека з id, ідентичним до раніше використаного призведе до помилки і запит виконаний не буде.
400 Error: Bad Request
Якщо в запиті невірно вказаний id попереднього чеку, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "id попереднього чеку відрізняється від останнього збереженого чеку"
}
передача цього id у пейлоад чека є опціональною. Вона дозволяє контролювати ланцюжок чеків, які ви передаєте у Checkbox і бути впевненим, що попередній чек вже потрапив на сервер, а ланцюжок передачі транзакцій лишився цілісним і послідовність не порушено.
400 Error: Bad Request
Якщо у блоці платежів вказати суму меншу, ніж ціна товару, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Сума платежів не може бути меньшою ніж сума чеку"
}
400 Error: Bad Request
Якщо у чеку поверненя в блоці платежів вказати суму, що відрізняється від загальної ціни товарів, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Сума платежів повинна дорівнювати сумі чеку повернення (4544.00)"
}
400 Error: Bad Request
Якщо ви спробуєте вилучити з каси більше готівкових коштів, ніж є у наявності (при створенні чека повернення), то отримаєте у відповідь помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>)"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Перед створенням офлайн чеку касу потрібно перевести у офлайн режим, інакше ви отримаєте від 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: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
{
"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 для онлайн чеку.
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": "Вказано невідомий ідентифікатор замовлення"
}
400 Error: Bad Request
Якщо ви вкажете для чека id, який вже був раніше використаний для створення іншого чека, то отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Вказаний id чеку вже існує"
}
Задаючи id чека при його створенні на своїй стороні ви зможете убезпечити себе від повторної помилкової фіскалізації одного і того ж чека, оскільки повторна відправка запиту на створення чека з id, ідентичним до раніше використаного призведе до помилки і запит виконаний не буде.
400 Error: Bad Request
Якщо в запиті невірно вказаний id попереднього чеку, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "id попереднього чеку відрізняється від останнього збереженого чеку"
}
передача цього id у пейлоад чека є опціональною. Вона дозволяє контролювати ланцюжок чеків, які ви передаєте у Checkbox і бути впевненим, що попередній чек вже потрапив на сервер, а ланцюжок передачі транзакцій лишився цілісним і послідовність не порушено.
400 Error: Bad Request
Якщо у блоці платежів вказати суму меншу, ніж ціна товару, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Сума платежів не може бути меньшою ніж сума чеку"
}
400 Error: Bad Request
Якщо у чеку поверненя в блоці платежів вказати суму, що відрізняється від загальної ціни товарів, то ви отримаєте помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Сума платежів повинна дорівнювати сумі чеку повернення (4544.00)"
}
400 Error: Bad Request
Якщо ви спробуєте вилучити з каси більше готівкових коштів, ніж є у наявності (при створенні чека повернення), то отримаєте у відповідь помилку 400 Error: Bad Request і повідомлення виду:
{
"message": "Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>)"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
X та Z звіти дуже схожі за своєю структурою, проте між ними є принципова різниця - створення Z - звіту означає закриття поточної касової зміни. X - звіт, в свою чергу, зміну не закриває.
Для створення X-звіту потрібно використовувати метод /api/v1/reports Create X Report
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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" - блок з інформацією про платежі в рамках поточної зміни
400 Error: Bad Request
Спроба створити X-звіт у закритій зміні призведе до помилки 400 Error: Bad Request з повідомленням у тілі відповіді "message": "Зміну не відкрито".
{
"message": "Зміну не відкрито"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Для створення Z-звіту потрібно використовувати метод /api/v1/shifts/close Close Shift
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Content-Type: application/json
Authorization: Bearer <токен авторизації>
Якщо тіло запиту залишити порожнім, то всі дані по 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" - блок даних з інформацією про касира
400 Error: Bad Request
Якщо підпис касира не запущений, то ви отримаєте помилку 400 Error: Bad Request з повідомленням:
{
"message": "CheckBox Підпис неактивний, запустіть його, будь ласка"
}
400 Error: Bad Request
Спроба закрити зміну, якщо вона вже закрита призведе до помилки 400 Error: Bad Request з повідомленням у тілі відповіді "message": "Зміну не відкрито".
{
"message": "Зміну не відкрито"
}
401 Error: Unauthorized
Якщо касир не авторизований (його токен доступу було скасовано), сервер поверне помилку 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу".
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
Якщо касир деактивований користувачем, сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Доступ заборонено, оскільки касира деактивовано"
{
"message": "Доступ заборонено, оскільки касира деактивовано"
}
403 Error: Forbidden
Якщо касир активний, але не було виконано авторизацію (не переданий токен авторизації у заголовку запиту), сервер поверне помилку 403 Error: Forbidden та повідомлення в тілі відповіді "message": "Not authenticated"
{
"message": "Not authenticated"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
409 Error
У випадку, якщо зміну було відкрито через іншу інтеграцію, для якої встановлені обмеження (наприклад, Чекбокс Каса, використання якої одночасно з прямою API інтеграцією може призвести до серйозних помилок в роботі ПРРО), API поверне помилку виду:
{
"message": "Зміну відкрито за допомогою CheckBox Kasa, виконання дії через іншу інтеграцію призведе до непередбачуваних помилок в роботі каси"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Якщо вам потрібно завершити сесію користувача (касира) з поточним токеном доступу та скасувати токен - використайте метод POST /api/v1/cashier/signout
У випадку успішного виконання запиту ви отримаєте код 205 Successful Response.
accept: application/json
X-Client-Name: <назва інтеграції(опціонально)>
X-Client-Version: <версія інтеграції(опціонально)>
X-Access-Key: <ключ-ідентифікатор інтеграції>
Authorization: Bearer <токен авторизації>
Тіло запиту у даному випадку має бути порожнім
Приклад
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
Тіло відповіді від сервера при успішному виконанні запиту буде порожнім
401 Error: Unauthorized
Якщо токен доступу вже був відізваний, або він некоректний - ви отримаєте у відповіді 401 Error: Unauthorized з повідомленням у тілі відповіді "message": "Невірний токен доступу"
{
"message": "Невірний токен доступу"
}
403 Error: Forbidden
У випадку, якщо ключ-ідентифікатор інтеграції було вказано невірно, ви отримаєте помилку 403 Error: Forbidden і повідомлення у полі "message": "Невірний ключ доступу" в тілі відповіді від сервера Checkbox.
{
"message": "Невірний ключ доступу"
}
422 Validation Error
Якщо запит сформовано невірно, то ви отримаєте помилку 422 Validation Error зі змістом наступного вигляду, де буде вказано приблизне розташування та опис помилки:
{
"detail": [
{
"loc": [
"<місцезнаходження помилки>"
],
"msg": "<опис помилки>",
"type": "<тип помилки>"
}
],
"message": "<короткий опис помилки>"
}
503 Error
Якщо у момент запиту на сервері проводяться технічні роботи, ви отримаєте помилку з кодом 503 та повідомленням виду:
{"message":"Maintenance work till 3:30 GMT+3. Sorry for the inconvenience."}
Приклад api запитів на php від нашого клієнта.