Реалізація / Повернення
Запит
URI: /api/v2/check/sale?api_token={api_token}
Метод дозволяє зробити реалізацію або повернення.
Запит виконується методом POST з тілом запиту у JSON форматі.
⚠️ Запит повинен містити заголовки Accept: application/json та Content-Type: application/json
інформація
При оплаті готівкою потрібно виконувати округлення до 10 копійок згідно чинного законодавства.
Сума, що закінчується від 1 до 4 копійок, округлюється в бік зменшення до найближчої суми, яка закінчується на 0 копійок.
Сума, що закінчується від 5 до 9 копійок, округлюється в бік збільшення до найближчої суми, яка закінчується на 0 копійок.
В полі round_sum вказується різниця в копійках між округленим і не округленим значенням (зі знаком "-"(знижка) або "+"(надбавка) відповідно).
Якщо виконуєте округлення, в масиві payments повинні бути вже округлені значення та перераховане поле total_sum. Округленню підлягає лише форма оплати готівкою.
Приклади ПДВ
ПДВ А 20% "letters": "A" "tax_prc": 20
ПДВ Б 0% "letters": "Б" "tax_prc": 0
БЕЗ ПДВ "letters": null "tax_prc": null
БЕЗ ПДВ (Без ПДВ з літерним відображенням) "letters": Н "tax_prc": 0 До кожної позиції товару буде додано ПДВ, який у податках чека буде прописаний як "Без ПДВ Н"
Звільнений від оподаткування "letters": "-Н" "tax_prc": 0
Параметри запиту
| Ім'я | Тип | Обов'язковий | Опис |
|---|---|---|---|
| api_token | string | Так | Токен авторизації, згенерований в особистому кабінеті |
| num_fiscal | integer | Так | Фіскальний номер каси |
| action_type | string | Так | Тип дії: Z_SALE — реалізація RETURN — повернення |
| local_number | integer | Так | Локальний номер операції, який клієнт передає з кожним чеком |
| return_number | integer | Ні | Номер чека, за яким іде повернення (номер, який передано в local_number під час продажу). Використовується якщо action_type = RETURN |
| return_num_fiscal | integer | Ні | Фіскальний номер повернення. У разі, якщо повернення проводиться іншою фіскальною касою, то вказати фіскальний номер каси, за яким проводилась операція. Використовується якщо action_type = RETURN |
| total_sum | float | Так | Загальна сума чека |
| round_sum | float | Ні | Сума округлення |
| products | list[object] | Так | Містить список товарів для реалізації / повернення |
| products.letters | string | Ні | Літера податку (А, Б, В, Г, Д, Е, С, Н, -Н, <пусто> або NULL) |
| products.tax_prc | string | Ні | Відсоток податку |
| products.excise_prc | string | Ні | Відсоток акцизного податку Для акцизних товарів краще використовувати окрему літеру та % податку. Наприклад: Г - 20% - 5% |
| products.excise_letter | string | Ні | Символ для акцизу |
| products.code | string | Ні | Код товару |
| products.unit_code | string | Ні | Код одиниці виміру товару |
| products.unit_name | string | Ні | Назва одиниці виміру товару |
| products.name | string | Так | Назва товару |
| products.bar_code | string | Ні | Штрих-код |
| products.excise_barcode | string | Ні | Акцизний код |
| products.uktzed | integer | Ні | УКТЗЕД код товару |
| products.amount | float | Так | Кількість товару у чеку Не більше трьох знаків після коми |
| products.price | float | Так | Вартість однієї одиниці товару |
| products.cost | float | Так | Підсумок по даній позиції Не більше двох знаків після коми |
| products.sum_discount | float | Ні | Сума знижки |
| payments | list[object] | Так | Містить параметри методів оплати |
| payments.code | integer | Так | Код методу оплати: 0 — ГОТІВКА 1 — БЕЗГОТІВКОВА 2 — ІНШЕ |
| payments.name | string | Так | Назва форми оплати (Реквізити чека рядок 18):
|
| payments.payment_method | string | Ні | Засоби оплати у чеку (Реквізити чека рядок 19)
|
| payments.sum | float | Так | Сума оплати |
| payments.sum_provided | float | Так | Передана сума |
| payments.sum_remains | float | Ні | Сума решти 🛈 Вказується лише у випадку, якщо payments.code = 0 (код методу оплати) — ГОТІВКА |
| payments.pay_terminal | float | Ні | Параметри термінала при оплаті карткою |
| payments.pay_terminal.comission | float | Ні | Розмір комісії, що стягується при оплаті через платіжний термінал Може бути відсутнім або дорівнювати 0, якщо комісія не застосовується 🛈Якщо значення більше 0, ця сума буде виводитись у чеку |
| payments.pay_terminal.name | string | Ні | Ідентифікатор торговця (MID) Приклад: "493084867" |
| payments.pay_terminal.terminal_id | string | Ні | Ідентифікатор термінала (TID) |
| payments.pay_terminal.epz | string | Ні | Маска картки |
| payments.pay_terminal.card_type | string | Ні | Тип картки |
| payments.pay_terminal.auth_code | string | Ні | Код авторизації |
| payments.pay_terminal.rrn | string | Ні | Унікальний ідентифікатор банківської транзакції |
| payments.pay_terminal.additional_text | string | Ні | Додатковий текст 🛈 Не використовується |
| payments.pay_terminal.time | string | Ні | Дата та час оплати через термінал (LiqPay та інші) у форматі 25.04.2023 15:49:03 🛈 Клієнти повинні передавати параметр якщо різниця між оплатою і проведенням чека понад 5 хвилин |
| footer | string | Ні | Текст в нижній частині чека |
| open_shift | boolean | Ні | Прапор відкриття зміни Якщо зміна закрита і передано значення True, тоді зміна буде відкрита |
| print_width | integer | Ні | Ширина чека в символах |
| pdf_width | integer | Ні | Ширина pdf |
Приклад запиту
Запит: /api/v2/check/sale?api_token={api_token}
{
"api_token": "42b5eaccba739f08***e7fe157eba8bf",
"num_fiscal": 4000022469,
"action_type": "Z_SALE",
"local_number": 12,
"total_sum": 50.1,
"round_sum": 0.04,
"products": [
{
"letters": "А",
"tax_prc": "20",
"excise_prc": "5",
"excise_letter": null,
"code": "821",
"unit_code": "2009",
"unit_name": "штука",
"name": "Вода питна",
"uktzed": 4823004003572,
"amount": "1",
"price": "50.06",
"cost": "50.06",
"sum_discount": "0"
}
],
"payments": [
{
"code": 0,
"name": "ГОТІВКА",
"payment_method": 'готівка',
"sum": 100,
"sum_provided": 100,
"sum_remains": 0
},
{
"code": 1,
"name": "KARTKA",
"payment_method": 'безготівка',
"sum": 25,
"sum_provided": 25,
"pay_terminal": {
"comission": 0.5,
"name": "493084867",
"terminal_id": "40904582",
"epz": "4149XXXXXXXX5807",
"card_type": "VISA GOLD",
"auth_code": "538296",
"rrn": "000018706638",
"additional_text": "Тримач ЕПЗ - підпис",
"time": "03.04.2023 15:15:03"
}
}
],
"footer": "This is my\n custom footer! Welcome to CashDesk! \n Test \n Next line text!",
"open_shift": true,
"print_width": 32,
"pdf_width": 48
}
Параметри відповіді
інформація
Існує два способи друку чека:
- PDF-друк — повне представлення чека у форматі PDF
- Текстовий друк (поле text_print) — текстове представлення чека. QR код чека знаходиться в полі qr (формат png)
| Ім'я | Тип | Опис |
|---|---|---|
| ORDERNUM | string | Номер чека реалізації / повернення |
| ORDERDATE | string | Дата формування чека |
| ORDERTIME | string | Час формування чека |
| MAC | string | Код аутентифікації повідомлення чека |
| is_offline | boolean | Ознака офлайн чека |
| local_number | integer | Локальний номер операції, який клієнт передає з кожним чеком |
| text_print | string | Текстове представлення чека у форматі Base64. Клієнт самостійно обирає шрифт та спосіб друку |
| qr | string | QR код чека у форматі Base64. Для використання з текстовим чеком – додаткове зображення для друку |
| qr_data | string | Дані для генерації QR кода |
| string | PDF представлення чека у форматі Base64. Може бути одразу роздруковане без додаткової обробки | |
| link | string | Посилання для перегляду чека на сайті |
| uuid | string | Локальний uuid номер чека |
| cash_in_box | float | Поточна кількість грошей в касі |
Приклади успішних відповідей
Продаж/Повернення
200 OK
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"ORDERNUM": "OTbrl4J6zAQ",
"ORDERDATE": "2020-12-16",
"ORDERTIME": "09:58:45",
"MAC": "2baea23fdcfe2f4d1853ec5ad87d5fbdf65ed0fbf48f60623ac92e2e518d1bce",
"is_offline": false,
"local_number": 42,
"text_print": "ICAgICAgICAgINCi0JXQodCi0J7QktCY0Jkg0KfQldC....",
"qr": "iVBORw0KGgoAAAANSUhEUgAAAV4AAAFeCAYAAADNK....",
"qr_data": "http://",
"pdf": "JVBERi0xLjcKMSAwIG9iago8PCAvVHlwZSAvQ2F0",
"link": "http://cashdesk.com/check/b63ad1dd-b218-465e-9251-b2510de77205/html",
"uuid": "498372e1-dbbe-4af8-abd3-bba87082a3b6"
}
Продаж з округленням
200 OK
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"ORDERNUM": "Nuu7J2SBH6Y",
"ORDERDATE": "2021-07-29",
"ORDERTIME": "09:38:02",
"MAC": "16657e0878131705882484d4d2a31482f8457b8cd079da909c3d7ddb2963d362",
"is_offline": false,
"qr": null,
"link": "http://cashdesk.com/check/fac3e242-cd74-416a-9e7a-a19d3642b457/html",
"pdf": null,
"text_print": null,
"uuid": "fac3e242-cd74-416a-9e7a-a19d3642b457",
"local_number": 10,
"cash_in_box": 37804.69
}
Приклади неуспішних відповідей
ДПС цим підписом відкрита зміна на іншому ПРРО
400 Bad Request
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"message": "ДПС цим підписом відкрита зміна на іншому ПРРО 4000055257"
}
Дубль чека
інформація
Помилка виникне, якщо вже існує чек з таким же локальним номером, але сума чека різна.
Якщо у попереднього чека такий же локальний номер і сума чека однакова, то у відповідь повернеться попередній чек.
400 Bad Request
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"message": "Check already exist"
}
Сервер ДПС недоступний
503 Service Unavailable
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"message": "Сервер ДПС недоступний"
}
Помилка валідації даних
422 Unprocessable Entity
Відповідь: /api/v2/check/sale?api_token=42b5eaccba739f08***e7fe157eba8bf
{
"message": "The given data was invalid.",
"errors": {
"total_sum":
[
"Not correct calculation with payments 75"
]
}
}
порада
Postman колекція (Реалізація/Повернення): https://documenter.getpostman.com/view/12128952/TVRj5U1d#3c0a0189-75ad-430c-9724-7d92c3d09462