Експрес-накладні в системі checkbox - це проект фіскального чека, який повʼязаний із накладною Нової Пошти та буде фіскалізовано автоматично після отримання покупцем посилки.
❗️ Важливо: щоб опція створення проектів фіскальних чеків стала доступною, спершу активуйте її у вашому особистому кабінеті Checkbox за інструкцією.
Використовуйте цей метод для створення проекта фіскального чека та експрес-накладних в системі checkbox.
Перед початком необхідно виконати певні налаштування в особистому кабінеті checkbox.
Додавання проекту експрес-накладної дозволено у закритій касовій зміні.
cancelled (скасовано). В такому випадку рекомендуємо видалити її із системи checkbox.returned (повернуто)accept: application/json
Authorization: <токен авторизації>
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Content-Type: application/json
{
"employee":"<uuid касира, який буде відкривати зміну для створення чека>",
"cashRegister":"<uuid каси, яка буде відкрита для створення чека>",
"receipt_body":{
"payments":[
{
"value":"<сума оплати у копійках - має відповідти сумі експрес-накладної НП>",
"ettn":"<номер накладної Нової Пошти>",
"type":"<""ETTN"" (завжди має значення ETTN)>",
"label":"<текстова назва форми оплати (завжди має значення ""Експрес-накладна"")>"
}
],
"footer":"<футер чека>",
"delivery":{
"email":"<e-mail клієнта для відправки копії чека>",
"phone":"<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
}
},
"goods":[
{
"good":{
"code":"<Код товару>",
"name":"<Назва товару>",
"barcode":"<Штрих-код товару>",
"excise_barcodes":[
"<цифрове позначення штрих-коду акцизної марки 1>",
"<цифрове позначення штрих-коду акцизної марки 2>"
],
"header":"<Хедер товару 1>",
"footer":"<Футер товару 1>",
"price":"<ціна у копійках>",
"tax":[
"<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>"
],
"uktzed":"<код УКТЗЕД>"
},
"good_id":"<UUID v4 товару (якщо ви користуєтесь залишками на сайті checkbox)>",
"quantity":"<кількість у тисячах", 1 шт = 1000>,
"is_return":"<флаг true/false, що визначає, чи це чек повернення>"
},
{
"good":{
"<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>"
}
}
]
}
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/np/ettn' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "employee":"7152306f-d2a2-4dd2-a9c4-037df6811111", "cashRegister":"fcf13176-f972-4f5b-bae0-54abf9211111", "receipt_body":{ "goods":[ { "good":{ "code":"22", "name":"Документи", "price":20000, "tax":[ 8 ] }, "quantity":1000, "is_return":false } ], "payments":[ { "type":"ETTN", "label":"Експрес-накладна", "value":20000, "ettn":"20450963211111" } ], "footer":"<футер чека>" }}'
{
"ettnNumber": "20450963211111",
"description": "Документи",
"recipientPhone": "380500511111",
"receiptBody": {
"payments": [
{
"value": 20000,
"type": "CARD",
"label": "Безготівкова"
}
],
"rounding": true,
"footer": "<футер чека>",
"delivery": [],
"goods": [
{
"good": {
"code": "22",
"name": "Документи",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 20000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false
}
],
"id": "ca6d9fe9-f3f0-49b9-858d-bda023111111"
},
"receiptId": "ca6d9fe9-f3f0-49b9-858d-bda023111111",
"receiptRelationId": null,
"returnReceiptId": null,
"totalSum": 20000,
"employee": {
"dateCreated": "2022-09-09T14:35:44+03:00",
"id": "7152306f-d2a2-4dd2-a9c4-037df6811111"
},
"cashRegister": {
"id": "06fbc9f0-0bed-487b-b0be-598278c11111",
"dateCreated": "2024-05-30T15:18:30+03:00"
},
"status": "created",
"lastCheckDate": "2024-07-25T15:25:47+03:00",
"rawError": null,
"hasWebhook": false,
"deliveryPhone": null,
"deliveryEmail": null,
"id": "b8c6558e-760b-43c2-af2a-6803c3211111",
"dateCreated": "2024-07-25T15:25:47+03:00"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/np/ettn' \ -H 'accept: application/json' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "employee":"7152306f-d2a2-4dd2-a9c4-037df6811111", "cashRegister":"fcf13176-f972-4f5b-bae0-54abf9211111", "receipt_body":{ "goods":[ { "good":{ "code":"22", "name":"Документи", "price":20000, "tax":[ 8 ] }, "quantity":1000, "is_return":false } ], "payments":[ { "type":"ETTN", "label":"Експрес-накладна", "value":20000, "ettn":"20450963211111" } ], "footer":"<футер чека>" }}'
"ettnNumber" - номер експрес-накладної Нової Пошти
"description" - опис відправлення експрес-накладної Нової Пошти
"recipientPhone" - номер телефону отримувача експрес-накладної Нової Пошти
"receiptBody" - блок даних з інформацією про чек:
"payments" - блок даних з інформацією про платежі:
"CARD")"rounding" - активація режиму заокруглення (завжди true)
"footer" - футер чека
"delivery" - блок даних з інформацією про доставку чека
"goods" - масив даних з переліком товарів
"id" - UUID v4 створеного чека після отримання покупцем експрес-накладної
"receiptId" - UUID v4 створеного чека після отримання покупцем експрес-накладної
"receiptRelationId" -
"returnReceiptId" -
"totalSum" - сума оплати у копійках
"employee" - блок даних з інформацією про касира:
- "dateCreated" - мітка часу створення касира у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
- "id" - унікальний ідентифікатор касира у форматі UUID v4
"cashRegister" - блок даних з інформацією про касу:
- "id" - унікальний ідентифікатор каси у форматі UUID v4
- "dateCreated" - мітка часу створення касир у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"status" - статус експрес-накладної і системі checkbox. Можливі статуси: created - створено, done - отримано та фіскалізовано, receipt_error - помилка видачі фіскального чека, cancelled - покупець відмовився від отримання експрес-накладної, returned - чек повернуто.
"lastCheckDate" - мітка часу останньої перевірки експрес-накладної у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
"rawError" - опис помилки (при статусі експрес-накладної receipt_error)
"hasWebhook" - false,
"deliveryPhone" - номер телефону отримувача фіскального чек після його створення
"deliveryEmail" - e-mail отримувача фіскального чек після його створення
"id" - order_id унікальний ідентифікатор експрес-накладної в системі checkbox у форматі UUID v4
"dateCreated" - мітка часу створення експрес-накладної в системі checkbox у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
Використовуйте цей метод для додавання до експрес-накладних способу доставки фіскального чека покупцеві.
accept: application/json
Authorization: <токен авторизації>
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
order_id: <унікальний ідентифікатор експрес-накладної в системі checkbox (обов`язково)>
Content-Type: application/json
{
"delivery_phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..",
"delivery_email": "<e-mail клієнта для відправки копії чека>"
}
curl -X 'PUT' \ 'https://api.checkbox.ua/api/v1/np/ettn/b8c6558e-760b-43c2-af2a-6803c3211111' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "delivery_phone": "380500511111", "delivery_email": "[email protected]"}'
{
"ettnNumber": "20450963211111",
"description": "Документи",
"recipientPhone": "380500511111",
"receiptBody": {
"payments": [
{
"value": 20000,
"type": "CARD",
"label": "Безготівкова"
}
],
"rounding": true,
"footer": "<футер чека>",
"delivery": {
"email": "[email protected]"
},
"goods": [
{
"good": {
"code": "22",
"name": "Документи",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 20000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false
}
],
"id": "ca6d9fe9-f3f0-49b9-858d-bda023111111"
},
"receiptId": "ca6d9fe9-f3f0-49b9-858d-bda023111111",
"receiptRelationId": null,
"returnReceiptId": null,
"totalSum": 20000,
"employee": {
"dateCreated": "2022-09-09T14:35:44+03:00",
"id": "7152306f-d2a2-4dd2-a9c4-037df6811111"
},
"cashRegister": {
"id": "06fbc9f0-0bed-487b-b0be-598278c11111",
"dateCreated": "2024-05-30T15:18:30+03:00"
},
"status": "created",
"lastCheckDate": "2024-07-25T15:59:47+03:00",
"rawError": null,
"hasWebhook": false,
"deliveryPhone": null,
"deliveryEmail": "[email protected]",
"id": "b8c6558e-760b-43c2-af2a-6803c3211111",
"dateCreated": "2024-07-25T15:25:47+03:00"
}
Опис параметрів співпадає із описом параметрів створення експрес-накладної.
Використовуйте цей метод для видалення експрес-накладної та проеку фіскального чека із системи checkbox. При цьому ЕТТН має бути у статусі 'скасовано' (cancelled) або 'створено' (created).
accept: application/json
Authorization: <токен авторизації>
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
order_id: <унікальний ідентифікатор експрес-накладної в системі checkbox (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'DELETE' \ 'https://api.checkbox.ua/api/v1/np/ettn/b8c6558e-760b-43c2-af2a-6803c3211111' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token'
""
"" - у разі успішного видалення експрес-накладної в системі checkbox.
Використовуйте цей метод для отримання деталей експрес-накладної в системі checkbox.
accept: application/json
Authorization: <токен авторизації>
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
order_id: <унікальний ідентифікатор експрес-накладної в системі checkbox (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/np/ettn/b8c6558e-760b-43c2-af2a-6803c3211111' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token'
{
"ettnNumber": "20450963211111",
"description": "Документи",
"recipientPhone": "380500511111",
"receiptBody": {
"payments": [
{
"value": 20000,
"type": "CARD",
"label": "Безготівкова"
}
],
"rounding": true,
"footer": "<футер чека>",
"delivery": [],
"goods": [
{
"good": {
"code": "22",
"name": "Документи",
"barcode": null,
"excise_barcode": null,
"excise_barcodes": null,
"header": null,
"footer": null,
"price": 20000,
"tax": [
8
],
"uktzed": null
},
"good_id": null,
"quantity": 1000,
"is_return": false
}
],
"id": "ca6d9fe9-f3f0-49b9-858d-bda023111111"
},
"receiptId": "ca6d9fe9-f3f0-49b9-858d-bda023111111",
"receiptRelationId": null,
"returnReceiptId": null,
"totalSum": 20000,
"employee": {
"dateCreated": "2022-09-09T14:35:44+03:00",
"id": "7152306f-d2a2-4dd2-a9c4-037df6811111"
},
"cashRegister": {
"id": "06fbc9f0-0bed-487b-b0be-598278c11111",
"dateCreated": "2024-05-30T15:18:30+03:00"
},
"status": "created",
"lastCheckDate": "2024-07-25T15:59:47+03:00",
"rawError": null,
"hasWebhook": false,
"deliveryPhone": null,
"deliveryEmail": null,
"id": "b8c6558e-760b-43c2-af2a-6803c3211111",
"dateCreated": "2024-07-25T15:25:47+03:00"
}
Опис параметрів співпадає із описом параметрів створення експрес-накладної.
Використовуйте цей метод для отримання списку переліку експрес-накладних в системі checkbox. Параметри пошуку доступні за посиланням вище.
accept: application/json
Authorization: <токен авторизації>
X-Client-Name: <назва інтеграції (обов`язково)>
X-Client-Version: <версія інтеграції (обов`язково)>
X-License-Key: <ключ ліцензії каси (обов`язково)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/np/ettn' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: 60ba422ff0d6421294311111' \ -H 'Authorization: Bearer token'
[
{
"ettnNumber": "20450963211111",
"description": "Документи",
"recipientPhone": "380500511111",
"receiptId": "ca6d9fe9-f3f0-49b9-858d-bda023111111",
"receiptRelationId": null,
"returnReceiptId": null,
"totalSum": 20000,
"employee": {
"login": "test_fyvw11111",
"dateCreated": "2022-09-09T14:35:44+03:00",
"id": "7152306f-d2a2-4dd2-a9c4-037df6811111"
},
"cashRegister": {
"fiscalNumber": "4000811111",
"id": "06fbc9f0-0bed-487b-b0be-598278c11111",
"dateCreated": "2024-05-30T15:18:30+03:00"
},
"status": "created",
"lastCheckDate": "2024-07-25T15:59:47+03:00",
"deliveryPhone": null,
"deliveryEmail": null,
"id": "b8c6558e-760b-43c2-af2a-6803c3211111",
"dateCreated": "2024-07-25T15:25:47+03:00"
}
]
Опис параметрів співпадає із описом параметрів створення експрес-накладної без деталей фіскального чека.