Експрес-накладні в системі checkbox - це проект фіскального чека, який повʼязаний із накладною Нової Пошти та буде фіскалізовано автоматично після отримання покупцем посилки.
❗️ Важливо: щоб опція створення проектів експрес-накладних стала доступною, спершу активуйте її у вашому особистому кабінеті checkbox за інструкцією.
❗️ Увага: дані методи API 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"
}
]
Опис параметрів співпадає із описом параметрів створення експрес-накладної без деталей фіскального чека.