Щоб отримати UUID каси, скористайтесь методом /api/v1/cash-registers.
Щоб визначити, в якому режимі зараз працює каса, потрібно виконати запит на отримання інформації про ПРРО /api/v1/cash-registers/{cash_register_id}. Параметр "offline_mode" повідомить нам про поточний статус онлайн/офлайн режиму. Для онлайн режиму цей параметр має значення false, а для офлайн режиму - true.
Максимальний режим роботи в офлайн режимі — 36 годин.
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/c13876dd-e51e-433f-a61c-f2c426311111' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Authorization: Bearer token'
{
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST511111",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-11-10T22:55:07+00:00",
"number": "1",
"shift": null,
"offline_mode": true,
"stay_offline": true,
"branch": null,
"address": "УКРАЇНА, М.КИЇВ ГОЛОСІЇВСЬКИЙ Р-Н, Тестова, 41а",
"type": 0
}
"id" - унікальний ідентифікатор каси у форматі UUID
"fiscal_number" - фіскальний номер каси
"active" - true/false, ідентифікатор активної каси. Для кас, деактиованих в системі checkbox цей параметр буде false
"created_at" - дата створення каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останнього оновлення (зміни) облікових даних каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"number" - порядковий номер каси
"shift" - блок даних з інформацією про зміну. Якщо касову зміну не відкрито, відповідь буде null
"offline_mode" - true/false, ідентифікатор офлайн режиму. false означає, що каса зараз у онлайні, а true означає, що каса працює у офлайн режимі.
"stay_offline" - якщо даний параметр true, то це означає, що перехід у офлайн був виконаний на стороні клієнта (шляхом відправки запиту /api/v1/cash-registers/go-offline, а не завдяки автоматичному офлайн переходу, який відбувається, коли не відповідає сервер ДПС)
"branch" - блок даних з інформацією про торгову точку. Якщо це тестова касса, значення завжди буде null
"address" - адреса торгової точки
Для перевірки зв'язку з сервером Податкової Служби можна скористатися методом /api/v1/cash-registers/ping-tax-service. Відправка команди PING також ініціалізує відправку чеків у податкову з подальшим виходом каси у онлайн режим (якщо вона знаходиться у офлайні).
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/ping-tax-service' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -d ''
{
"status": "DONE",
"error": null
}
Якщо ви отримуєте помилку виду:
_InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.DEADLINE_EXCEEDED
details = "Deadline Exceeded"
debug_error_string = "{"created":"@1651529548.259915513","description":"Deadline Exceeded","file":"src/core/ext/filters/deadline/deadline_filter.cc","file_line":81,"grpc_status":4}"
>
Це свідчить про недоступність серерів Податкової Служби.
"status" - статус транзакції відправки запиту. Може мати статуси CREATED/PENDING/SIGNED/DELIVERED/DONE або ERROR
"error" - текстовий опис помилки, яку повернає сервер ДПС. Якщо помилки немає, цей параметр прийме значення null
У полі "error" може повертатись і помилка виду:
{
"status": "DONE",
"error": "ERROR_BAD_HASH_PREV store bdfdc222d0a015519e269292d58b5690a7f02d9b65a0eae79b6241b7a9ea153f chk ad10bda2a97f4674dbb052a0ff0e401175d8425bd85f9bf9247ddba1ff73421e"
}
Вона ніяк не вплине на роботу безпосередньо (команда PING призначена для перевірки наявності зв'язку з ДПС, а не для передачі і збереження транзакції зміни/чека/офлайн-онлайн переходу, тому не важливо, пройде чи ні PING перевірку на відповідність хешу попереднього чеку. Будь-яка відповідь від ДПС означатиме, що зв'язок з податковою є).
Ситуація з помилкою вище виникає у випадку, коли з сервера Checkbox відправляється PING, але він до сервера ДПС потрапляє раніше, ніж масив чеків, створених у офлайн режимі, які ще не потрапили до ДПС.
Якщо сервер ДПС у даний момент недоступний, ви отримаєте помилку виду:
_InactiveRpcError: <_InactiveRpcError of RPC that terminated with:
status = StatusCode.DEADLINE_EXCEEDED
details = "Deadline Exceeded"
debug_error_string = "{"created":"@1651529548.259915513","description":"Deadline Exceeded","file":"src/core/ext/filters/deadline/deadline_filter.cc","file_line":81,"grpc_status":4}"
>
Отримати з Податкової Служби список фіскальних кодів для створення офлайн транзакцій можна за допомогою метода /api/v1/cash-registers/ask-offline-codes тільки коли каса знаходиться у ОНЛАЙН режимі. Після виконання запиту ці номери зберігаються на сервері Checkbox і стають доступними для отримання методом /api/v1/cash-registers/get-offline-codes.
Після виконання запиту на офлайн коди відправляти будь-які офлайн транзакції (зміни, чеки, офлайн переходи) можна тільки з датою/часом fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу виконання запиту /api/v1/cash-registers/ask-offline-codes.
Відправити запит на офлайн фіскальні коди можна синхронно або асинхронно, що регулюється відповідним параметром у запиті (sync). Кількість кодів, яку користувач бажає отримати, задається у параметрі count запиту.
Максимальна кількість кодів, яку повертає ДПС = 5000 кодів!
Асинхронний режим одразу поверне статус "status": "OK" (або "ERROR", якщо на етапі формування запиту відбулася помилка), незалежно від того, чи запит успішно досяг сервера податкової. У асинхронному режимі "ОК" не означає успішне виконання запиту, а тільки його успішну відправку. Синхронний режим обробляє запит повністю і передає остаточний статус "DONE", якщо запит успішно досяг сервера ДПС, або "TIMEOUT", якщо сервер ДПС не відповів у визначений строк.
Важливо - номер перестає повертатися сервером ДПС (вважається "використаним") лише після відправки до ДПС транзакції з цим номером. До того часу ДПС повертає фіскальний номер при кожному виклику.
Наприклад: зробивши до ДПС перший запит на 100 номерів, отримаємо 100 нових вільних фіскальних номерів для відповідного ПРРО. Але зробивши після цього запит ще на 200 номерів, отримаємо 100 тих самих номерів та ще 100 наступних за ними.
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/ask-offline-codes?count=2000&sync=true' \ -H 'accept: */*' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token'
{
"status": "OK"
}
"status" - статус запиту. Для асинхронного режиму завжди буде "ОК" або "ERROR", для синхронного - приймає значення "DONE" у випадку успішного запиту, "TIMEOUT", якщо перевищено ліміт очікування відповіді від сервера ДПС або "ERROR", якщо виникла помилка.
Врахуйте, що у асинхронному режимі "ОК" не означає успішне виконання запиту, а тільки його успішну відправку.
"error" - текстовий опис помилки.
Якщо попередньо ПРРО раніше вже отримало список офлайн фіскальних кодів за допомогою метода /api/v1/cash-registers/ask-offline-codes, то за допомогою метода /api/v1/cash-registers/get-offline-codes ви зможете завантажити необхідну кількість невикористаних на даний момент фіскальних номерів з сервера Checkbox, навіть якщо сервер ДПС недоступний.
Будь-який фіскальний код можна використати лише 1 раз на створення офлайн транзакції відкриття/закриття зміни, офлайн переходу або чеку. Врахуйте, що на стороні серверу Checkbox реалізовано функцію автоматичного переходу у офлайн режим у випадку тайм-ауту відповіді від ДПС. Тобто, сервер автоматично створить транзакцію офлайн переходу та почне створювати чеки у офлайн режимі, підставляючи у них доступні офлайн коди, навіть якщо ви зі свого боку відправляєте чеки як онлайнові. Перед відправкою до Checkbox офлайн чеків варто синхронізувати пул доступних для використання фіскальних кодів, інакше на певних чеках може виникнути помилка виду "Offline code '<офлайн код>' was used before!".
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/cash-registers/get-offline-codes?count=3' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token'
[
{
"fiscal_code": "TEST-iA5fmb",
"serial_id": 1,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586071+00:00"
},
{
"fiscal_code": "TEST-aQ-V-c",
"serial_id": 2,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586073+00:00"
},
{
"fiscal_code": "TEST-WzSbIz",
"serial_id": 3,
"cash_register_id": "c13876dd-e51e-433f-a61c-f2c426311111",
"created_at": "2023-11-08T12:25:21.586073+00:00"
}
]
Для кожного фіскального коду метод поверне масив даних, який включає в себе:
"cash_register_id" - id обраної каси у форматі UUID
"serial_id" - порядковий номер фіскального коду
"created_at" - дата створення фіскального коду
"fiscal_code" - фіскальний код
Якщо на сервері немає фіскальних кодів, то масив буде порожнім. У випадку, якщо ви відправите у запиті параметр count, який буде перевищувати кількість доступних офлайн кодів, то сервер поверне у тілі відповіді стільки кодів, скільки є у наявності.
POST метод /api/v1/cash-registers/go-online дозволяє відправити команду на початок переходу у онлайн режим.
Cама по собі відправка цієї команди не означає, що каса буде одразу переведена у онлайн режим.
Якщо в черзі на відправку у ДПС багато офлайн чеків, то одного запиту може бути недостатньо. Після відправки /api/v1/cash-registers/go-online варто через хвилину перевірити статус каси запитом /api/v1/cash-registers/{cash_register_id} (параметр "offline_mode" має повернути поточний статус). У онлайні він буде false, а у офлайні true. Якщо каса не перейшла у онлайн - варто відправити /api/v1/cash-registers/go-online ще раз та знову перевірити через хвилину статус каси, повторюючи дії в циклі, поки каса не вийде у онлайн-режим.
Наявний rate-limit дозволяє передавати не більше 1 запиту раз на 2 хвилини. Він діє індивідуально на кожну окрему касу, а не на IP-адресу.
При систематичному порушенні ліміту ми зв'яжемось за контактами, вказаними в налаштуваннях особистого кабінету організації для вирішення питання порушення наявних лімітів.
Якщо ви відправили команду /api/v1/cash-registers/go-online вже більше разів, ніж у вас створено невідправлених у ДПС офлайн транзакцій, або вже тривалий час не можете перейти у онлайн, незважаючи на постійні спроби - перевірте наявність зв'язку з ДПС методом /api/v1/cash-registers/ping-tax-service. Якщо з податковою є зв'язок, а перехід у онлайн не відбувається - зверніться у технічну підтримку Checkbox за консультацією.
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/go-online' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -d ''
{
"status": "ok"
}
"status" - статус отримання команди на ініціалізацію переходу у онлайн режим. Даний статус завжди повертає значення "ok" у випадку успішного виконання запиту, проте не означає, що каса одразу ж перейде у онлайн. Саме тому радимо через хвилину перевірити статус каси запитом /api/v1/cash-registers/{cash_register_id}. Після того, як каса перейде у онлайн, потрібно зупинити повторну відправку /api/v1/cash-registers/go-online, щоб не створювати зайве навантаження на сервер Податкової Служби.
POST метод /api/v1/cash-registers/go-offline дозволяє відправити команду на перехід ПРРО у офлайн режим. Для переходу у офлайн достатньо виконати 1 успішний запит go-offline. Поточний статус онлайн/офлайн ПРРО можна визначити за допомогою запиту /api/v1/cash-registers/{cash_register_id}. Параметр "offline_mode" покаже поточний статус онлайн/офлайн (у онлайні він буде false, а у офлайні true).
У тілі запиту є можливість вказати часову мітку офлайн переходу (такою датою/часом буде зареєстрований у ДПС перехід у офлайн).
Перейти у офлайн можливо з міткою дати/часу fiscal_date БІЛЬШОЮ АБО РІВНОЮ даті/часу останньої успішно доставленої у ДПС транзакції (чеку/відкриття/закриття зміни/переходу у онлайн).
Передача невірної дати/часу призведе до застрягання каси у офлайн режимі та ПОЛОМКИ КАСИ.
У параметрі "fiscal_code" потрібно передати фіскальний код, який раніше ще не був використаний.
Якщо в тілі запиту на перехід у офлайн не передати параметр "fiscal_code", то сервер зі свого боку автоматично підставить один з вільних фіскальних кодів і виконає переведення ПРРО у офлайн режим. Врахуйте, що якщо ви спробуєте потім відправити чек з офлайн кодом, який був автоматично підставлений у офлайн перехід, то виникне помилка, оскільки кожен код можна використати лише один раз. Також, якщо у тілі запиту не вказувати "go_offline_date", то офлайн перехід відбудеться з поточною міткою дати/часу. Тобто, якщо вас влаштовує, що офлайн код буде автоматично підставлено сервером, а дата/час переходу будуть поточні, то можете лишити тіло запиту на перехід у офлайн взагалі порожнім.
Первинне отримання масиву фіскальних кодів відбувається з використанням методу /api/v1/cash-registers/ask-offline-codes. Після успішного виконання /api/v1/cash-registers/ask-offline-codes отримати список ще не використаних на сервері фіскальних кодів можна за допомогою метода /api/v1/cash-registers/get-offline-codes. Саме ним бажано користуватись, аж допоки запас офлайн кодів не зменшиться до кількості, яку ви встановите для себе критичною (наприклад, до 500). Метод /api/v1/cash-registers/get-offline-codes дозволяє набагато швидше отримати вільні, вже отримані раніше фіскальні коди для обраного ПРРО, не чекаючи відповідь від сервера податкової.
accept: application/json
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
Authorization: <токен авторизації>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Content-Type: application/json
{
"go_offline_date": "<фіскальна дата у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>",
"fiscal_code": "<фіскальний код>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/cash-registers/go-offline' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'X-License-Key: test3a544a54373a9cb3f2711111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "go_offline_date": "2023-11-29T06:14:20+0200", "fiscal_code": "TEST-aQ-V-c"}'
{
"status": "ok",
"id": "4722e600-905f-4a89-9d71-801698125664"
}
"status" - статус виконання запиту. Успішний запит завжди матиме статус ok
"id" - унікальний ідентифікатор транзакції у форматі UUID