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

Запит

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.sum_discount	float	Ні	Сума знижки
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

Запит​

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

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

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

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

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

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

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

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

Дубль чека​

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

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