Замовлення в системі checkbox - це проект фіскального чека, який необхідно фіскалізувати кур'єру після доставки замовлення покупцеві та його оплати.
Розділ замовлень доступний лише в мобільному додатку checkbox на android та після увімкнення відповідного функціоналу для касира службою технічної підтримки checkbox. Функціонал для iOS в розробці, орієнтовні терміни релізу - І квартар 2024 року.
Після увімкнення відповідного функціоналу в мобільному додатку буде доступний розділ Замовлення бокового меню, де відбувається робота із створеними по REST API із зовнішньої системи замовленнями.
¶ Отримання списку замовлень
Використовуйте цей метод, щоб отримати список вже зареєстрованих замовлень.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення, де вимагається)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/orders?limit=25&offset=0' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token'
¶ Response body
{
"meta": {
"limit": 25,
"offset": 0
},
"results": [
{
"id": "562afb00-3a35-4e6b-a854-5c7d2fa11111",
"order_id": "Доставка меду",
"status": "SAVING",
"custom_status": null,
"is_paid": true,
"payment_method": "CASHLESS_ON_DELIVERY",
"receipt_draft": {
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": [
"[email protected]"
],
"phone": null
},
"type": "SELL"
},
"delivery_details": {
"address": {
"address_type": "flat",
"street": "Тестова 41а",
"entrance": "4",
"floor": "4",
"apartment_number": "32",
"elevator": false,
"intercom": true
},
"box_id": [
1258
],
"client_name": "Шпак Антон Семенович",
"client_phone_number": "+380962111111",
"delivery_time": "2023-10-19T07:11:10+00:00",
"client_comment": "Ліфт не працює",
"thermal_dependence": true
},
"created_at": "2023-10-22T11:43:45.325360+00:00",
"updated_at": "2023-10-22T11:50:09.723674+00:00",
"not_fiscalize": false,
"stock_code": null
}
]
}
"results" - масив даних із інформацією про замовлення
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"status" - статус замовлення, можливі статуси замовлень: PENDING, SAVING, SUCCESS, CANCELLED.
"custom_status" - користувацький статус замовлення, можливі статуси замовлень: NEW, IN_WORK, APPROVED, TRANSFERRED_TO_WMS, PREPARING, DELIVERING, DELIVERED, DONE, CANCELED, TEST
"is_paid" - true/false, ознака попередньої оплати замовлення
"payment_method" - спосіб оплати замовлення, можливі способи оплати: CARD_AFTER_ASSEMBLING(картою після збірки замовлення), CASH_ON_DELIVERY(готівкою при отриманні замовлення), CASHLESS_ON_DELIVERY(карткою при отриманні замовлення)
"receipt_draft" - інформація про чек (payload створення фіскального чека)
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)
"delivery_details" - масив данних із інформацією про адресу доставки:
- "address_type" - тип адреси, можливі значення:
flat,house,office(квартира, дім, офіс) - "street" - вулиця та номер будинку
- "entrance" - номер під'їзду
- "floor" - номер поверху
- "apartment_number" - номер квартири
- "elevator" - true/false, наявність ліфту
- "intercom" - true/false, наявніть домофону
- "box_id" - масив данних із інформацією про номер пакування/ящика
- "client_name" - ПІБ покупця, який має отримати доставлене замовлення
- "client_phone_number" - номер телефону покупця
- "delivery_time" - орієнтовна дата доставки замовлення
- "client_comment" - коментар для кур'єра про замовлення
- "thermal_dependence" - true/false, ознака температурної чутливості замовлення
"created_at" - дата створення замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останньої зміни замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"not_fiscalize" - true/false, ознака наявності не фіскального товару
"stock_code" - true/false - ?
¶ Створення нового замовлення
Використовуйте цей метод, щоб створити нове замовлення. У відповідь буде повернуто список тільки доданих замовлень. Замовлення, які вже зареєстровані в системі - будуть проігноровані.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<унікальний ідентифікатор замовлення у форматі UUID>",
"order_id": "<назва замовлення в мобільному додатку>",
"cashier_id": "<унікальний ідентифікатор касира у форматі UUID>",
"custom_status": "<користувацький статус замовлення, можливі статуси замовлень: `NEW`,`IN_WORK`,`APPROVED`,`TRANSFERRED_TO_WMS`,`PREPARING`,`DELIVERING`,`DELIVERED`,`DONE`,`CANCELED`,`TEST`>",
"payment_method": "<спосіб оплати замовлення, можливі способи оплати: `CARD_AFTER_ASSEMBLING`(картою після збірки замовлення), `CASH_ON_DELIVERY`(готівкою при отриманні замовлення), `CASHLESS_ON_DELIVERY`(карткою при отриманні замовлення)>",
"receipt_draft": {
"cashier_name": "<ПІБ касира, вказане користувачем при його реєстрації>",
"departament": "<назва відділу>",
"goods": [
{
"good": {
"code": "<код товару>",
"name": "<назва товару>",
"barcode": "<штрих-код товару>",
"excise_barcode": "<ифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках за одиницю товару>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару, попередньо доданих до номенклатури товарів checkbox>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"total_sum": <сума вартості товару>
},
{
"good":{
<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>
}
}
],
"additional_goods": [
{
"good": {
"code": "<код товару>",
"name": "<назва товару>",
"barcode": "<штрих-код товару>",
"excise_barcode": "<ифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках за одиницю товару>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару, попередньо доданих до номенклатури товарів checkbox>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"total_sum": <сума вартості товару>
},
{
"good":{
<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>
}
}
],
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"payments":
[
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"provider_type": <у разі застосування технології TAPXPHONE, дане поле буде заповнено автоматично. Можливі значення: `TAPXPHONE`, `POSCONTROL`, `TERMINAL`>,
"value": <сума оплати у копійках, < 100000000000>,
"label": "<текстова назва форми оплати, [1, 128] characters>",
"code": <номер оплати (тільки для безготівкових платежів), (0, 10)>,
"commission": <комісія (тільки для безготівкових платежів)>,
"card_mask": "<маска карти (не більше 19 символів) (тільки для безготівкових платежів)>",
"bank_name": "<назва банку (тільки для безготівкових платежів)>",
"auth_code": "<код авторизації банківської операції (тільки для безготівкових платежів)>",
"rrn": "<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)>",
"payment_system": "<платіжна система (тільки для безготівкових платежів)>",
"owner_name": "<ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)>",
"terminal": "<інформація про платіжний термінал (тільки для безготівкових платежів)>",
"acquirer_and_seller": "<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)>",
"receipt_no": "<номер банківського чека (тільки для безготівкових платежів)>",
"tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"signature_required": <true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
},
{
<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>
}
],
"bonuses":
[
{
"bonus_card": <інформація про бонусну картку покупця, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"value": <інформація про накопичені бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"additional_info": <додаткова інформація про бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>
}
],
"header": "<службова інформація, вказана в хедері чека>",
"footer": "<службова інформація, вказана у футері чека>",
"barcode": "<штрих-код чека>",
"delivery":
{
"email": "<e-mail клієнта для відправки копії чека>",
"emails":
["<e-mail клієнта для відправки копії чека 1>","<e-mail клієнта для відправки копії чека 2>"],
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"type": "<тип чека, можливі типи: `SELL`, `RETURN`, `SERVICE_IN`, `SERVICE_OUT`, `SERVICE_CURRENCY`, `CURRENCY_EXCHANGE`, PAWNSHOP`, `CASH_WITHDRAWAL` (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)>"
},
"delivery_details": {
"address": {
"address_type": "<тип адреси, можливі значення: `flat`, `house`, `office` (квартира, дім, офіс)>",
"street": "<вулиця та номер будинку>",
"entrance": "<номер під'їзду>",
"floor": "<номер поверху>",
"apartment_number": "<номер квартири>",
"elevator": <true/false, наявність ліфту>,
"intercom": <true/false, наявніть домофону>
},
"box_id": [
<масив данних із інформацією про номер пакування/ящика, int>
],
"client_name": "<ПІБ покупця, який має отримати доставлене замовлення>",
"client_phone_number": "<номер телефону покупця>",
"delivery_time": "<орієнтовна дата доставки замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm>",
"client_comment": "<коментар для кур'єра про замовлення>",
"thermal_dependence": <true/false, ознака температурної чутливості замовлення>
},
"not_fiscalize": <true/false, ознака не фіскального замовлення>,
"stock_code": "<string>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/orders' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '[ { "order_id":"Доставка меду", "payment_method":"CASHLESS_ON_DELIVERY", "receipt_draft":{ "goods":[ { "good":{ "code":"1", "name":"Гречаний мед (400г)", "price":16000, "tax":[ 8 ] }, "quantity":2000, "is_return":false }, { "good":{ "code":"2", "name":"Липовий мед (655г)", "price":28000, "tax":[ 8 ] }, "quantity":1000, "is_return":false } ], "discounts":[ { "type":"DISCOUNT", "mode":"VALUE", "value":2000, "name":"Використані бонуси" } ], "payments":[ { "type":"CASHLESS", "label":"Картка", "value":58000 } ], "delivery":{ "email":"[email protected]" }, "type":"SELL" }, "delivery_details":{ "address":{ "address_type":"flat", "street":"Тестова 41а", "entrance":"4", "floor":"4", "apartment_number":"32", "elevator":false, "intercom":true }, "box_id":[ 1258 ], "client_name":"Шпак Антон Семенович", "client_phone_number":"+380962111111", "client_comment":"Ліфт не працює", "thermal_dependence": true, "delivery_time":"2023-10-19T10:11:10+0300" }, "not_fiscalize":false }]'
¶ Response body
{
"id": "562afb00-3a35-4e6b-a854-5c7d2fa11111",
"order_id": "Доставка меду",
"status": "PENDING",
"custom_status": null,
"is_paid": true,
"payment_method": "CASHLESS_ON_DELIVERY",
"receipt_draft": {
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": [
"[email protected]"
],
"phone": null
},
"type": "SELL"
},
"delivery_details": {
"address": {
"address_type": "flat",
"street": "Тестова 41а",
"entrance": "4",
"floor": "4",
"apartment_number": "32",
"elevator": false,
"intercom": true
},
"box_id": [
1258
],
"client_name": "Шпак Антон Семенович",
"client_phone_number": "+380962111111",
"delivery_time": "2023-10-19T07:11:10+00:00",
"client_comment": "Ліфт не працює",
"thermal_dependence": true
},
"created_at": "2023-10-22T11:43:45.325360+00:00",
"updated_at": null,
"not_fiscalize": false,
"stock_code": null
}
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"status" - статус замовлення, можливі статуси замовлень: PENDING, SAVING, SUCCESS, CANCELLED.
"custom_status" - користувацький статус замовлення, можливі статуси замовлень: NEW, IN_WORK, APPROVED, TRANSFERRED_TO_WMS, PREPARING, DELIVERING, DELIVERED, DONE, CANCELED, TEST
"is_paid" - true/false, ознака попередньої оплати замовлення
"payment_method" - спосіб оплати замовлення, можливі способи оплати: CARD_AFTER_ASSEMBLING(картою після збірки замовлення), CASH_ON_DELIVERY(готівкою при отриманні замовлення), CASHLESS_ON_DELIVERY(карткою при отриманні замовлення)
"receipt_draft" - інформація про чек (payload створення фіскального чека)
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)
"delivery_details" - масив данних із інформацією про адресу доставки:
- "address_type" - тип адреси, можливі значення:
flat,house,office(квартира, дім, офіс) - "street" - вулиця та номер будинку
- "entrance" - номер під'їзду
- "floor" - номер поверху
- "apartment_number" - номер квартири
- "elevator" - true/false, наявність ліфту
- "intercom" - true/false, наявніть домофону
- "box_id" - масив данних із інформацією про номер пакування/ящика
- "client_name" - ПІБ покупця, який має отримати доставлене замовлення
- "client_phone_number" - номер телефону покупця
- "delivery_time" - орієнтовна дата доставки замовлення
- "client_comment" - коментар для кур'єра про замовлення
- "thermal_dependence" - true/false, ознака температурної чутливості замовлення
"created_at" - дата створення замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останньої зміни замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"not_fiscalize" - true/false, ознака наявності не фіскального товару
"stock_code" - true/false - ?
.gif)
¶ Перевірка замовлення
У відповідь на створення нового замовлення, ви отримаєте його унікальний ідентифікатор у форматі UUID. За допомогою нього, ви в будь-який момент можете перевірити інформацію про замовлення.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/orders/562afb00-3a35-4e6b-a854-5c7d2fa11111?orders_all=false' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token'
¶ Response body
{
"id": "562afb00-3a35-4e6b-a854-5c7d2fa11111",
"order_id": "Доставка меду",
"status": "SAVING",
"custom_status": null,
"is_paid": true,
"payment_method": "CASHLESS_ON_DELIVERY",
"receipt_draft": {
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": [
"[email protected]"
],
"phone": null
},
"type": "SELL"
},
"delivery_details": {
"address": {
"address_type": "flat",
"street": "Тестова 41а",
"entrance": "4",
"floor": "4",
"apartment_number": "32",
"elevator": false,
"intercom": true
},
"box_id": [
1258
],
"client_name": "Шпак Антон Семенович",
"client_phone_number": "+380962111111",
"delivery_time": "2023-10-19T07:11:10+00:00",
"client_comment": "Ліфт не працює",
"thermal_dependence": true
},
"created_at": "2023-10-22T11:43:45.325360+00:00",
"updated_at": "2023-10-22T11:50:09.723674+00:00",
"not_fiscalize": false,
"stock_code": null
}
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"status" - статус замовлення, можливі статуси замовлень: PENDING, SAVING, SUCCESS, CANCELLED.
"custom_status" - користувацький статус замовлення, можливі статуси замовлень: NEW, IN_WORK, APPROVED, TRANSFERRED_TO_WMS, PREPARING, DELIVERING, DELIVERED, DONE, CANCELED, TEST
"is_paid" - true/false, ознака попередньої оплати замовлення
"payment_method" - спосіб оплати замовлення, можливі способи оплати: CARD_AFTER_ASSEMBLING(картою після збірки замовлення), CASH_ON_DELIVERY(готівкою при отриманні замовлення), CASHLESS_ON_DELIVERY(карткою при отриманні замовлення)
"receipt_draft" - інформація про чек (payload створення фіскального чека)
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)
"delivery_details" - масив данних із інформацією про адресу доставки:
- "address_type" - тип адреси, можливі значення:
flat,house,office(квартира, дім, офіс) - "street" - вулиця та номер будинку
- "entrance" - номер під'їзду
- "floor" - номер поверху
- "apartment_number" - номер квартири
- "elevator" - true/false, наявність ліфту
- "intercom" - true/false, наявніть домофону
- "box_id" - масив данних із інформацією про номер пакування/ящика
- "client_name" - ПІБ покупця, який має отримати доставлене замовлення
- "client_phone_number" - номер телефону покупця
- "delivery_time" - орієнтовна дата доставки замовлення
- "client_comment" - коментар для кур'єра про замовлення
- "thermal_dependence" - true/false, ознака температурної чутливості замовлення
"created_at" - дата створення замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останньої зміни замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"not_fiscalize" - true/false, ознака наявності не фіскального товару
"stock_code" - true/false - ?
¶ Оплата замовлення
Існує 2 способи оплати замовлення:
- В мобільному додатку checkbox:
· Перейдіть у розділ Замовлення. Для цого, відкрийте бокове меню, натиснувши ≡ в лівому верхньому куті головного меню.
· Оберіть необхідне відкрите замовлення. Перевірте дані.
· Прогорнувши замовлення вниз, натисніть Підтвердити.
· Як тільки фіскальний чек буде створено, відкриється сторінка із його відображенням.
· Щоб завершити замовлення, натисніть на ✅ внизу екрану. - За допомогою REST API методом /api/v1/receipts/sell. При цьому в payload запиту на створення чека має містити ті ж самі дані, що і запит на створення замовлення, та додатково має бути вказано "order_id": "uuid" створенного раніше замовлення.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"id": "<UUID чека>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":
[
{
"good":
{
"code": "<Код товару>",
"name": "<Назва товару>",
"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 флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"is_pawnshop": <true/false флаг, яким можна позначити, що даний чек є чеком ломбарду>,
"custom": {
"html_global_header": "<глобальний хедер для чеків html/pdf візуалізацій>",
"html_global_footer": "<глобальний футер для чеків html/pdf візуалізацій>",
"html_body_style": "<фон сторінки з чеком>",
"html_receipt_style": "<стиль блоку з чеком>",
"html_ruler_style": "<стиль роздільника з зірочками між блоками чеку",
"html_light_block_style": "<стиль світлих блоків, це весь підвал чеку та клітинки з вартістю та кількістю>",
"text_global_header": "<глобальний хедер для чеків png/txt візуалізацій>",
"text_global_footer": "<глобальний футер для чеків png/txt візуалізацій>"
}
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/receipts/sell' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "goods":[ { "good":{ "code":"1", "name":"Гречаний мед (400г)", "price":16000, "tax":[ 8 ] }, "quantity":2000, "is_return":false }, { "good":{ "code":"2", "name":"Липовий мед (655г)", "price":28000, "tax":[ 8 ] }, "quantity":1000, "is_return":false } ], "discounts":[ { "type":"DISCOUNT", "mode":"VALUE", "value":2000, "tax_code":8, "name":"Використані бонуси" } ], "payments":[ { "type":"CASHLESS", "label":"Картка", "value":58000 } ], "delivery":{ "email":"[email protected]" }, "order_id":"fdac0fc7-d6ec-490b-a0f2-4dc085611111"}'
¶ Response body
{
"id": "bb1d2ad9-7a10-47c2-9c9e-4e47b9b11111",
"type": "SELL",
"transaction": {
"id": "3d0308a5-056f-42f7-aec7-2be5bf211111",
"type": "RECEIPT",
"serial": 113,
"status": "PENDING",
"request_signed_at": null,
"request_received_at": null,
"response_status": null,
"response_error_message": null,
"response_id": null,
"offline_id": null,
"created_at": "2023-10-22T15:45:23.471495+00:00",
"updated_at": "2023-10-22T15:45:23.471495+00:00",
"original_datetime": "2023-10-22T15:45:23.471495+00:00",
"previous_hash": "c01218343fdeb453626e14108def46014e3f872a42dd2d9fb1afe3eed8711111"
},
"serial": 51,
"status": "CREATED",
"goods": [
{
"good": {
"code": "1",
"barcode": null,
"name": "Гречаний мед (400г)",
"excise_barcodes": null,
"header": null,
"footer": null,
"uktzed": null,
"price": 16000
},
"good_id": null,
"sum": 32000,
"quantity": 2000,
"is_return": false,
"taxes": [
{
"id": "9ff1ea9a-4d10-452f-b3c1-59e59b711111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"value": 0,
"extra_value": 0
}
],
"discounts": []
},
{
"good": {
"code": "2",
"barcode": null,
"name": "Липовий мед (655г)",
"excise_barcodes": null,
"header": null,
"footer": null,
"uktzed": null,
"price": 28000
},
"good_id": null,
"sum": 28000,
"quantity": 1000,
"is_return": false,
"taxes": [
{
"id": "486ecca1-9bba-40c2-824d-8e9fc5a11111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"value": 0,
"extra_value": 0
}
],
"discounts": []
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"total_sum": 58000,
"sum": 58000,
"total_payment": 58000,
"total_rest": 0,
"rest": 0,
"round_sum": 0,
"fiscal_code": null,
"fiscal_date": null,
"delivered_at": null,
"created_at": "2023-10-22T15:45:23.471495+00:00",
"updated_at": null,
"taxes": [
{
"id": "f4d70f63-5728-4160-bf5a-23c845811111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"value": 0,
"extra_value": 0
}
],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [
8
],
"name": "Використані бонуси",
"privilege": null,
"sum": -2000
}
],
"order_id": "fdac0fc7-d6ec-490b-a0f2-4dc085611111",
"header": null,
"footer": null,
"barcode": null,
"custom": null,
"context": null,
"is_created_offline": false,
"is_sent_dps": false,
"sent_dps_at": null,
"tax_url": null,
"related_receipt_id": null,
"technical_return": false,
"stock_code": null,
"currency_exchange": null,
"shift": {
"id": "b56259ab-bf5a-4253-bf1b-6b539e311111",
"serial": 31,
"status": "OPENED",
"z_report": null,
"opened_at": "2023-10-22T11:15:13.045546+00:00",
"closed_at": null,
"initial_transaction": {
"id": "8d01c26c-c94a-424e-ac24-e8414c311111",
"type": "SHIFT_OPEN",
"serial": 104,
"status": "DONE",
"request_signed_at": "2023-10-22T11:15:13.117976+00:00",
"request_received_at": "2023-10-22T11:15:13.159911+00:00",
"response_status": "OK",
"response_error_message": null,
"response_id": "TEST-5g_To7",
"offline_id": null,
"created_at": "2023-10-22T11:15:13.045546+00:00",
"updated_at": "2023-10-22T11:15:13.186920+00:00",
"original_datetime": "2023-10-22T11:15:13.045546+00:00",
"previous_hash": "dd246554c406e84bee13e1dcbec84043ce33214e7cfaba8faa81d78f45211111"
},
"closing_transaction": null,
"created_at": "2023-10-22T11:15:13.045546+00:00",
"updated_at": "2023-10-22T11:15:13.192206+00:00",
"balance": {
"initial": 58000,
"balance": 232000,
"cash_sales": 174000,
"card_sales": 348000,
"discounts_sum": 18000,
"extra_charge_sum": null,
"cash_returns": 0,
"card_returns": 0,
"service_in": 0,
"service_out": 0,
"updated_at": "2023-10-22T15:45:23.471495+00:00"
},
"taxes": [
{
"id": "f4d70f63-5728-4160-bf5a-23c845811111",
"code": 8,
"label": "Без ПДВ",
"symbol": "З",
"rate": 0,
"extra_rate": null,
"included": true,
"created_at": "2023-09-27T07:57:34.983722+00:00",
"updated_at": null,
"no_vat": true,
"advanced_code": null,
"sales": 0,
"returns": 0,
"sales_turnover": 522000,
"returns_turnover": 0
}
],
"emergency_close": null,
"emergency_close_details": null,
"cash_register": {
"id": "c13876dd-e51e-433f-a61c-f2c426311111",
"fiscal_number": "TEST551151",
"active": true,
"created_at": "2022-07-26T19:54:09+00:00",
"updated_at": "2023-10-20T22:55:04+00:00",
"number": "1"
},
"cashier": {
"id": "04da40aa-e28e-42b7-8d51-6cb6ee811111",
"full_name": "Тестовий касир",
"nin": "000000000",
"key_id": "test_jrdulZ77cjg11111",
"signature_type": "TEST",
"permissions": {
"orders": true,
"add_discounts": true,
"editing_goods_sum": true,
"deferred_receipt": true,
"editing_good_price": true,
"can_add_manual_good": true,
"service_in": true,
"service_out": true,
"returns": true,
"sales": true,
"card_payment": true,
"cash_payment": true,
"other_payment": true,
"mixed_payment": true,
"branch_params": true,
"reports_history": true,
"additional_service_receipt": false,
"free_return": false
},
"created_at": "2022-06-01T14:23:04+00:00",
"updated_at": "2022-07-19T14:13:58+00:00",
"certificate_end": null,
"blocked": null
}
},
"control_number": null
}
"id" - унікальний ідентифікатор чека у форматі UUID
"type" - тип чека
"transaction" - інформація про транзакцію чека.
- "id" - унікальний ідентифікатор транзакції у форматі UUID
- "type" - тип транзакції
- "serial" - порядковий номер транзакції
- "status" - статус транзакції. Може приймати значення CREATED/PENDING/SIGNED/DELIVERED/DONE(або ERROR) (СТВОРЕНА/НА ПІДПИСАННІ/ПІДПИСАНА/ВІДПРАВЛЕНА/ВИКОНАНА(або ПОМИЛКА))
- "request_signed_at" - мітка часу підписання транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "request_received_at" - мітка часу отримання транзакції сервером ДПС у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Якщо запит ще не був доставлений у податкову, то дане значення буде null
- "response_status" - статус, отриманний від сервера ДПС у відповідь на запит. Успішний запит матиме статус OK
- "response_error_message" - текстовий опис помилки, при отриманні її від сервера ДПС у відповідь на запит.
- "response_id" - ідентифікатор відповіді на запит від сервера ДПС (фіскальний номер)
- "offline_id" - офлайн ідентифікатор відповіді на запит від сервера ДПС (фіскальний номер). Матиме значення null якщо транзакція була створена у онлайн режимі.
- "created_at" - мітка часу створення транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних транзакції у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "previous_hash" - хеш попередньої транзакції
"serial" - порядковий номер чека
"status" - статус чека
"goods" - блок даних з переліком товарів.
- "code" - код товару (обов'язковий параметр)
- "barcode" - штрих-код товару
- "name" - назва товару (обов'язковий параметр)
- "excise_barcodes" - цифрове позначення штихового коду акцизної марки, якщо їх >1
- "header" - хедер товару
- "footer" - футер товару
- "uktzed" - код уктзед
- "price" - ціна товару
- "good_id" - ідентифікатор товару у форматі UUID
- "sum" - сума у копійках
- "quantity" - кількість у тисячах. 1 шт = 1000
- "is_return" - true/false, флаг який помічає обраний товар як товар повернення
"taxes" - блок даних з інформацією про податкові ставки, які використовувались для товару в чеку
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "value" - розмір податку
- "extra_value" - розмір додаткового збору (наприклад, для акцизу)
"discounts" - блок даних про знижки по товару.
- "type" - тип знижки "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)
- "mode" - режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)
- "value" - розмір знижки
- "tax_code"/"tax_codes" - коди податкових ставок, які використовуються для товару і були вказані при створенні знижки
- "name" - назва знижки/надбавки
- "sum" - сума знижки/надбавки
"payments" - блок даних з інформацією про платежі
- "type" - тип платежу CASH/CASHLESS
- "pawnshop_is_return" - параметр, який визначає даний чек як чеки видачі коштів ломбарду. За замовчуванням для звичайних чеків, створених не для ломбардів, має бути null
- "value" - сума внесення/винесення у копійках. Для формування чеку службового винесення потрібно перед сумою вказати
- "label" - текстова мітка, яка буде розміщена на чеку
- "code" - номер оплати (тільки для безготівкових платежів)
- "commission" - комісія (тільки для безготівкових платежів)
- "card_mask" - маска карти (не більше 19 символів) (тільки для безготівкових платежів)
- "bank_name" - назва банку (тільки для безготівкових платежів)
- "auth_code" - код авторизації банківської операції (тільки для безготівкових платежів)
- "rrn" - Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)
- "payment_system" - платіжна система (тільки для безготівкових платежів)
- "owner_name" - ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)
- "terminal" - інформація про платіжний термінал (тільки для безготівкових платежів)
- "acquirer_and_seller" - ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)
- "receipt_no" - номер банківського чека (тільки для безготівкових платежів)
- "signature_required" - true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира
"total_sum" та "sum" - сума вартості товарів у чеку
"total_payment" - сума оплати за товари у чеку
"rest" та "total_rest" - сума здачі
"fiscal_code" - фіскальний номер чека. При створенні чека у онлайні чек отримує фіскальний код згодом, після обробки та передачі його у ДПС, яка у відповідь призначає чеку офлайн код
"fiscal_date" - фіскальна дата, з якою чек буде зареєстровано у ДПС. Чек отримає фіскальну дату після завершення обробки.
"delivered_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час доставки чека у ДПС.
"created_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час створення чека
"updated_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час останнього оновлення даних чека. Якщо чек тільки що створено або якщо інформація по ньому не оновлювалась, то дане значення буде null
"taxes" - блок даних про податки, які використовувались для всього чеку
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "value" - розмір податку
- "extra_value" - розмір додаткового збору (наприклад, для акцизу)
"discounts" - блок даних про знижки, які застосовувались до всього чеку.
- "type" - тип знижки "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)
- "mode" - режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)
- "value" - розмір знижки
- "tax_code"/"tax_codes" - коди податкових ставок, які використовуються для товару і були вказані при створенні знижки
- "name" - назва знижки/надбавки
- "sum" - сума знижки/надбавки
"order_id" - ідентифікатор замовлення у форматі UUID (використовується при роботі з API замовлень).
"header" - хедер чека.
"footer" - футер чека.
"barcode" - штрих-код чека.
"custom" - блок з даними кастомізації чека. Докладніше про параметри, які можуть відображатись в даному блоці можете дізнатись тут
"is_created_offline" - ознака режиму (онлайн/офлайн) у якому був створений чек. true - чек створений у офлайні, false - чек створений у онлайні.
"is_sent_dps" - ознака відправки чека у ДПС.
"sent_dps_at" - мітка часу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm, яка відмічає дату/час відправки чека у ДПС.
"tax_url" - посилання на чек у кабінеті ДПС.
"related_receipt_id" - id пов'язаного чека у форматі UUID. Цим параметром можна пов'язати між собою чек продажу та повернення, щоб завжди мати змогу дізнатися, на основі якого конкретно чека продажу ви робили повернення.
"technical_return" - параметр, який відповідає за мітку технічного повернення на чеку. Технічне повернення - це повернення чеку продажу у випадку, коли чек продажу сформований невірно і для коригування балансу виникає змога провести повернення.
"currency_exchange" - блок даних, який стосується операцій валютного обміну. Не є актуальним для звичайного чека.
"shift" - блок з даними про поточну зміну
- "id" - унікальний ідентифікатор зміни у форматі UUID
- "serial" - порядковий номер зміни
- "status" - статус зміни. Може мати значення CREATED/OPENED/CLOSING/CLOSED (СТВОРЕНА/ВІДКРИТА/ЗАКРИВАЄТЬСЯ/ЗАКРИТА)
- "z_report" - блок з інформацією по z-звіту касової зміни. Для відкритої зміни це значення завжди буде null
- "opened_at" - мітка часу відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "closed_at" - мітка часу закриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Для відкритої зміни завжди буде null
"initial_transaction" - блок з інформацією про першу транзакцію обраної зміни
- "id" - унікальний ідентифікатор транзакції у форматі UUID
- "type" - тип транзакції. Для першої транзакції зміни це значення завжди буде SHIFT_OPEN
- "serial" - порядковий номер транзакції
- "status" - статус транзакції. Може приймати значення CREATED/PENDING/SIGNED/DELIVERED/DONE(або ERROR) (СТВОРЕНА/НА ПІДПИСАННІ/ПІДПИСАНА/ВІДПРАВЛЕНА/ВИКОНАНА(або ПОМИЛКА))
- "request_signed_at" - мітка часу підписання запиту на відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "request_received_at" - мітка часу отримання запиту на відкриття зміни сервером ДПС у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. Якщо запит ще не був доставлений у податкову, то дане значення буде null
- "response_status" - статус, отриманний від сервера ДПС у відповідь на запит. Успішний запит матиме статус OK
- "response_error_message" - текстовий опис помилки, при отриманні її від сервера ДПС у відповідь на запит.
- "response_id" - ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер)
- "offline_id" - офлайн ідентифікатор відповіді на запит відкриття зміни від сервера ДПС (фіскальний номер). Матиме значення null якщо транзакція відкриття зміни була створена у онлайн режимі.
- "created_at" - мітка часу створення транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останнього оновлення даних транзакції відкриття зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "previous_hash" - хеш попередньої транзакції
"closing_transaction" - блок даних про останню транзакцію у зміні. Для відкритої зміни прийматиме значення null. Якщо зміна закрита, то даний блок міститиме набір даних стосовно останньої транзакції у зміні аналогічний до "initial_transaction"
"created_at" - мітка часу створення зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - мітка часу останнього оновлення даних зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"balance" - блок даних по грошовому балансу обраної зміни. Всі значення передаються у копійках.
- "initial" - початковий баланс готівкових коштів
- "balance" - поточний баланс готівкових коштів
- "cash_sales" - сума готівкових продажів
- "card_sales" - сума безготівкових продажів
- "cash_returns" - сума готівкових повернень
- "card_returns" - сума безготівкових повернень
- "service_in" - сума службових внесень готівкових
- "service_out" - сума службових вилучень готівкових коштів
- "updated_at" - мітка часу останнього оновлення даних балансу зміни у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"taxes" - блок даних з інформацією про податкові ставки, які діють у рамках обраної зміни. Для кожної податкової ставки набір даних складається з наступних пунктів:
- "id" - унікальний ідентифікатор податкової ставки у форматі UUID
- "code" - цифровий код податкової ставки
- "label" - назва податкової ставки
- "symbol" - літерний код податкової ставки
- "rate" - розмір податкової ставки у відсотках
- "extra_rate" - розмір додаткового збору у відсотках
- "included" - тип податку вкладений/накладений (true/false). При використанні вкладеного податку сума податку міститься (вкладена) у загальну суму товару. Накладений податок - сума товару не містить податку, податок рахується окремо. Накладений податок використовується вкрай рідко на практиці, тому через веб-інтерфейс сайту Checkbox заблокована можливість створення податкових ставок накладеного податку.
- "created_at" - мітка часу створення податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - мітка часу останньої зміни параметрів податкової ставки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm. На даний момент при використанны методу /api/v1/cashier/shift, значення "updated_at" завжди повертає null
- "sales" - сума податку усіх чеків продажу у копійках
- "returns" - сума податку усіх чеків повернення у копійках
- "sales_turnover" - сума продажів з цією податковою ставкою (оборот) у копійках
- "returns_turnover" - сума повернень з цією податковою ставкою (оборот) у копійках
"cash_register" - блок даних з інформацією про касу, на якій було створено чек
- "id": - унікальний ідентифікатор каси у форматі UUID
- "fiscal_number" - фіскальний номер каси
- "active" - статус каси АКТИВНА/НЕАКТИВНА (true/false)
- "created_at" - дата реєстрації каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "updated_at" - дата останньої зміни даних обраної каси у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"cashier" - блок даних з інформацією про касира, який створив чек
- "id" - унікальний ідентифікатор касира у форматі uuid;
- "full_name" - ПІБ касира, вказане користувачем при його реєстрації;
- "nin" - ідентифікаційний код касира у ДПС;
- "key_id" - ідентификатор ключа (печатки) ЕЦП касира;
- "signature_type"- тип агента підпису чеків, який використовується касиром. Наразі актуальними є типи CLOUD_SIGNATURE_3 для ключів (печаток), підписуючих чеки на захищеному хмарному сховищі та AGENT, для ключів (печаток), які виконують підписання чеків локально, за допомогою програми Чекбокс підпис або плагіну підпису в браузері клієнтського ПК;
- "permissions" - перелік додаткових дозволів для обраного касира. У прикладі вище - "orders": true, тобто, касиру дозволено користуватися функціоналом API у режимі роботи з замовленнями. Опис цього функціоналу ви зможете знайти у відповідному розділі даної документації;
- "created_at" - дата реєстрації касира;
- "updated_at" - дата останнього внесення змін у обліковий запис даного касира;
- "certificate_end" - дата завершення строку дії електронного ключа (печатки) касира;
- "blocked" - інформація про чинність сертифікату ключа (печатки) касира. Якщо на агенті підпису активна перевірка сертифікату за OSCP протоколом, то у випадку, коли користувач скасовує електронний ключ (печатку), в цьому полі буде відповідне повідомлення "blocked": "Сертифікат не чинний (при перевірці за протоколом OCSP)". Якщо ж інформації про блокування ключа (печатки) сервер не має, то за замовчуванням у відповіді сервера буде значення "blocked": null.
"control_number" - контрольне число, яке отримує офлайн чек після обробки сервером. Чек, створений у онлайн режимі згідно діючого законодавства не має містити такого реквізиту, а отже значення буде null для онлайн чеку.
¶ Виконання не фіскального замовлення
Використовуйте цей мотед, щоб перевести статус замовлення з PENDING в SUCCESS. Метод працює тільки з замовленнями, які не потрібно фіскалізувати (якщо такі замовлення були фіскалізовані іншим чином). У відповідь буде відправлено замовлення на адресу, встановлену для отримання зворотнього виклику (вебхук).
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'PATCH' \ 'https://api.checkbox.ua/api/v1/orders/close?order_id=63009741-0117-4b7a-b1a2-3baed6711111' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token'
¶ Response body
{
"id": "63009741-0117-4b7a-b1a2-3baed6711111",
"order_id": "Доставка меду",
"status": "SUCCESS",
"custom_status": null,
"is_paid": true,
"payment_method": "CASHLESS_ON_DELIVERY",
"receipt_draft": {
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": [
"[email protected]"
],
"phone": null
},
"type": "SELL"
},
"delivery_details": {
"address": {
"address_type": "flat",
"street": "Тестова 41а",
"entrance": "4",
"floor": "4",
"apartment_number": "32",
"elevator": false,
"intercom": true
},
"box_id": [
1258
],
"client_name": "Шпак Антон Семенович",
"client_phone_number": "+380962111111",
"delivery_time": "2023-10-19T07:11:10+00:00",
"client_comment": "Ліфт не працює",
"thermal_dependence": true
},
"created_at": "2023-10-22T16:10:11.018321+00:00",
"updated_at": "2023-10-22T16:10:31.924829+00:00",
"not_fiscalize": true,
"stock_code": null
}
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"status" - статус замовлення, можливі статуси замовлень: PENDING, SAVING, SUCCESS, CANCELLED.
"custom_status" - користувацький статус замовлення, можливі статуси замовлень: NEW, IN_WORK, APPROVED, TRANSFERRED_TO_WMS, PREPARING, DELIVERING, DELIVERED, DONE, CANCELED, TEST
"is_paid" - true/false, ознака попередньої оплати замовлення
"payment_method" - спосіб оплати замовлення, можливі способи оплати: CARD_AFTER_ASSEMBLING(картою після збірки замовлення), CASH_ON_DELIVERY(готівкою при отриманні замовлення), CASHLESS_ON_DELIVERY(карткою при отриманні замовлення)
"receipt_draft" - інформація про чек (payload створення фіскального чека)
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)
"delivery_details" - масив данних із інформацією про адресу доставки:
- "address_type" - тип адреси, можливі значення:
flat,house,office(квартира, дім, офіс) - "street" - вулиця та номер будинку
- "entrance" - номер під'їзду
- "floor" - номер поверху
- "apartment_number" - номер квартири
- "elevator" - true/false, наявність ліфту
- "intercom" - true/false, наявніть домофону
- "box_id" - масив данних із інформацією про номер пакування/ящика
- "client_name" - ПІБ покупця, який має отримати доставлене замовлення
- "client_phone_number" - номер телефону покупця
- "delivery_time" - орієнтовна дата доставки замовлення
- "client_comment" - коментар для кур'єра про замовлення
- "thermal_dependence" - true/false, ознака температурної чутливості замовлення
"created_at" - дата створення замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останньої зміни замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"not_fiscalize" - true/false, ознака наявності не фіскального товару
"stock_code" - true/false - ?
¶ Відміна замовлення
Використовуйте цей метод, щоб перевести статус замовлення з PENDING в CANCELLED.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
curl -X 'PATCH' \ 'https://api.checkbox.ua/api/v1/orders/20bd9f37-0794-4ef1-8b25-47fe7f611111' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token'
¶ Responce body
{
"id": "20bd9f37-0794-4ef1-8b25-47fe7f611111",
"order_id": "Доставка меду",
"status": "CANCELLED",
"custom_status": null,
"is_paid": true,
"payment_method": "CASHLESS_ON_DELIVERY",
"receipt_draft": {
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": [
"[email protected]"
],
"phone": null
},
"type": "SELL"
},
"delivery_details": {
"address": {
"address_type": "flat",
"street": "Тестова 41а",
"entrance": "4",
"floor": "4",
"apartment_number": "32",
"elevator": false,
"intercom": true
},
"box_id": [
1258
],
"client_name": "Шпак Антон Семенович",
"client_phone_number": "+380962111111",
"delivery_time": "2023-10-19T07:11:10+00:00",
"client_comment": "Ліфт не працює",
"thermal_dependence": true
},
"created_at": "2023-10-22T16:02:01.163717+00:00",
"updated_at": "2023-10-22T16:02:56.949105+00:00",
"not_fiscalize": false,
"stock_code": null
}
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"status" - статус замовлення, можливі статуси замовлень: PENDING, SAVING, SUCCESS, CANCELLED.
"custom_status" - користувацький статус замовлення, можливі статуси замовлень: NEW, IN_WORK, APPROVED, TRANSFERRED_TO_WMS, PREPARING, DELIVERING, DELIVERED, DONE, CANCELED, TEST
"is_paid" - true/false, ознака попередньої оплати замовлення
"payment_method" - спосіб оплати замовлення, можливі способи оплати: CARD_AFTER_ASSEMBLING(картою після збірки замовлення), CASH_ON_DELIVERY(готівкою при отриманні замовлення), CASHLESS_ON_DELIVERY(карткою при отриманні замовлення)
"receipt_draft" - інформація про чек (payload створення фіскального чека)
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)
"delivery_details" - масив данних із інформацією про адресу доставки:
- "address_type" - тип адреси, можливі значення:
flat,house,office(квартира, дім, офіс) - "street" - вулиця та номер будинку
- "entrance" - номер під'їзду
- "floor" - номер поверху
- "apartment_number" - номер квартири
- "elevator" - true/false, наявність ліфту
- "intercom" - true/false, наявніть домофону
- "box_id" - масив данних із інформацією про номер пакування/ящика
- "client_name" - ПІБ покупця, який має отримати доставлене замовлення
- "client_phone_number" - номер телефону покупця
- "delivery_time" - орієнтовна дата доставки замовлення
- "client_comment" - коментар для кур'єра про замовлення
- "thermal_dependence" - true/false, ознака температурної чутливості замовлення
"created_at" - дата створення замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата останньої зміни замовлення у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"not_fiscalize" - true/false, ознака наявності не фіскального товару
"stock_code" - true/false - ?
¶ Встановлення та видалення інтеграції
Даним методом встановлюється URL адреса куди при редагуванні замовлення буде надіслано POST запити з відповідною інформацією. Налаштування зберігаються для кожного касира окремо.
Указана в даному запиті адреса повинна приймати POST запити із указаною в документації схемою та повертати статус-код 200, у разі якщо статус-код буде >= 400 або час очікування відповіді більше 5 секунд у відповідь буде надіслана помилка.
Під час встановлення налаштувань сервером CheckBox генерується секретний ключ та повертається у відповіді на даний метод, за допомогою цього ключа можна перевірити чи дійсно запит виконується серверами CheckBox. Під час виконання виклику вебхуків тіло запиту хешується за допомогою алгоритму:
encodeBase64(
HmacSHA256(
getBytesUTF-8(
request_body
)
secret_key
)
)
· encodeBase64 - функція перетворення бінарних даних в Base64 формат
· HmacSHA256 - функция створення хешу підпису даних
· getBytesUTF-8 - функция перетворення рядка в бінарне представлення (в кодуванні UTF-8)
· request_body - тіло запиту
з використанням ключа та записується до заголовку x-request-signature, таким чином на стороні де отримується запит можна перевірити дійсність даних за тим же алгоритмом.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"url": "<URL-адреса, куди будуть відправлятись POST запити>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/orders/integration' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "url": "https://webhook.site/b1992f12-6536-4c3b-a74d-f2fb5f511111"}'
¶ Response body
{
"url": "https://webhook.site/b1992f12-6536-4c3b-a74d-f2fb5f511111",
"last_error_date": null,
"last_error_message": null,
"created_at": "2023-10-22T16:16:03.658314+00:00",
"updated_at": null,
"key": "tnX7jL6CZDdiNkVGuH0KukAl_ND11111"
}
"url" - URL-адреса, куди будуть відправлятись POST запити
"last_error_date" - дата та час останньої помилки у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"last_error_message" - опис останньої помилки
"created_at" - дата та час встановлення вебхука у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"updated_at" - дата та час останнього оновлення вебхука у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"key" - секретний ключ інтеграції, за допомогою якого можна перевірити, чи дійсно POST запити виконуються серверами checkbox.
Використовуйте цей метод для видалення веб-хука інтеграції замовлень.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
Тіло запиту у даному випадку має бути порожнім.
¶ Response body
{
"ok": true
}
"ok" - true/false, результат успіху операції.
¶
¶ Редагування замовлення на стороні інтеграції
Метод для редагування вже існуючого замовлення на стороні інтеграції. У відповідь буде надіслано веб-хук на вказану адресу після успішного виконання операції.
¶ Request headers
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
Authorization: <токен авторизації>
Content-Type: application/json
¶ Request body
{
"cashier_name": "<ПІБ касира, вказане користувачем при його реєстрації>",
"departament": "<назва відділу>",
"goods": [
{
"good": {
"code": "<код товару>",
"name": "<назва товару>",
"barcode": "<штрих-код товару>",
"excise_barcode": "<ифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках за одиницю товару>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару, попередньо доданих до номенклатури товарів checkbox>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"total_sum": <сума вартості товару>
},
{
"good":{
<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>
}
}
],
"additional_goods": [
{
"good": {
"code": "<код товару>",
"name": "<назва товару>",
"barcode": "<штрих-код товару>",
"excise_barcode": "<ифрове позначення штрих-коду акцизної марки>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<хедер товару 1>",
"footer": "<Футер товару 1>",
"price": <ціна у копійках за одиницю товару>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID товару, попередньо доданих до номенклатури товарів checkbox>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"total_sum": <сума вартості товару>
},
{
"good":{
<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>
}
}
],
"discounts":
[
{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА)>",
"value": <значення знижки > 0>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}
],
"payments":
[
{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"pawnshop_is_return": <true/false Ознака того, що даний чек є видатковим чеком ломбарду. Для звичайного чека параметр вказувати не потрібно>,
"provider_type": <у разі застосування технології TAPXPHONE, дане поле буде заповнено автоматично. Можливі значення: `TAPXPHONE`, `POSCONTROL`, `TERMINAL`>,
"value": <сума оплати у копійках, < 100000000000>,
"label": "<текстова назва форми оплати, [1, 128] characters>",
"code": <номер оплати (тільки для безготівкових платежів), (0, 10)>,
"commission": <комісія (тільки для безготівкових платежів)>,
"card_mask": "<маска карти (не більше 19 символів) (тільки для безготівкових платежів)>",
"bank_name": "<назва банку (тільки для безготівкових платежів)>",
"auth_code": "<код авторизації банківської операції (тільки для безготівкових платежів)>",
"rrn": "<Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)>",
"payment_system": "<платіжна система (тільки для безготівкових платежів)>",
"owner_name": "<ім'я власника електронного платіжного засобу (тільки для безготівкових платежів)>",
"terminal": "<інформація про платіжний термінал (тільки для безготівкових платежів)>",
"acquirer_and_seller": "<ідентифікатор еквайра та торгівця, або інші реквізити, що дають змогу їх ідентифікувати (тільки для безготівкових платежів)>",
"receipt_no": "<номер банківського чека (тільки для безготівкових платежів)>",
"tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"signature_required": <true/false флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
},
{
<блок з даними по додатковій формі оплати за шаблоном, який описаний вище (якщо в чеку декілька форм оплати)>
}
],
"bonuses":
[
{
"bonus_card": <інформація про бонусну картку покупця, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"value": <інформація про накопичені бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"additional_info": <додаткова інформація про бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>
}
],
"header": "<службова інформація, вказана в хедері чека>",
"footer": "<службова інформація, вказана у футері чека>",
"barcode": "<штрих-код чека>",
"delivery": {{
"email": "<e-mail клієнта для відправки копії чека>",
"emails":
["<e-mail клієнта для відправки копії чека 1>","<e-mail клієнта для відправки копії чека 2>"],
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"type": "<тип чека, можливі типи: `SELL`, `RETURN`, `SERVICE_IN`, `SERVICE_OUT`, `SERVICE_CURRENCY`, `CURRENCY_EXCHANGE`, PAWNSHOP`, `CASH_WITHDRAWAL` (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)>",
"id": "<унікальний ідентифікатор замовлення у форматі UUID>",
"order_id": "<назва замовлення в мобільному додатку>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/orders/integration/edit-order' \ -H 'accept: application/json' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "goods":[ { "good":{ "code":"1", "name":"Гречаний мед (400г)", "price":16000, "tax":[ 8 ] }, "quantity":2000, "is_return":false }, { "good":{ "code":"2", "name":"Липовий мед (655г)", "price":28000, "tax":[ 8 ] }, "quantity":1000, "is_return":false } ], "discounts":[ { "type":"DISCOUNT", "mode":"VALUE", "value":2000, "name":"Використані бонуси" } ], "payments":[ { "type":"CASHLESS", "label":"Картка", "value":58000 } ], "type":"SELL", "id":"dd99a639-2454-4e33-941c-717f5cb11111", "order_id":"Доставка меду 1"}'
¶ Response body
{
"cashier_name": null,
"departament": null,
"goods": [
{
"good": {
"code": "1",
"name": "Гречаний мед (400г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 16000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 2000,
"is_return": false,
"discounts": [],
"total_sum": null
},
{
"good": {
"code": "2",
"name": "Липовий мед (655г)",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 28000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false,
"discounts": [],
"total_sum": null
}
],
"additional_goods": [],
"discounts": [
{
"type": "DISCOUNT",
"mode": "VALUE",
"value": 2000,
"tax_code": null,
"tax_codes": [],
"name": "Використані бонуси",
"privilege": null
}
],
"payments": [
{
"type": "CASHLESS",
"pawnshop_is_return": null,
"provider_type": null,
"code": null,
"value": 58000,
"commission": null,
"label": "Картка",
"card_mask": null,
"bank_name": null,
"auth_code": null,
"rrn": null,
"payment_system": null,
"owner_name": null,
"terminal": null,
"acquiring": null,
"acquirer_and_seller": null,
"receipt_no": null,
"signature_required": null,
"tapxphone_terminal": null
}
],
"bonuses": [],
"header": null,
"footer": null,
"barcode": null,
"delivery": {
"email": null,
"emails": null,
"phone": null
},
"type": "SELL",
"id": "dd99a639-2454-4e33-941c-717f5cb11111",
"order_id": "Доставка меду 1"
}
"id" - унікальний ідентифікатор замовлення у форматі UUID
"order_id" - назва замовлення в мобільному додатку
"cashier_name" - ПІБ касира, вказане користувачем при його реєстрації
"departament" - назва відділу
"goods" - масив данних із інформацією про товари
- "code" - код товару
- "name" - назва товару
- "barcode" - штрих-код товару
- "excise_barcode" - цифрове позначення штрих-коду акцизної марки
- "excise_barcodes" - масив даних із цифровим позначенням штрих-коду акцизної марки
- "header" - хедер товару 1
- "footer" - Футер товару 1
- "price" - ціна у копійках за одиницю товару
- "tax" - масив данних із цифровим або літерним кодом ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому
- "uktzed" - код УКТЗЕД
- "good_id" - UUID товару, попередньо доданих до номенклатури товарів checkbox
- "quantity" - кількість у тисячах, 1 шт = 1000
- "is_return" - флаг true/false, що визначає, чи це чек повернення
"additional_goods" - масив данних іх інформаціює про не фіскальні товари (які оплачені іншим чином, але потребують доставки в цьому замовленні)
"discounts" - масив данних із інформацією про знижку/надбаву для товара/на весь чек
- "type" - тип знижки -
DISCOUNT,EXTRA_CHARGE(ЗНИЖКА/НАДБАВКА) - "mode" - режим знижки
VALUE,PERCENT(АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення) - "value" - значення знижки
- "tax_code" - код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку
- "tax_codes" - масив данних із кодами податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку
- "name" - назва знижки або надбавки
- "privilege" - номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки
"total_sum" - сума вартості товару
"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 флаг, який визначає, чи має бути доступною графа для підпису власника картки та касира>
- "tapxphone_terminal": <унікальний ідентифікатор інтеграції технології TAPXPHONE у форм UUID>
"bonuses" - масив данних із інформацією про бонусну программу (не друкується в чеку)
- "bonus_card" - інформація про бонусну картку покупця
- "value" - інформація про накопичені бонуси
- "additional_info" - додаткова інформація про бонуси
"header" - службова інформація, вказана в хедері чека
"footer" - службова інформація, вказана у футері чека
"barcode" - штрих-код чека
"delivery" - блок даних з інформацією про доставку чека
- "email" - e-mail клієнта для відправки копії чека
- "phone" - номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
"type" - тип чека, можливі типи: SELL, RETURN, SERVICE_IN, SERVICE_OUT, SERVICE_CURRENCY, CURRENCY_EXCHANGE, PAWNSHOP, CASH_WITHDRAWAL (ПРОДАЖ, ПОВЕРНЕННЯ, СЛУЖБОВЕ ВНЕСЕННЯ, СЛУЖБОВЕ ВИНЕСЕННЯ, ПРОДАЖ ВАЛЮТИ, ОБМІН ВАЛЮТИ, ЧЕК ЗАСТАВИ, ЧЕК ВИДАЧІ КОШТІВ - за замовчуванням, чек ПРОДАЖУ)