Реалізація / Повернення

Запит

URI: /api/v2/check/sale?api_token={api_token}

Метод дозволяє зробити реалізацію або повернення.

Запит виконується методом POST з тілом запиту у JSON форматі.

⚠️ Запит повинен містити заголовки Accept: application/json та Content-Type: application/json

Правила заокруглення сум при готівкових розрахунках (зміни з 1 жовтня 2025 року).

В запиті необхідно передавати параметри round_sum та round_rule. Детальну інформацію можна переглянути за посиланням

Округленню підлягає лише форма оплати готівкою. В масиві payments передаються округлені значення.

Приклади ПДВ

Приклади того, як податки відображаються залежно від значень у полях letters (літера податку) та tax_prc (відсоток податку):

ПДВ А 20%
"letters": "A"
"tax_prc": 20

ПДВ Б 0%
"letters": "Б"
"tax_prc": 0

БЕЗ ПДВ
"letters": null
"tax_prc": null

БЕЗ ПДВ Д
"letters": Д
"tax_prc": null

Якщо поле tax_prc порожнє або містить значення null, такий податок рахується БЕЗ ПДВ, а його літера береться з поля letters.

БЕЗ ПДВ (Без ПДВ з літерним відображенням)
"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	Ні	Сума округлення Вказується різниця в копійках між округленим і не округленим значенням (зі знаком `-`(знижка) або `+`(надбавка) відповідно)
round_rule	string	Ні	Правило заокруглення 🛈 за замовчуванням `10` Можливі значення: `0` - заокруглення вимкнено `10` - до 10 копійок `50` - до 50 копійок `100` - до 1 гривні
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.price та кількості products.amount Значення повинно містити не більше двох знаків після коми
products.sum_discount	float	Ні	Сума знижки для товарної позиції. 🛈 Віднімається від products.cost
payments	list[object]	Так	Містить параметри методів оплати
payments.code	integer	Так	Код методу оплати: 0 — ГОТІВКА 1 — БЕЗГОТІВКОВА 2 — ІНШЕ
payments.name	string	Так	Назва форми оплати Реквізити чека рядок 18): ГОТІВКА БЕЗГОТІВКОВА ІНШЕ
payments.payment_method	string	Ні	Засоби оплати у чеку (Реквізити чека рядок 19) Якщо форма оплати (payments.name) ГОТІВКА, рядок 19 фіскального касового чека Засоби оплати (payments.payment_method) НЕ друкується Якщо форма оплати (payments.name) БЕЗГОТІВКОВА — вкажіть засіб оплати. В іншому випадку за замовчуванням буде вказано Засіб оплати (payments.payment_method) — Електронний платіжний засіб Якщо форма оплати (payments.name) ІНШЕ — вкажіть власне значення (клієнт задає самостійно) 🛈 Якщо клієнт НЕ передає значення: для payments.code = 0 — в чеку відображається ГОТІВКА для payments.code = 1 або 2 — в чеку відображається Електронний платіжний засіб
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,
    "round_rule": 10,
    "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 кода
pdf	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

Запит​

Параметри запиту​

Приклад запиту​

Параметри відповіді​

Приклади успішних відповідей​

Продаж/Повернення​

Продаж з округленням​

Приклади неуспішних відповідей​

ДПС цим підписом відкрита зміна на іншому ПРРО​

Дубль чека​

Сервер ДПС недоступний​

Помилка валідації даних​