¶ Опис порядку роботи з локальним API CheckBox Kasa
Після встановлення та запуску програми Checkbox Kasa - вона підіймає свій локальний веб-сервер, з яким можна спілкуватись за допомогою REST API.
В даній статті описано мінімальний необхідний перелік методів, яких буде достатньо для створення інтеграції. З повним переліком методів (без деталізованого опису) ви зможете ознайомитись за посиланням Swagger.
Опис Request Headers, які зустрічаються найчастіше у запитах:
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
Content-Type: application/json
accept: application/json
¶ Послідовність роботи
- Відкриття зміни
- Створення службового чеку внесення готівки (за необхідності)
- Створення чеку/чеків продажу/повернення
- Створення чеку видачі готівкових коштів держателю ЕПЗ
- Створення службового чеку винесення готівки (за необхідності)
- Перевірка балансу зміни за допомогою X-Звіту (за необхідності).
- Закриття зміни (створення Z - звіту)
- Перевірка статусу каси (онлайн/офлайн)
Ніколи не використовуйте бойову касу/касира для цілей тестування, інакше потім вам доведеться, як мінімум, пояснювати податковій, що ви передали некоректні дані та можливо платити штраф.
¶ Зміна
¶ Відкриття касової зміни
Відкрити зміну можна за допомогою запиту /api/v1/shift/open. Відкрити зміну можна у онлайн або офлайн режимі. Для відкриття касової зміни не потрібно вказувати фіскальний код або фіскальну дату (вона буде автоматично вказана поточною з ПК).
Касова зміна має бути закрита в той день, коли вона відкрита і не може тривати більше 24х годин.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/shift/open' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -d ''
¶ Response body
{
"status": <true - у випадку успішного відкриття зміни, false - якщо зміну вже відкрито або сталася помилка при відкритті>
}
¶
¶ Закриття зміни (створення Z - звіту)
Z-звіт – це фіскальний підсумковий документ, який повинен сформуватись в той же день коли зміна була відкрита та зробити до 23:59. Формування Z-звіту означає завершення касової зміни і здачу виручки. Виручку до каси підприємства здають тільки юридичні особи. Якщо зміна не була відкрита, то в такому випадку немає необхідності формувати Z-звіт кожен день
Під час закриття касової зміни, Z - звіт автоматично створюється та друкується.
Для закриття зміни необхідно виконати команду /api/v1/shift/close.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
¶ Request body
Тіло запиту у даному випадку має бути порожнім
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/shift/close' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -d ''
¶ Response body
{
"id": "<yнікальний UUID v4 z-звіту>",
"status": <true/false - статус виконання>,
"fiscal_code": "<фіскальний код>",
"fiscal_date": "фіскальна дата у форматі ISO 8601",
"is_online": true,
"report": {
"id": "<yнікальний UUID v4 z-звіту>",
"serial": 25,
"taxes": [
{
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": 0,
"sell_sum": 20000,
"return_sum": 0,
"sales_turnover": 120000,
"returns_turnover": 0,
"setup_date": "2023-09-27T07:57:32.979471",
"no_vat": false
},
],
"payments": [
{
"type": "CASH",
"code": null,
"label": "Готівка",
"sell_sum": 156000,
"return_sum": 0,
"service_in": 100,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
}
],
"sell_receipts_count": 13,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 0,
"last_receipt_id": "afcb657e-af26-4e1a-8f36-c682a11becaf",
"initial": 0,
"balance": 156200,
"sales_round_up": 0,
"sales_round_down": 0,
"returns_round_up": 0,
"returns_round_down": 0,
"discounts_sum": 0,
"extra_charge_sum": 0
}
}
"id" - унікальний ідентифікатор Z-звіту у форматі UUID,
"status" - статус виконання команди,
"fiscal_code" - фіскальний номер транзакції,
"fiscal_date" - фіскальна дата, з якою транзакцію буде зареєстровано у ДПС,
"is_online" - true/false, режим створення транзакції,
"report" - блок даних з інформацією
"id" - унікальний ідентифікатор Z-звіту у форматі UUID,
"serial" - порядковий номер зміни,
"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
"payments" - блок з інформацією про платежі в рамках поточної зміни:
- "type" - "CASH",
- "code" - код способу оплати,
- "label" - текстовий опис, який має містити назву форми оплати. Наприклад, Готівка або Картка,
- "sell_sum" - сума продажів з поточною форомою оплати у копійках,
- "return_sum" - сума повернень з поточною форомою оплати у копійках,
- "service_in" - сума службових внесень з поточною форомою оплати у копійках,
- "service_out" - сума службових винесень з поточною форомою оплати у копійках,
- "cash_withdrawal" - сума операцій з видачі готівкових коштів у копійках,
- "cash_withdrawal_commission" - сума комісійних нарахувань по операціям з видачі готівкових коштів у копійках.
"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" - сума копійок чеків повернення, заокруглених в меньшу сторону,
"discounts_sum" - сума копійок чеків повернення, заокруглених в меньшу сторону,
"extra_charge_sum" - сума надбавок в поточній зміні.
¶
¶ Перевірка статусу каси
Повертається відповідь із інформацією про статус каси
¶ Request headers
accept: application/json
¶ Request example
ℹ️ Тіло запиту у даному випадку має бути порожнім
curl -X 'GET' \ 'http://127.0.0.1:9200/api/v1/kasa/status \ -H 'accept: application/json'
Повертається у відповідь масив з інформацією про статус каси
¶ Response body
{
"online_status": true,
"approximate_dps_online_status": true,
"hours_in_offline": 0,
"first_pending_transaction": "2025-03-29T11:34:45.298Z",
"last_go_offline_at": "2025-03-29T11:34:45.298Z",
"hours_since_last_go_offline": 0,
"pending_transactions": 0,
"offline_codes": 0,
"offline_codes_percent": 0
}
"online_status": - каса в онлайні true-так,false-ні,
"approximate_dps_online_status": - звязок з дпс true-так,false-ні,
"hours_in_offline": - кількість годин в офлайні,
"first_pending_transaction": - "дата першої офлайн транзакції",
"last_go_offline_at": - "дата переходу в офлайн",
"hours_since_last_go_offline": - кількість годин з останнього запиту на перехід в офлайн,
"pending_transactions": - кількість не відправлених транзакцій,
"offline_codes": - кількість офлайн кодів,
"offline_codes_percent": - кількість офлайн кодів в %
¶ Чеки
¶ Створення службового чеку внесення або винесення готівки
Внесення і видача готівки – службові (нефіскальні) операції, коли ви вносите розмінні гроші в касу або інкасуєте готівку.
Метод /api/v1/receipt/service дозволяє створити чек службового внесення або вилучення готівки. Для коректного створення такого чеку потрібно обов'язково передати у тілі запиту параметри type (має бути CASH за замовчуванням), value та label (має бути "Готівка" за замовчуванням).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
Content-Type: application/json
¶ Request body
{
"payment": {
"type": "CASH", <Дозволено тільки тип `CASH`>
"value": 100, <сума у копійках, для створення чеку службового вилучення перед сумою має бути - >
"label": "Готівка" <Назва типу оплати>
},
"print": true <true/false команда на друк службовоого чека>
}
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/receipt/service' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Content-Type: application/json' \ -d '{ "payment": { "type": "CASH", "value": 10000, "label": "Готівка" }, "print_simple_text": false, "print": true}'
¶ Response body
{
"type": "SERVICE_IN",
"updated_at": "2023-10-01T14:17:17.404780",
"transaction_id": 4,
"shift_id": 2,
"external_id": "4f6d35f0-a533-49e8-95fc-22f90c7564ec",
"custom_id": null,
"status": "DONE",
"cashier_name": null,
"departament": null,
"header": null,
"footer": null,
"barcode": null,
"tax_codes": null,
"files" - : [
{
"mime": "image/png",
"path": "C:\\checkbox.kasa.manager\\profiles\\test\\files_printer\\2023-10-01\\14-17-17-107514_receipt.png"
}
],
"signature": "gAAAAABlGVU8GrMr6c_eOQT21EKNq48SIU40c65ORSMJRqQ_4vg2TyP4Iwl-z110dMPqib72SiCB8EqGcBJ5z63xuhzctVPupY_ibZZPc5A8yvpberYmv05Po3B22h6Uwl7omLea19SSMtYsi-8Hr395R0zE4xUlqePE3tHTcb5kYHgZBHTaOI6rXm4NcItW15MbkNY2piIVXAAYjNEMqauKGBCcGpNC2Bp881JcCu1XZSE-zux-bF0t0n-sbW0YxeCAHI2bBDGl4f3yXIf0NZGQMxZUXBpJ6w==",
"fiscal_code": null,
"created_at": "2023-10-01T14:17:17.107514",
"id": 1
}
"type" - SERVICE_IN для чека внесення та SERVICE_OUT для чека винесення готівки.
"updated_at" - Час запису транзакції в локальну БД.
"transaction_id" - Порядковий номер транзакції в локальній БД.
"shift_id" - Номер зміни, у якій було виконано транзакцію.
"external_id" - UUID транзакції.
"custom_id" - Кастомний UUID транзакції.
"status" - Статус транзакції.
"cashier_name" - Назва касира.
"departament" - Назва департаменту.
"header" - Хедер чека.
"footer" - Футер чека.
"barcode" - Штрихкод чека.
"tax_codes" - Код податку.
"files" - Масив даних, тип та шлях збереженого файлу чека.
"signature" - Шифрований підпис транзакції.
"fiscal_code" - Фіскальний номер чека (для службових чеків внесення/винесення готівки завжди null).
"created_at" - Час створення транзакції.
"id" - Порядковий номер чека в локальній БД.
¶
¶ Створення чеку продажу або повернення
Метод /api/v1/receipt/sell призначений для створення чека як у онлайн, так і у офлайн режимі (але без можливості явно вказати офлайн фіскальний код або офлайн фіскальну дату - каса автоматично підставляє поточну дату та час).
Мінімальний набір даних для створення чека продажу включає в себе UUID чека, код товару, назву товару, ціну, кількість, тип оплати та суму оплати. Але взагалі чек може містити багато додаткових параметрів, які будуть описані у прикладі.
Відмінність чеку повернення від чека продажу полягає в тому, що при поверненні товару при його додаванні в чек потрібно вказувати параметр "is return": true.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
Content-Type: application/json
¶ Request body
{
"custom_id": "<генерація та передача UUID чека на стороні інтеграції є обов'язковою>",
"departament": "<Назва відділу>",
"cashier_name": "<Ім'я касира>",
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"discounts": [
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"name": "<назва знижки або надбавки>",
"tax_codes": [<коди податкових ставок через кому, що застосовуються для товару (якщо їх >1). Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>]
}
],
"goods": [
{
"code": "<Код товару>",
"name": "<Назва товару>",
"price": <ціна у копійках>,
"quantity": <кількість у тисячах, 1 шт = 1000>,
"taxes": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"discounts": [
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"name": "<назва знижки або надбавки>",
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>]
}
],
"uktzed": "<код УКТЗЕД>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"barcode": "<Штрих-код товару>",
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"is_winnings_payout": <флаг true/false, що визначає, чи це виплата виграшу>,
}
],
"payments": [
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"value": <сума оплати у копійках>,
"label": "<текстова назва форми оплати>",
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
}
],
"delivery": {
"email": "<e-mail клієнта для відправки копії чека>",
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"print": <true/false, команда на друк чека>,
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"round": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"abs_vizualization_values": <true/false, абсолютне відображення суми чека в графічному або друкованому вигляді>
}
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/receipt/sell' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Content-Type: application/json' \ -d '{ "custom_id": "3a252dc3-042f-4058-8172-79c0db96e8c0", "goods": [ { "code": "Good1", "name": "Колбаса Краківська", "price": 12000, "quantity": 1000, "taxes": [ 5 ] } ], "payments": [ { "type": "CASH", "value": 12000, "label": "Готівка" } ], "print": true, "remove_rest": false, "technical_return": false, "round": false}'
¶ Response body
{
"id": "db2d95a6-ab56-4ad2-848c-087bb0c11111",
"fiscal_code": "TEST-T11111",
"fiscal_date": "2023-10-24T13:55:48.697782+03:00",
"is_online": true,
"is_sell": true,
"total_payment": 12000,
"total_sum": 12000,
"total_rest": 0,
"round_sum": 0,
"goods": [
{
"good": {
"code": "Good1",
"name": "Колбаса Краківська",
"header": null,
"footer": null,
"uktzed": null,
"price": 12000,
"excise_barcodes": null,
"barcode": null,
"tax": [
5
]
},
"sum": 12000,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"value": 2000,
"extra_value": 0,
"included": true,
"no_vat": false,
"returns_turnover": 0,
"sales_turnover": 12000,
"created_at": "2023-09-27T07:57:32.979471"
}
],
"discounts": []
}
],
"payments": [
{
"type": "CASH",
"value": 12000,
"label": "Готівка"
}
],
"type": "SELL",
"discounts": [],
"taxes": [
{
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": null,
"value": 2000,
"extra_value": 0,
"included": true,
"no_vat": false,
"returns_turnover": 0,
"sales_turnover": 12000,
"created_at": "2023-09-27T07:57:32.979471",
"id": "b4a68b3f-2071-4c32-985b-861c644e8266"
}
],
"delivery": null,
"header": null,
"footer": null,
"barcode": null,
"cashier_name": null,
"departament": null,
"previous_receipt_id": null
}
"id" - унікальний ідентифікатор чека у форматі UUID,
"fiscal_code" - фіскальний номер чека. При створенні чека у онлайні чек отримує фіскальний код згодом, після обробки та передачі його у ДПС, яка у відповідь призначає чеку офлайн код,
"fiscal_date" - фіскальна дата, з якою чек буде зареєстровано у ДПС. Чек отримає фіскальну дату після завершення обробки,
"is_online" - true/false, режим створення чека,
"is_sell" - true/false флаг чека продажу,
"total_payment" - сума оплати за товари у чеку,
"total_sum" - сума вартості товарів у чеку,
"total_rest" - сума здачі,
"round_sum" - сума заокруглення,
"goods" - блок даних з переліком товарів.
- "code" - код товару (обов'язковий параметр),
- "name" - назва товару (обов'язковий параметр),
- "header" - хедер товару,
- "footer" - футер товару,
- "uktzed" - код уктзед,
- "price" - ціна товару,
- "excise_barcodes" - цифрове позначення штихового коду акцизної марки, якщо їх >1,
- "barcode" - штрих-код товару,
- "tax" - номер податку
- "sum" - сума у копійках,
- "quantity" - кількість у тисячах. 1 шт = 1000,
- "is_return" - true/false флаг який помічає обраний чек як чек повернення
"taxes" - блок даних з інформацією про податкові ставки, які використовувались для товару в чеку
- "code" - цифровий код податкової ставки,
- "label" - назва податкової ставки,
- "symbol" - літерний код податкової ставки,
- "rate" - розмір податкової ставки у відсотках,
- "extra_rate" - розмір додаткового збору у відсотках,
- "value" - розмір податку,
- "extra_value" - розмір додаткового збору (наприклад, для акцизу),
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку,
- "returns_turnover" - сума повернень з цією податковою ставкою (оборот) у копійках,
- "sales_turnover" - сума продажів з цією податковою ставкою (оборот) у копійках,
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
"discounts" - блок даних про знижки, які застосовувались до всього чеку.
- "type" - тип знижки "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)
- "mode" - режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)
- "value" - розмір знижки
- "tax_code"/"tax_codes" - коди податкових ставок, які використовуються для товару і були вказані при створенні знижки
- "name" - назва знижки/надбавки
- "sum" - сума знижки/надбавки
"payments" - блок даних з інформацією про платежі
- "type" - тип платежу CASH/CASHLESS
- "pawnshop_is_return" - параметр, який визначає даний чек як чеки видачі коштів ломбарду. За замовчуванням для звичайних чеків, створених не для ломбардів, має бути null
- "value" - сума внесення/винесення у копійках. Для формування чеку службового винесення потрібно перед сумою вказати
- "label" - текстова мітка, яка буде розміщена на чеку
- "code" - номер оплати (тільки для безготівкових платежів)
- "commission" - комісія (тільки для безготівкових платежів)
- "card_mask" - маска карти (не більше 19 символів) (тільки для безготівкових платежів)
- "bank_name" - назва банку (тільки для безготівкових платежів)
- "auth_code" - код авторизації банківської операції (тільки для безготівкових платежів)
- "rrn" - Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)
- "payment_system" - платіжна система (тільки для безготівкових платежів)
- "owner_name" - ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)
- "terminal" - інформація про платіжний термінал (тільки для безготівкових платежів)
- "acquirer_and_seller" - ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)
- "receipt_no" - номер банківського чека (тільки для безготівкових платежів)
- "signature_required" - true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира
"type" - тип транзакції,
"delivery" - блок даних з інформацією про доставку чека,
- "email" - e-mail клієнта для відправки копії чека,
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"header" - хедер чека,
"footer" - футер чека,
"barcode" - штрих-код чека,
"cashier_name" - названи касира,
"departament" - назва відділу,
"previous_receipt_id" - UUID попереднього чека
¶
¶ Створення чеку видачі готівкових коштів держателю ЕПЗ
Метод /api/v1/receipt/cash-withdrawal призначений для створення чека видачі готівкових коштів держателю ЕПЗ (видача готівки на касі).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (опціонально)>
X-Client-Version: <версія інтеграції (опціонально)>
Content-Type: application/json
¶ Request body
{
"payment":
{
"code": <номер оплати>,
"value": <сума оплати у копійках>,
"label": "<текстова назва форми оплати>",
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
},
"print": <true/false, команда на друк чека>
}
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/receipt/cash-withdrawal' \ -H 'accept: application/json' \ -H 'X-Client-Name: Test-Client-Name' \ -H 'X-Client-Version: Test-Client-Version' \ -H 'Content-Type: application/json' \ -d '{ "payment": { "value": 10000, "commission": 50, "label": "Картка", "card_mask": "XXXXXXXXXXXX6734", "bank_name": "МійБанк", "auth_code": "078359", "rrn": "305817547765", "payment_system": "VISA", "owner_name": "CHEREZPLETINNOHUZADYRAISHCHENKO PETRO", "terminal": "S1LF0EUR", "acquiring": "MyBank", "acquirer_and_seller": "MyBank", "receipt_no": "1", "signature_required": true, "code": 1 }, "print": true, "print_simple_text": false}'
¶ Response body
{
"custom_id": null,
"status": "DONE",
"cashier_name": null,
"departament": null,
"header": null,
"footer": null,
"barcode": null,
"tax_codes": null,
"files": [
{
"mime": "image/png",
"path": "C:\\checkbox.kasa.manager\\profiles\\TEST\\files_printer\\2023-10-25\\07-39-59-519740_document.png"
}
],
"signature": "gAAAAABlOJwfbaIZ8wmVErxAYyXQuB0Fb9_r9SX7r5VRbbl09Z6tSbV7nWZJqddY_XEl5DmjUBUaU8eaTwxUplhfGKp2uM4CfBpBpPF4pj6W0iCoYICVqze6K6Fb_NqKXAK0tTaSdE_mauhlhZ3UJa5FHSosVnSMxBVUy820WQ-z-bj5X7LEs8NyouVlGFKT2gAA8z3TCpnVsrKN5VQySueBTpl0OzFluZ_Ob8YUvcOnK2mpvRETXkjUEfiBsv8tbUXb6yyvAcEfKlYufSVr3OaLT8uZu9Pkbi_GO998hikJr3vRCvXTy78kQTHIADXGBaWiKUyc4ZN2ANR2rqKe34i5DJOeWskzbXPaU7o0tGe0nisH4BYlTFNIJPbPAbWDhyfxkPl7Rrk1ohc-4-VhGA3PAP6hLs3PfvNtP0EEjacOsIm4Oq0Lur2rzjIxGRDHcOnUxKvS-hEVATQGRTKmxc5U0YWWN0qc9vpoIxc_sCOvO3fdF7Xygci0QvRh6ujhvczZx73V5qjRCRpUvEI72feot8RcA2PiWEuAKd8lCUNt0B4GfqoMCZ1l-OXHTtzYE3pcuVoacR_rW5hivzdAwtOlxv-TSETeMZbZVTfLjQH1a74nbP80CEHfOMYRU6WAyNeviRug0TORoRUAx58nGxY8d0_EUSxNJzDx5HXGg05o82Y3J2fGnyIWDLRMdkhLZ5n54VU_nG0Irhye7ZscM71N3mSdmwwa_zJJlwCQiKhcUSgYzh3ON2W_Yy6NEKa1F_vLmZCmU1Qmk0GJcmotdmhn-o12QQo-C_SSYtktDmrVKZ7Vra35ksVB7LUlj_dKDATRVK2kNkfhcUEQY2s_XnKt8-yaObN5kjTAp4lK7dR4rUOsfGWVC66OPDXAIWZvwPF_51f11111",
"fiscal_code": "TEST-h11111",
"created_at": "2023-10-25T07:39:59.519740",
"id": 4,
"updated_at": "2023-10-25T07:40:00.148788",
"transaction_id": 9,
"type": "CASH_WITHDRAWAL",
"shift_id": 3,
"external_id": "bb855c63-ba3e-43f2-9134-bf61cab11111"
}
"custom_id" - унікальний ідентифікатор чека у форматі UUID,
"status" - статус виконання команди,
"cashier_name" - назва касира,
"departament" - назва відділу,
"header" - хедер чека,
"footer" - футер чека,
"barcode" - штрих-код чека,
"tax_codes" - код податку,
"files" - масив данних з інформацією про файл чека:
- "mime" - тип збереженного файлу
- "path" - шлях збереженого файлу чека
"signature" - шифрований підпис транзакції,
"fiscal_code" - фіскальний номер чека. При створенні чека у онлайні чек отримує фіскальний код згодом, після обробки та передачі його у ДПС, яка у відповідь призначає чеку офлайн код,
"created_at" - час створення транзакції,
"id" - порядковий номер чека в локальній БД,
"updated_at" - час запису транзакції в локальну БД,
"transaction_id" - порядковий номер транзакції в локальній БД,
"type" - тип транзакції (завжди "CASH_WITHDRAWAL"),
"shift_id" - номер зміни, у якій було виконано транзакцію,
"external_id" - UUID транзакції.
¶
¶ Звіти
¶ Перевірка балансу зміни за допомогою X-Звіту
Х-звіт – це не фіскальний чек, призначений для контролю роботи каси. Показує всі операції (підсумкові суми), проведені протягом зміни. Х-звіт можна знімати в будь-який час і в будь-якій кількості протягом робочого часу.
Для друку X-звіту потрібно використовувати метод /api/v1/shift/xreport. У відповідь каса поверне х-звіт у форматі JSON та збереже зображення звіту, яке буде відрпавлено на принтер для подальшого друку.
¶ Request headers
accept: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім
curl -X 'POST' \ 'http://127.0.0.1:9200/api/v1/shift/xreport' \ -H 'accept: application/json' \ -d ''
¶ Response body
{
"status": true,
"report": {
"serial": 25,
"taxes": [
{
"code": 5,
"label": "ПДВ 20%",
"symbol": "Є",
"rate": 20,
"extra_rate": 0,
"sell_sum": 20000,
"return_sum": 0,
"sales_turnover": 120000,
"returns_turnover": 0,
"setup_date": "2023-09-27T07:57:32.979471",
"no_vat": false
}
],
"payments": [
{
"type": "CASH",
"code": null,
"label": "Готівка",
"sell_sum": 156000,
"return_sum": 0,
"service_in": 100,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
},
{
"type": "CASH",
"code": null,
"label": "Картка",
"sell_sum": 0,
"return_sum": 0,
"service_in": 100,
"service_out": 0,
"cash_withdrawal": 0,
"cash_withdrawal_commission": 0
}
],
"sell_receipts_count": 13,
"return_receipts_count": 0,
"cash_withdrawal_receipts_count": 0,
"last_receipt_id": "afcb657e-af26-4e1a-8f36-c682a11becaf",
"initial": 0,
"balance": 156200,
"sales_round_up": 0,
"sales_round_down": 0,
"returns_round_up": 0,
"returns_round_down": 0,
"discounts_sum": 0,
"extra_charge_sum": 0
}
}
"status" - статус виконання команди,
"report" - блок даних з інформацією
"serial" - порядковий номер звіту,
"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
"payments" - блок з інформацією про платежі в рамках поточної зміни
- "type" - "CASH",
- "code" - код способу оплати,
- "label" - текстовий опис, який має містити назву форми оплати. Наприклад, Готівка або Картка,
- "sell_sum" - сума продажів з поточною форомою оплати у копійках,
- "return_sum" - сума повернень з поточною форомою оплати у копійках,
- "service_in" - сума службових внесень з поточною форомою оплати у копійках,
- "service_out" - сума службових винесень з поточною форомою оплати у копійках,
- "cash_withdrawal" - сума операцій з видачі готівкових коштів у копійках,
- "cash_withdrawal_commission" - сума комісійних нарахувань по операціям з видачі готівкових коштів у копійках
"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" - сума копійок чеків повернення, заокруглених в меньшу сторону,
"discounts_sum" - сума знижок в поточній зміні,
"extra_charge_sum" - сума надбавок в поточній зміні.
¶
¶ Створення періодичного звіту
Окрім Х- або Z-звіту, ви можете також формувати періодичний звіт методом /api/v1/reports/periodical. При цьому інформація, яка не зберігається локально (за замовченням зберігається інформація за останні 30 днів) - запитується з серверів checkbox. Дата має бути вказаною у форматі <YYYY-MM-DDTHH:MM:SS>.
¶ Request headers
accept: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім
curl -X 'GET' \ 'http://127.0.0.1:9200/api/v1/reports/periodical?from_date=2023-08-01T00%3A00%3A00&to_date=2023-09-01T00%3A00%3A00&is_short=true' \ -H 'accept: application/json'
¶ Request body
null
null - у разі успішого виконання операції. У випадку помилки, повернеться message із причиною помилки.
| Приклад повного періодичного звіту | Приклад скороченного періодичного звіту |
|---|---|
 |
 |
¶
¶ Опис можливих помилок
Опис можливих помилок
| Responce body 🖥️ | Description ✍🏻 | |
|---|---|---|
| 400 | CheckBox Підпис неактивний, запустіть його, будь ласка | Якщо підпис касира не запущений, то ви отримаєте помилку 400. Ви можете використовувати його на захищеному хмарному сервісі, або встановити локально. |
| 400 | Офлайн сессія триває більше <n> годин, касу заблоковано! Необхідно відновити зв'язок з сервером. |
За замовченням дозволено перебувати в офлайн режимі роботи не більше 36 годин. Якщо ви перевищете цей ліміт, ви отримаєте помилку 400. В такому випадку роботу каси буде заблоковано, поки вона не перейде в онлайн режим роботи. Якщо при перевірці стану каси вона тривалий час знаходиться в офлайн режимі - будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом. |
| 400 | Зміну не відкрито | Якщо ви спробуєте виконати запит у закритій зміні, а його можна виконати тільки у відкритій зміні - ви отримаєте помилку 400 |
| 400 | Створення чеків дозволено лише у день відкриття зміни. Для продовження роботи закрийте чинну зміну і відкрийте нову | Якщо ви спробуєте виконати фіскальний запит у касовій зміні, яка відкрита минулим днем - ви отримаєте помилку 400 |
| 400 | Зміна відкрита вже понад 24 години. Для продовження роботи закрийте чинну зміну і відкрийте нову | Якщо ви спробуєте виконати фіскальний запит у касовій зміні, яку відкрито понад 24 години (при цьому перевірку дня відкриття зміни відключено) - ви отримаєте помилку 400 |
| 400 | Неможливо виконати операцію, оскільки в касі недостатньо коштів (<сума, яку ви хочете вилучити> > <сума готівки у касі>) | Якщо ви спробуєте вилучити з каси більше коштів, ніж є у наявності, то отримаєте у відповідь помилку 400 |
| 400 | Сума копійок внесення або вилучення повинна бути кратною 10 (найменша копійка в обігу готівки) | Якщо ви спробуєте вилучити з каси копійки меньше, ніж є в обігу, то отримаєте у відповідь помилку 400 |
| 400 | Сума платежів не може бути меньшою ніж сума чеку | Якщо у блоці платежів вказати суму меншу, ніж ціна товару, то ви отримаєте помилку 400 |
| 400 | Сума платежів повинна дорівнювати сумі чеку повернення (4544.00) | Якщо у чеку поверненя в блоці платежів вказати суму, що відрізняється від загальної ціни товарів, то ви отримаєте помилку 400 |
| 400 | Виявлено невідповідніть поточного і попереднього стану каси. Зверніться у підтримку | Якщо файли захисту офлайн режиму було змінено або видалено, ви отримаєте помилку 400. Будь ласка, зверніться до служби підтримки Checkbox зручним для вас способом. |
| 400 | Дата створення останньої транзакції в локальній БД більше ніж поточна дата.Касу заблоковано. Перевірте налаштування локальної дати та часу | Якщо в локальній базі даних дата останньої транзакції більша, ніж поточна дата (наприклад, збився час на ПК), ви отримаєте помилку 400. Будь ласка, зачекайте, поки не пройде час створення транзакції |
| 400 | Дія не може бути виконана в режимі оффлайн. Перевірте правильність пін кода та ключа ліцензії | Якщо ви намагаєтесь виконати дію, але каса перебуває в офлайн режимі із сервером checkbox (наприклад, при розірванні інтернет-зв'язку), ви отримаєте помилку 400. Будь ласка, перевірте наявність інтернет-зв'язку |
| 403 | Термін дії ключа закінчився <YYYY-MM-DD HH:MM:SS> |
У випадку, якщо термін дії ключа касира скінчився, ви отримаєте помилку 403. Для продовження роботи вам необхідно отримати новий ключ та зареєструвати нового касира. |
| 403 | Доступ заборонено, оскільки касира деактивовано | Якщо касир деактивований користувачем, сервер поверне помилку 403 |
| 403 | Касира заблоковано: <причина блокування> |
Якщо касира було заблоковано на сторноні Checkbox (наприклад, сертифікат ключа відізвано ДПС або АЦСК, яким його було видано) - сервер поверне помилку 403. Будь ласка, зв'яжіться із службою підтримки Checkbox зручним для вас способом для вирішення питання. |
| 403 | Касу заблоковано через відсутність чеків за попередній період, необхідно сплатити за послуги користування касою для автоматичного розблокування або залишити заявку на веб-порталі https://my.checkbox.in.ua | У випадку, якщо ви не користувались касою тривалий період - вона автоматично заморожується, щоб не нараховувалась абонплата. Для розморозки - необхідно сплатити рахунок за користування касами та звернутись до служби підтримки Checkbox зручним для вас способом. |
| 403 | Каса заблокована через помилку ERROR_TYPE від ДПС |
У випадку, якщо касу деактивовано в ДПС, але вона активна в кабінеті Checkbox, під час наступного відкриття зміни або видачі чека ви отримаєте помилку. Будь ласка, виконайте синхронізацію даних з ДПС в особистому кабінеті Checkbox та зверніться до служби підтримки. |
| 403 | Для видачі чеків, будь ласка, оплатіть рахунок за користування касами. | Якщо ви не оплатили послуги Checkbox завчасно, усі каси організації буде заблоковано, сервер поверне помилку 403. Будь ласка, зверніться до служби підтримки Checkbox, що б ми оперативно розблокували роботу кас та надіслали вам актуальний рахунок. |
| 409 | Каса вже використовується іншим ID агента. Ймовірно запит виконано з каси дублікату. Зверніться до підтримки | При першому запуску каси для неї та касира встановлюється унікальний ідентифікатор пристрою X-Device-ID, який складається із декількох параметрів. Якщо ви запустили касу на іншому ПК, або від імені іншого користувача - ви отримаєте помилку 409. |
| 422 | { |
Якщо запит сформовано невірно, то ви отримаєте помилку 422, де буде вказано приблизне розташування та опис помилки. |
Якщо у Вас виникли питання, Ви знайшли помилку або хочете запропонувати вказати додаткову інформацію в інструкціях - Ви завжди можете зв'язатись з нами зручним для вас способом.