# Вчасно.Каса Хмарне API {#vchasno-kasa-cloud-fiscal-api}
API для інтеграції з кабінетом Вчасно.Каса та фіскалізації чеків. Напряму, без залучення Device Manager. Якщо ви користуєтесь Device Manager, то вам не потрібне це АПІ.
# Загальні вимоги {#general-requirements}
**HOST**: [https://kasa.vchasno.ua](https://kasa.vchasno.ua)
Для всіх методів очікуються такі хедери:
- **Content-Type: application/json**
- **Authorization: VCHASNO_KASA_PRRO_TOKEN**
Де `VCHASNO_KASA_PRRO_TOKEN` - токен каси, класти у хедер без префіксу Bearer.
Приклад запиту на дані по касі:
```
curl --location 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"fiscal": {
"task": 18
}
}'
```
Токен каси можна отримати у веб-кабінеті Вчасно.Каса ([https://kasa.vchasno.ua/](https://kasa.vchasno.ua/)), перейшовши у Налаштування конкретної каси (Дії з касою -> Налаштування каси -> блок Токен)
Токен відображається тільки один раз при його формуванні. Повторне отримання цього ж токену - неможливо (дані хешуються). Тому, якщо ви загубите токен каси, його треба буде перегенерувати. При перегенерації старий токен припиняє дію.
**Тестовий режим**
У веб-кабінеті [Вчасно.Каса](https://kasa.vchasno.ua) також доступна тестова каса, по якій можна взяти токен і тестувати інтеграцію. Відмінність тестової каси від реальної - чеки не відправляються до ДПС, всюди підсвічується, що це тестова каса та тестовий чек. Чеки з тестової каси **не можна надавати покупцям**, так як це порушення правил фіскалізації - клієнти мають отримувати дійсний чек з реальної каси. Реєстрація реальної каси також доступна у веб-кабінеті [Вчасно.Каса](https://kasa.vchasno.ua).
**Для фіскалізації чеків необхідно додати ключ у сховище ключів.**
Зробити це можна у веб-кабінеті, сторінка "Сховище ключів" ([https://kasa.vchasno.ua/app/storage-keys](https://kasa.vchasno.ua/app/storage-keys))
- [Postman-колекція *Імпортуйте, створіть Environment зі змінною KASA_PRRO_TOKEN — і надсилайте запити*](/cloud_api/vchasno-kasa.cloud.postman_collection.json)
{.links-list}
# Запити на фіскалізацію {#fiscal-requests-structure}
Всі запити на фіскалізацію виконуються через **POST /api/v3/fiscal/execute**
Зазвичай час виконання запиту на фіскалізацію складає до 1 секунди.
При проблемах з АЦСК чи ДПС ми виконуємо додаткові заходи задля забезпечення безперебійної роботи, тому рекомендуємо виставити таймаут на запит у 25 секунд. Обов'язково передавайте у запитах на фіскалізацію свій унікальний `tag`.
Флоу роботи:
- відкрити фіскальну зміну (task: 0). Рекомендуємо це робити явним АПІ запитом. Якщо ж зміна не була відкрита, то при виконанні запиту чеку (task: 1, 2, 3, 4, 14, 15, 16) вона буде відкрита автоматично.
- проводити фіскальні операції (чеки продажу, повернення, etc)
- закрити фіскальну зміну (task: 11). Тривалість однієї фіскальної зміни не має перевищувати 24 години, також рекомендуємо закривати зміну у той же день, коли і відкрили. У веб кабінеті можна налаштування автозакриття зміни.
## Структура запиту {#fs--request-structure}
Пояснення щодо обов'язковості ключів у запитах:
- ✅ - Обов'язково передавати для всіх запитів.
- ✔ - Обов'язковий тільки для певних запитів або при певних умовах. Умови зазначені у колонці "Зміст".
- ❌ - Опційний ключ, можна передавати за необхідності.
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>dt</td>
<td>string</td>
<td>Дата і час завдання в форматі <em>YYYYMMDDHHMMSS</em>.
Використовується як дата і час для чеку
<br>Якщо не передати - використається час серверу
<br><strong>ВАЖЛИВО!</strong> Дата чеку, що проводиться, має бути >= дати попереднього проведеного чеку. В іншому випадку ДПС не прийме такий чек.</td>
<td>❌</td>
</tr>
<tr>
<td>tag</td>
<td>string</td>
<td>Ідентифікатор запиту.
Можна вказати довільний рядок.
Використовується для ідентифікації повторних запитів на фіскалізацію. Для уникнення <strong>дублювання чеків,</strong> необхідно у кожному запиті вказувати власний унікальний ідентифікатор.
<br>Якщо не передати чи передати пустим, сервером буде згенеровано uuid для цього поля.</td>
<td>❌</td>
</tr>
<tr>
<td>source</td>
<td>string</td>
<td>Назва джерела завдання, може бути довільною. Слугує для кращої ідентифікації в логах</td>
<td>❌</td>
</tr>
<tr>
<td>fiscal</td>
<td>object</td>
<td>Об'єкт з реквізитами фіскального завдання</td>
<td>✅</td>
</tr>
<tr>
<td>userinfo</td>
<td>object</td>
<td>Дані, куди надсилати посилання на чек (для завдань 1, 2, 3, 4, 14, 15, 16).
<br>Об'єкт виду:
{
"email" : "...",
"phone": "+380XXXXXXXXX"
}
<br>Очікуємо формат +380XXXXXXXXX, та якщо ви вкажете додаткові розділові знаки у номері (наприклад +380ХХ-ХХХ-ХХ-ХХ), ми спробуємо конвертувати його у потрібний формат
<br>У випадку, якщо телефон чи емейл вказано невірно - повідомлення не буде відправлено, але на проведення чеку це ніяк не вплине (не буде валідаційної помилки).</td>
<td>❌</td>
</tr>
</tbody>
</table>
## Структура fiscal {#fs--fiscal-object}
### Структура об'єкту fiscal (реквізити фіскального завдання) {#fs--fiscal-object-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>task</td>
<td>integer</td>
<td>Тип фіскального завдання:
<br><strong>0 - відкриття зміни</strong>
<br><strong>1 - чек продажу</strong>
<br><strong>2 - чек повернення</strong>
<br><strong>3 - службове внесення</strong>
<br><strong>4 - службова видача</strong>
<br><strong>14 - чек видачі готівки</strong>
<br><strong>15 - чек переказу коштів</strong>
<br><strong>16 - чек видачі коштів при переказі</strong>
<br><strong>10 - X-звіт</strong>
<br><strong>11 - Z-звіт</strong>
<br><strong>18 - статус пРРО</strong></td>
<td>✅</td>
</tr>
<tr>
<td>subtask</td>
<td>integer</td>
<td>Маркування, тільки для чеків <strong>передплати</strong> та <strong>постоплати</strong>
<br>1 - передплата
<br>2 - постоплата</td>
<td>✔</td>
</tr>
<tr>
<td>cashier</td>
<td>string</td>
<td>Інформація про касира</td>
<td>❌</td>
</tr>
<tr>
<td>receipt</td>
<td>object</td>
<td>Поля чеку (для завдань 1 і 2)</td>
<td>✔</td>
</tr>
<tr>
<td>cash</td>
<td>object</td>
<td>Поля внесення/видачі, чеку видачі готівки і чеку видачі готівки при переказі (для завдань 3, 4, 14 і 16)</td>
<td>✔</td>
</tr>
</tbody>
</table>
## Структура fiscal.receipt {#fs--fiscal-receipt}
### Структура об'єкту fiscal.receipt (поля чеку) {#fs--fiscal-receipt-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>sum</td>
<td>float</td>
<td>Сума чеку (2 знаки після коми) з урахуванням всіх знижок</td>
<td>✅</td>
</tr>
<tr>
<td>round</td>
<td>float</td>
<td>Сума округлення (входить до суми чеку).
На цю суму має відрізнятись сума чеку від сум по всіх видам оплати.</td>
<td>❌</td>
</tr>
<tr>
<td>comment_up</td>
<td>string</td>
<td>Коментар, який друкується перед списком товарів</td>
<td>❌</td>
</tr>
<tr>
<td>comment_down</td>
<td>string</td>
<td>Коментар, який друкується внизу чеку</td>
<td>❌</td>
</tr>
<tr>
<td>rows</td>
<td>array</td>
<td>Рядки чеку</td>
<td>✅</td>
</tr>
<tr>
<td>pays</td>
<td>array</td>
<td>Перелік засобів оплат</td>
<td>✅</td>
</tr>
<tr>
<td>purchase_receipt_fisn</td>
<td>string</td>
<td><strong>Обов'язкове поле для чеків повернення (task 2) по програмі "Національний кешбек"</strong>
<br>Фіскальний номер чеку на продаж на основі якого здійснюється повернення</td>
<td>✔</td>
</tr>
<tr>
<td>purchase_rro_fisn</td>
<td>string</td>
<td><strong>Обов'язкове поле для чеків повернення (task 2) по програмі "Національний кешбек"</strong>
<br>Фіскальний номер РРО або ПРРО з якого було здійснено оригінальний продаж товару по чеку вказаного в <strong>purchase_receipt_fisn</strong></td>
<td>✔</td>
</tr>
<tr>
<td>purchase_receipt_dt</td>
<td>string</td>
<td><strong>Обов'язкове поле для чеків повернення (task 2) по програмі "Національний кешбек"</strong>
<br>Дата фіскалізації чеку на продаж по якому здійснюється повернення в форматі YYYYMMDD.</td>
<td>✔</td>
</tr>
<tr>
<td>disc</td>
<td>float</td>
<td>Сума або відсоток загальної знижки на чек.</td>
<td>❌</td>
</tr>
<tr>
<td>disc_type</td>
<td>integer</td>
<td>Визначає тип загальної знижки у fiscal.receipt.disc
Значення:
<br>0 - сумова
<br>1 - відсоткова знижка</td>
<td>❌</td>
</tr>
<tr>
<td>discounts</td>
<td>array</td>
<td>Список загальних знижок (якщо є потреба задати декілька).</td>
<td>❌</td>
</tr>
</tbody>
</table>
## Структура fiscal.receipt.rows {#fs--fiscal-receipt-rows}
### Структура об'єкту fiscal.receipt.rows (рядки чеку) {#fs--fiscal-receipt-rows-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>string</td>
<td>Артикул товару в обліковій системі підприємства</td>
<td>❌</td>
</tr>
<tr>
<td>code1</td>
<td>string</td>
<td>ШК (штрихкод) товару</td>
<td>❌</td>
</tr>
<tr>
<td>code2</td>
<td>string</td>
<td>Код УКТЗЕД</td>
<td>❌</td>
</tr>
<tr>
<td>code3</td>
<td>string</td>
<td>Код ДКПП</td>
<td>❌</td>
</tr>
<tr>
<td>code_a</td>
<td>string</td>
<td>Код акцизної марки товару</td>
<td>❌</td>
</tr>
<tr>
<td>code_aa</td>
<td>array</td>
<td>Масив акцизних марок товарів (для випадку, коли для одної позиції декілька марок)</td>
<td>❌</td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>Назва товару</td>
<td>✅</td>
</tr>
<tr>
<td>cnt</td>
<td>float</td>
<td>Кількість товару (не більше 3х знаків після коми)</td>
<td>✅</td>
</tr>
<tr>
<td>price</td>
<td>float</td>
<td>Ціна товару (2 знаки після коми)
Може бути пустим, тоді рахується автоматично шляхом поділу поля cost на cnt і математичним округленням</td>
<td>✅</td>
</tr>
<tr>
<td>disc</td>
<td>float</td>
<td>Знижка на рядок чеку (2 знаки після коми)</td>
<td>✅</td>
</tr>
<tr>
<td>cost</td>
<td>float</td>
<td>Сума по рядку до знижки
Може бути пустим, тоді рахується автоматично шляхом множення поля cnt на price і математичним округленням</td>
<td>✅</td>
</tr>
<tr>
<td>taxgrp</td>
<td>integer</td>
<td>Код податкової групи:
<br><strong>1 ПДВ 20%</strong>
<br><strong>2 Без ПДВ</strong>
<br><strong>3 ПДВ 20% + акциз 5%</strong>
<br><strong>4 ПДВ 7%</strong>
<br><strong>5 ПДВ 0%</strong>
<br><strong>6 Без ПДВ + акциз 5%</strong>
<br><strong>7 Не є об`єктом ПДВ</strong>
<br><strong>8 ПДВ 20% + ПФ 7.5%</strong>
<br><strong>9 ПДВ 14%</strong></td>
<td>✅</td>
</tr>
<tr>
<td>comment</td>
<td>string</td>
<td>Коментар на рядок</td>
<td>❌</td>
</tr>
</tbody>
</table>
## Структура fiscal.receipt.pays {#fs--fiscal-receipt-pays}
### Структура об'єкту fiscal.receipt.pays (Оплати чеку (по видам)) {#fs--fiscal-receipt-pays-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>integer</td>
<td>Код засобу оплати. Коди за замовчуванням:
<br><strong>0 Готівка</strong>
<br><strong>1 Безготівка</strong>
<br><strong>2 Картка</strong>
<br><strong>3 Передплата</strong>
<br><strong>4 Післясплата</strong>
<br><strong>5 Кредит</strong>
<br><strong>6 Сертифікат</strong>
<br><strong>8 Чек</strong>
<br><strong>11 Бонусні бали</strong>
<br><strong>12 Погашення кредиту</strong>
<br><strong>13 Переказ через QR-код</strong>
<br><strong>14 Переказ з картки</strong>
<br><strong>15 Переказ з поточного рахунку</strong>
<br><strong>16 Інтернет еквайринг</strong>
<br><strong>17 Платіж LiqPay</strong>
<br><strong>18 Платіж через сервіс переказу ROZETKA Pay</strong>
<br><strong>19 Платіж Portmone</strong>
<br><strong>20 Платіж NovaPay</strong>
<br> Або ж кастомний варіант (налаштовується у кабінеті)</td>
<td>✅</td>
</tr>
<tr>
<td>sum</td>
<td>float</td>
<td>Сума оплати (2 знаки після коми)</td>
<td>✅</td>
</tr>
<tr>
<td>comment</td>
<td>string</td>
<td>Коментар на рядок оплати</td>
<td>❌</td>
</tr>
<tr>
<td>change</td>
<td>float</td>
<td>Решта (для оплати готівкою)
<br>Для правильного внесення оплати з рештою необхідно
<br>- в поле <strong>sum</strong> внести суму, яка іде в залік,
<br>- в поле <strong>change</strong> - решту.
<br>Загальна сума, яка отримана від покупця, розраховується як sum+change</td>
<td>✔</td>
</tr>
<tr>
<td>paysys</td>
<td>string</td>
<td>Назва платіжної системи (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>rrn</td>
<td>string</td>
<td>Код транзакції (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>cardmask</td>
<td>string</td>
<td>Замаскований номер картки (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>term_id</td>
<td>string</td>
<td>Ідентифікатор платіжного терміналу (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>bank_name</td>
<td>string</td>
<td>Назва банку еквайера (для оплати карткою).
<br>Вказується виключно як інформаційне поле для відображення в формі чеку назви банку еквайера. Не відображається у в'ювері чеків без <strong>bank_id.</strong> Дані вказані в це поле не відправляються в ДПС.</td>
<td>✔</td>
</tr>
<tr>
<td>bank_id</td>
<td>string</td>
<td>Ідентифікатор банку (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>auth_code</td>
<td>string</td>
<td>Код авторизації (для оплати карткою)</td>
<td>✔</td>
</tr>
<tr>
<td>oper_type</td>
<td>string</td>
<td>Вид операції</td>
<td>❌</td>
</tr>
<tr>
<td>commission</td>
<td>float</td>
<td>Сума комісії</td>
<td>❌</td>
</tr>
<tr>
<td>purchase_dt</td>
<td>string</td>
<td><strong>Обов'язкове поле для чеків продажу (task 1) по програмі "Національний кешбек"</strong>
<br>Дата та час авторизації оплати на терміналі в форматі YYYYMMDDHHMMSS.
<br>У візуалізації чеку даний час не відображається, лише передається в ДПС.</td>
<td>✔</td>
</tr>
</tbody>
</table>
## Структура fiscal.receipt.discounts {#fs--fiscal-receipt-discounts}
### Структура об'єкту fiscal.receipt.discounts (Список загальних знижок) {#fs--fiscal-receipt-discounts-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>disc</td>
<td>float</td>
<td>Сума або відсоток загальної знижки на чек.</td>
<td>✅</td>
</tr>
<tr>
<td>disc_type</td>
<td>integer</td>
<td>Тип загальної знижки.
Значення:
<br>0 - сумова,
<br>1 - відсоткова знижка.</td>
<td>✅</td>
</tr>
<tr>
<td>disc_name</td>
<td>string</td>
<td>Назва загальної знижки.
За замовчуванням "Знижка".</td>
<td>❌</td>
</tr>
</tbody>
</table>
## Структура fiscal.cash {#fs--fiscal-cash}
### Структура об'єкту fiscal.cash (Поля внесення/видачі, чеку видачі готівки, чеку видачі коштів при переказі) {#fs--fiscal-cash-inner}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>integer</td>
<td>Код засобу оплати. Коди за замовчуванням:
<br><strong>0 Готівка</strong>
<br><strong>1 Безготівка</strong>
<br><strong>2 Картка</strong>
<br><strong>3 Передплата</strong>
<br><strong>4 Післясплата</strong>
<br><strong>5 Кредит</strong>
<br><strong>6 Сертифікат</strong>
<br><strong>8 Чек</strong>
<br><strong>11 Бонусні бали</strong>
<br><strong>12 Погашення кредиту</strong>
<br><strong>13 Переказ через QR-код</strong>
<br><strong>14 Переказ з картки</strong>
<br><strong>15 Переказ з поточного рахунку</strong>
<br><strong>16 Інтернет еквайринг</strong>
<br><strong>17 Платіж LiqPay</strong>
<br><strong>18 Платіж через сервіс переказу ROZETKA Pay</strong>
<br><strong>19 Платіж Portmone</strong>
<br><strong>20 Платіж NovaPay</strong>
<br> Або ж кастомний варіант (налаштовується у кабінеті)</td>
<td>✅</td>
</tr>
<tr>
<td>sum</td>
<td>float</td>
<td>Сума внесення\видачі (2 знаки після коми)</td>
<td>✅</td>
</tr>
<tr>
<td>comment_up</td>
<td>string</td>
<td>Коментар, який друкується перед сумою</td>
<td>❌</td>
</tr>
<tr>
<td>comment_down</td>
<td>string</td>
<td>Коментар, який друкується після суми</td>
<td>❌</td>
</tr>
<tr>
<td>paysys</td>
<td>string</td>
<td>Назва платіжної системи <strong>(лише для чеку видачі готівки та чеку видачі готівки при переказі)</strong></td>
<td>✔</td>
</tr>
<tr>
<td>rrn</td>
<td>string</td>
<td>Код транзакції
<strong>Обов'язкове поле для task 4, 16</strong></td>
<td>✔</td>
</tr>
<tr>
<td>cardmask</td>
<td>string</td>
<td>Замаскований номер картки <strong>(лише для чеку видачі готівки та чеку видачі готівки при переказі)</strong></td>
<td>✔</td>
</tr>
<tr>
<td>term_id</td>
<td>string</td>
<td>Ідентифікатор платіжного терміналу <strong>(лише для чеку видачі готівки та чеку видачі готівки при переказі)</strong></td>
<td>✔</td>
</tr>
<tr>
<td>bank_id</td>
<td>string</td>
<td>Ідентифікатор банку <strong>Обов'язкове поле для task 4, 16</strong></td>
<td>✔</td>
</tr>
<tr>
<td>auth_code</td>
<td>string</td>
<td>Код авторизації <strong>(лише для чеку видачі готівки та чеку видачі готівки при переказі)</strong></td>
<td>✔</td>
</tr>
<tr>
<td>commission</td>
<td>float</td>
<td>Сума комісії <strong>(лише для чеку видачі готівки та чеку видачі готівки при переказі)</strong></td>
<td>✔</td>
</tr>
</tbody>
</table>
## Структура відповіді {#fs--response-structure}
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>ver</td>
<td>integer</td>
<td>Версія схеми (службове поле)</td>
<td>✅</td>
</tr>
<tr>
<td>source</td>
<td>string</td>
<td>Назва джерела завдання</td>
<td>✅</td>
</tr>
<tr>
<td>device</td>
<td>string</td>
<td>Фіскальний номер каси</td>
<td>✅</td>
</tr>
<tr>
<td>tag</td>
<td>string</td>
<td>Мітка завдання для ідентифікації відповіді</td>
<td>✅</td>
</tr>
<tr>
<td>dt</td>
<td>string</td>
<td>Дата та час виконання в форматі <em>YYYYMMDDHHMMSS</em></td>
<td>✅</td>
</tr>
<tr>
<td>res</td>
<td>integer</td>
<td>Код результату
<br>0 - ОК
<br>> 0 - код помилки</td>
<td>✅</td>
</tr>
<tr>
<td>res_action</td>
<td>integer</td>
<td>Подальші рекомендовані дії для збереження транзакційної цілісності
<br>0 - ОК, можна переходити до наступного завдання
<br>1 - помилка, завдання не пройшло, необхідно повторити запит
<br>2 - помилка + колізія. Виправлення колізії буде виконано при наступному запиті, тому необхідно виконати повтор для збереження транзакційності
<br>3 - помилка, що потребує зупинки та ручного фіксу</td>
<td>✅</td>
</tr>
<tr>
<td>errortxt</td>
<td>string</td>
<td>Текстова інформація про помилку</td>
<td>✅</td>
</tr>
<tr>
<td>error_extra</td>
<td>object | null</td>
<td>Опційний об'єкт, в якому повертаються деталі щодо помилки. Наприклад перелік полів, та причини, чому вони не пройшли валідацію</td>
<td>✅</td>
</tr>
<tr>
<td>warnings</td>
<td>array</td>
<td>Масив об'єктів вигляду
{code: 0, wtxt: "..."} з кодами та текстами попереджень, які потрібно донести до касира. Перелік кодів та текстів у розділі <strong>"Опис помилок"</strong></td>
<td>✅</td>
</tr>
<tr>
<td>task</td>
<td>integer</td>
<td>Тип завдання</td>
<td>✅</td>
</tr>
<tr>
<td>info</td>
<td>object</td>
<td>Вихідні дані
<br><em>Опис об'єкту info для конкретного типу завдання приведено у самих запитах нижче</em></td>
<td>✅</td>
</tr>
</tbody>
</table>
# Фіскальні запити {#fiscal-requests}
## Відкриття зміни (`"task": 0`) {#fr--open-shift}
<details>
<summary>Деталі</summary>
Якщо зміну на ПРРО закрито, то при надсиланні першого чеку (task = 1,2,3,4,14,15,16) **автоматично** надсилається запит на відкриття зміни.
**Опис відповіді**
**Структура об'єкту info для завдання відкриття зміни**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>task</td>
<td>integer</td>
<td>Тип завдання</td>
<td>✅</td>
</tr>
<tr>
<td>dt</td>
<td>string</td>
<td>Дата та час проведення чеку в форматі <em>YYYYMMDDHHMMSS</em></td>
<td>✅</td>
</tr>
<tr>
<td>fisid</td>
<td>string</td>
<td>Фіскальний номер каси</td>
<td>✅</td>
</tr>
<tr>
<td>doccode</td>
<td>string</td>
<td>Фіскальний номер чеку</td>
<td>✅</td>
</tr>
<tr>
<td>dataid</td>
<td>integer</td>
<td>Номер сформованого пакету</td>
<td>✅</td>
</tr>
<tr>
<td>shift_link</td>
<td>integer</td>
<td>Номер зміни каси</td>
<td>✅</td>
</tr>
<tr>
<td>shift_id</td>
<td>string</td>
<td>ID зміни</td>
<td>✅</td>
</tr>
<tr>
<td>cashier</td>
<td>string</td>
<td>Інформація про касира</td>
<td>✅</td>
</tr>
<tr>
<td>isoffline</td>
<td>bool</td>
<td>В якому режимі проведено чек
<br>true - в офлайні
<br>false - в онлайні</td>
<td>✅</td>
</tr>
<tr>
<td>safe</td>
<td>float</td>
<td>Сума готівки в касі</td>
<td>✅</td>
</tr>
<tr>
<td>dtype</td>
<td>integer</td>
<td>Тип девайсу
<br>0 - тестовий
<br>1 - фіскальний</td>
<td>✅</td>
</tr>
</tbody>
</table>
## відкриття_зміни {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 0
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 0,
"type": 1,
"ver": 6,
"source": "",
"device": "99997655555555",
"tag": "33d2bd1acb739cc9d80a7d24451ba318",
"dt": "20240131100530",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 0,
"fisid": "99997655555555",
"dataid": 195,
"doccode": "TEST_JC5D9PZUrd-ZKQ",
"dt": "20240131100530",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 0,
"shift_link": 46,
"shift_id": "6b72e68d-e596-4e11-a190-bedbded40cc2"
},
"error_extra": null
}
```
</details>
## Чек продажу (`"task": 1`) {#fr--sale-receipt}
<details>
<summary>Деталі</summary>
**Опис відповіді**
**Структура об'єкту info для завдань 1, 2, 3, 4, 14, 15, 16 (чек продажу та повернення, службове внесення/видача, чек видачі готівки, чек переказу коштів, чек видачі коштів при переказі)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>task</td>
<td>integer</td>
<td>Тип завдання</td>
<td>✅</td>
</tr>
<tr>
<td>dt</td>
<td>string</td>
<td>Дата та час проведення чеку в форматі <em>YYYYMMDDHHMMSS</em></td>
<td>✅</td>
</tr>
<tr>
<td>fisid</td>
<td>string</td>
<td>Фіскальний номер каси</td>
<td>✅</td>
</tr>
<tr>
<td>doccode</td>
<td>string</td>
<td>Фіскальний номер чеку</td>
<td>✅</td>
</tr>
<tr>
<td>dataid</td>
<td>integer</td>
<td>Номер сформованого пакету</td>
<td>✅</td>
</tr>
<tr>
<td>shift_link</td>
<td>integer</td>
<td>Номер зміни каси</td>
<td>✅</td>
</tr>
<tr>
<td>cashier</td>
<td>string</td>
<td>Інформація про касира</td>
<td>✅</td>
</tr>
<tr>
<td>isoffline</td>
<td>bool</td>
<td>В якому режимі проведено чек
true - в офлайні
false - в онлайні</td>
<td>✅</td>
</tr>
<tr>
<td>safe</td>
<td>float</td>
<td>Сума готівки в касі</td>
<td>✅</td>
</tr>
<tr>
<td>dtype</td>
<td>integer</td>
<td>Тип девайсу
0 - тестовий
1 - фіскальний</td>
<td>✅</td>
</tr>
<tr>
<td>qr</td>
<td>string</td>
<td>Посилання на електронний фіскальний чек Вчасно.Каса</td>
<td>✅</td>
</tr>
<tr>
<td>cancelid</td>
<td>string</td>
<td>Ідентифікатор для відміни операції</td>
<td>✅</td>
</tr>
<tr>
<td>mac</td>
<td>string</td>
<td>Контрольне число послідовності чеків</td>
<td>✅</td>
</tr>
</tbody>
</table>
## чек_продажу {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"userinfo": {
"email": "RECIPIENT_EMAIL",
"phone": "+380XXXXXXXXX"
},
"fiscal": {
"task": 1,
"receipt": {
"sum": 199.99,
"round": 0.01,
"comment_up": "Зразок! Коментар шапки чеку",
"comment_down": "Зразок! ДЯКУЄМО за покупку",
"disc": 10.00,
"disc_type": 0,
"rows": [
{
"code": "00001",
"pop": "Оплата за послуги користування ПРРО",
"code1": "73463253",
"code2": "54321",
"code_aa": [
"XX11111111111",
"XX11111111112"
],
"name": "Продукт 1",
"cnt": 2,
"price": 55.00,
"disc": 10.00,
"taxgrp": "4",
"comment": "Зразок! Коментар"
},
{
"code": "00002",
"code1": "73463254",
"code2": "45667",
"code_a": "XX11111111113",
"name": "Продукт 2",
"cnt": 1,
"price": 89.99,
"disc": -10.00,
"taxgrp": 3,
"comment": "Зразок! \"Have a good day\""
}
],
"pays": [
{
"type": 0,
"sum": 150.00,
"change": 50.00,
"comment": "Зразок! Тест"
},
{
"type": 2,
"sum": 40.00,
"commission": 1.00,
"paysys": "paysys_test",
"rrn": "rrn_test",
"oper_type": "Оплата",
"cardmask": "cardmask****test",
"term_id": "term_id",
"bank_name": "bank_name",
"bank_id": "bank_id",
"auth_code": "auth_code",
"comment": "Зразок! СЛАВА*УКРАЇНІ",
"show_additional_info": true
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 1,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "ea1a404fcc8f48f3e1dea03fe1ad3cbd",
"dt": "20241114121430",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 1,
"fisid": "99997955555555",
"dataid": 152,
"doccode": "TEST_7B_WSDzzmo9H7w",
"dt": "20241114121430",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 150,
"shift_link": 37,
"docno": 1,
"cancelid": "TEST_7B_WSDzzmo9H7w",
"qr": "https://kasa.vchasno.ua/c/TEST_7B_WSDzzmo9H7w?id=TEST_7B_WSDzzmo9H7w&date=20241114&time=12:14:30&fn=99997955555555&sm=189.99&mac=e8acd9a470a6b4258ec4df473bb2a121094543d48f611084f1bfb08cb712f2e8",
"mac": "e8acd9a470a6b4258ec4df473bb2a121094543d48f611084f1bfb08cb712f2e8"
},
"error_extra": null
}
```
</details>
## Чек повернення (`"task": 2`) {#fr--return-receipt}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище)
## чек_повернення {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 2,
"receipt": {
"sum": 199.99,
"round": 0.01,
"comment_up": "Зразок! Коментар шапки чеку",
"comment_down": "Зразок! ДЯКУЄМО за повернення",
"rows": [
{
"code": "00001",
"code1": "73463253",
"code2": "54321",
"code_aa": [
"XX11111111111",
"XX11111111112"
],
"name": "Продукт 1",
"cnt": 2,
"price": 55.00,
"disc": 10.00,
"taxgrp": "4",
"comment": "Зразок! Коментар"
},
{
"code": "00002",
"code1": "73463254",
"code2": "45667",
"code_a": "XX11111111113",
"name": "Продукт 2",
"cnt": 1,
"price": 89.99,
"disc": -10.00,
"taxgrp": 3,
"comment": "Зразок! \"Have a good day\""
}
],
"pays": [
{
"type": 0,
"sum": 150.00,
"change": 50.00,
"comment": "Зразок! Тест"
},
{
"type": 2,
"sum": 50.00,
"commission": 1.00,
"paysys": "paysys_test",
"rrn": "rrn_test",
"oper_type": "Оплата",
"cardmask": "cardmask****test",
"term_id": "term_id",
"bank_id": "bank_id",
"auth_code": "auth_code",
"comment": "Зразок! СЛАВА*УКРАЇНІ",
"show_additional_info": true
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 2,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "6fd430b3685d1d445c8a611d61cdd54a",
"dt": "20241114121508",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 2,
"fisid": "99997955555555",
"dataid": 153,
"doccode": "TEST_g8MjrMAN_X6lKA",
"dt": "20241114121508",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 0,
"shift_link": 37,
"docno": 1,
"cancelid": "TEST_g8MjrMAN_X6lKA",
"qr": "https://kasa.vchasno.ua/c/TEST_g8MjrMAN_X6lKA?id=TEST_g8MjrMAN_X6lKA&date=20241114&time=12:15:08&fn=99997955555555&sm=199.99&mac=975e62f6827b43fc88bc9997a6a36c68d95fb0cc8fea82d8ac89e9b75ac3050f",
"mac": "975e62f6827b43fc88bc9997a6a36c68d95fb0cc8fea82d8ac89e9b75ac3050f"
},
"error_extra": null
}
```
</details>
## Чек передплати (`"task": 1, "subtask": 1`) {#fr--prepayment-receipt}
<details>
<summary>Деталі</summary>
**Додаткові параметри для створення чеку передплати**
У об'єкті **rows** параметр **cnt** має бути 0
У об'єкті **fiscal** параметр **subtask=1** вказує що це чек передплати, обов'язковий параметр, якщо його пропустити, не буде створено чек передплати
Об'єкт **rows_pre_payment** опційний. Вказуються всі товари по яким робиться чек передоплати, для кращої валідації чеку постоплати
## чек_передплати {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 1,
"subtask": 1,
"receipt": {
"sum": 50.00,
"round": 0,
"comment_down": "Передплата по товарах: Товар, 100.00 грн",
"rows": [
{
"name": "Передплата",
"cnt": 0,
"price": 50.00,
"disc": 0,
"taxgrp": "1"
}
],
"rows_pre_payment": [
{
"name": "Товар",
"cnt": 1,
"price": 100.00,
"disc": 0,
"taxgrp": "1",
"code_aa": []
}
],
"pays": [
{
"type": 0,
"sum": 50.00,
"change": 0
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 1,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "95ecf2c0b92d7b12e6ac9ee1e77131d0",
"dt": "20241114121544",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 1,
"fisid": "99997955555555",
"dataid": 154,
"doccode": "TEST_kD2wSQzTqMSMdA",
"dt": "20241114121544",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 50,
"shift_link": 37,
"docno": 2,
"cancelid": "TEST_kD2wSQzTqMSMdA",
"qr": "https://kasa.vchasno.ua/c/TEST_kD2wSQzTqMSMdA?id=TEST_kD2wSQzTqMSMdA&date=20241114&time=12:15:44&fn=99997955555555&sm=50.00&mac=9facb17a574dfcc29a03e48905fc88d3907b4cafc4777ac97fb5155eb5227d5d",
"mac": "9facb17a574dfcc29a03e48905fc88d3907b4cafc4777ac97fb5155eb5227d5d"
},
"error_extra": null
}
```
</details>
## Чек післяплати (`"task": 1, "subtask": 2`) {#fr--postpayment-receipt}
<details>
<summary>Деталі</summary>
**Додаткові параметри для створення чеку післяплати**
**post_payment_of_check_fn**: prepayment_check_fn вказується для прив'язки до чеку передплати
У об'єкті **fiscal** обов'язковий параметр **subtask: 2** який вказує що це чек післяплати
У об'єкті **rows** обов'язковий параметр **disc_apply_type: 1** для знижок у післяплати
## чек_післяплати {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"post_payment_of_check_fn": "TEST_kD2wSQzTqMSMdA",
"fiscal": {
"task": 1,
"subtask": 2,
"receipt": {
"sum": 50.00,
"round": 0,
"comment_down": "Післяплата по товарах: Товар, 100.00 грн. Чек передплати: TEST_kD2wSQzTqMSMdA",
"rows": [
{
"name": "Товар ",
"cnt": 1,
"price": 100.00,
"disc": 50.00,
"disc_apply_type": 1,
"taxgrp": "1",
"code_aa": []
}
],
"pays": [
{
"type": 0,
"sum": 50.00,
"change": 0
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 1,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "a54aa166bcf17b33d9933fc5d7d109b2",
"dt": "20241114121643",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 1,
"fisid": "99997955555555",
"dataid": 155,
"doccode": "TEST_K7_fVdv_44YxdA",
"dt": "20241114121643",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 100,
"shift_link": 37,
"docno": 3,
"cancelid": "TEST_K7_fVdv_44YxdA",
"qr": "https://kasa.vchasno.ua/c/TEST_K7_fVdv_44YxdA?id=TEST_K7_fVdv_44YxdA&date=20241114&time=12:16:43&fn=99997955555555&sm=50.00&mac=c15a64d915581ca9b9dc8f184fcb9ff0f594c04ab8ceefb4e8c70e82c9a9fd3f",
"mac": "c15a64d915581ca9b9dc8f184fcb9ff0f594c04ab8ceefb4e8c70e82c9a9fd3f"
},
"error_extra": null
}
```
</details>
## Чек видачі готівки (`"task": 14`) {#fr--cash-withdrawal-receipt}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище)
## чек_видачі_готівки {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 14,
"cash": {
"type": 2,
"sum": 100,
"commission": 1.01,
"bank_id": "bank_id",
"term_id": "terminal_id",
"paysys": "paysys_test",
"rrn": "rrn_test",
"cardmask": "cardmask****test",
"auth_code": "auth_code",
"comment_up": "Зразок! Верхній комент",
"comment_down": "Зразок Нижній комент"
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 14,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "9926384e47ac3bd369959bf2aa13bb13",
"dt": "20241114121810",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 14,
"fisid": "99997955555555",
"dataid": 158,
"doccode": "TEST_muS2KtTYKboVbA",
"dt": "20241114121810",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 0,
"shift_link": 37,
"docno": 1,
"cancelid": "TEST_muS2KtTYKboVbA",
"qr": "https://kasa.vchasno.ua/c/TEST_muS2KtTYKboVbA?id=TEST_muS2KtTYKboVbA&date=20241114&time=12:18:10&fn=99997955555555&sm=101.01&mac=b617916f2ab2b1eef8644321d29b4f44e60f8cca06de4964a82660c6eaeacfd9",
"mac": "b617916f2ab2b1eef8644321d29b4f44e60f8cca06de4964a82660c6eaeacfd9"
},
"error_extra": null
}
```
</details>
## Чек переказу коштів (`"task": 15`) {#fr--money-transfer-receipt}
<details>
<summary>Деталі</summary>
**Валідація:**
Якщо хоча б в одному із об'єктів заповнені **payer_code** та/або **payer_name**, інші об'єкти повинні мати ідентичні дані по цим полям
Якщо в одному із об'єктів відсутнє значення **payer_code** і **payer_name**, заповнюємо з того об'єкту де воно є автоматично
Заборонено використовувати форму оплати "Інше" для чеку переказу коштів
**Додаткові поля об'єкту fiscal.receipt для чеку переказу коштів:**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>psp_id</td>
<td>string</td>
<td>Номер ПТКС / номер відокремленого підрозділу надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>psp_name</td>
<td>string</td>
<td>Найменування надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>psp_code</td>
<td>string</td>
<td>Податковий номер надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
</tbody>
</table>
**Додаткові поля об'єкту fiscal.receipt.rows для чеку переказу коштів:**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>recipient_name</td>
<td>string</td>
<td>Назва одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_code</td>
<td>string</td>
<td>Ідентифікаційний код одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_name</td>
<td>string</td>
<td>Найменування платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_code</td>
<td>string</td>
<td>Ідентифікаційний код платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_pan</td>
<td>string</td>
<td>Реквізити платіжного засобу отримувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_nban</td>
<td>string</td>
<td>Номер рахунку отримувача відкритого у небанківського надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_pan</td>
<td>string</td>
<td>Реквізити платіжного засобу платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_pr</td>
<td>string</td>
<td>Підстава платежу платником
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>transfer_id</td>
<td>string</td>
<td>Ідентифікатор переказу
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_bankid</td>
<td>string</td>
<td>Код банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_bankname</td>
<td>string</td>
<td>Найменування банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_ban</td>
<td>string</td>
<td>Номер рахунку в банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>pop</td>
<td>string</td>
<td>Призначення платежу (одержувача)
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
</tbody>
</table>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище)
## чек_переказу_коштів {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 15,
"receipt": {
"sum": 110.00,
"comment_up": "Зразок! Коментар шапки чеку",
"comment_down": "Зразок! Дякуємо",
"psp_id": "psp_id",
"psp_code": "psp_code",
"psp_name": "psp_name",
"rows": [
{
"code": "1",
"name": "Переказ коштів",
"pop": "Оплата за послуги користування ПРРО",
"recipient_name": "Вчасно Сервіс",
"recipient_code": "recipient_code",
"payer_name": "Кобилянська О. Ю.",
"payer_code": "payer_code",
"recipient_pan": "recipient_pan",
"recipient_nban": "recipient_nban",
"payer_pan": "payer_pan",
"payer_pr": "payer_pr",
"transfer_id": "transfer_id",
"recipient_bankid": "recipient_bankid",
"recipient_bankname": "recipient_bankname",
"recipient_ban": "recipient_ban",
"cnt": 1,
"price": 100.00,
"cost": 100.00,
"taxgrp": 2,
"comment": "Коментар",
"disc": 0
}
],
"pays": [
{
"type": 0,
"sum": 100.00,
"commission": 10.00,
"bank_id": "EVOPAY",
"rrn": "rrn1234"
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 15,
"type": 1,
"ver": 6,
"source": "",
"device": "9999973304407430",
"tag": "09cc6d20aa059b2e4dbd033f6068a23d",
"dt": "20250318101337",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 15,
"fisid": "9999973304407430",
"dataid": 126,
"doccode": "TEST_BHWyKU8KbdGkIQ",
"dt": "20250318101337",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 940.5,
"shift_link": 15,
"docno": 4,
"cancelid": "TEST_BHWyKU8KbdGkIQ",
"qr": "https://kasa.vchasno.ua/c/TEST_BHWyKU8KbdGkIQ?id=TEST_BHWyKU8KbdGkIQ&sm=110.00&fn=9999973304407430&date=20250318&time=10:13:37",
"mac": "7b1deb9bf40167ec765a17945dc7b88320da6429f6a0d4fda60478871cb0abc9"
},
"error_extra": null
}
```
</details>
## Чек видачі коштів при переказі (`"task": 16`) {#fr--transfer-payout-receipt}
<details>
<summary>Деталі</summary>
**Додаткові поля об'єкту fiscal.receipt для чеку видачі коштів при переказі:**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>psp_id</td>
<td>string</td>
<td>Номер ПТКС / номер відокремленого підрозділу надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>psp_name</td>
<td>string</td>
<td>Найменування надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>psp_code</td>
<td>string</td>
<td>Податковий номер надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
</tbody>
</table>
**Додаткові поля об'єкту fiscal.receipt.rows для чеку видачі коштів при переказі:**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>recipient_name</td>
<td>string</td>
<td>Назва одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_code</td>
<td>string</td>
<td>Ідентифікаційний код одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_name</td>
<td>string</td>
<td>Найменування платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_code</td>
<td>string</td>
<td>Ідентифікаційний код платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_pan</td>
<td>string</td>
<td>Реквізити платіжного засобу отримувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_nban</td>
<td>string</td>
<td>Номер рахунку отримувача відкритого у небанківського надавача платіжних послуг
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_pan</td>
<td>string</td>
<td>Реквізити платіжного засобу платника
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>payer_pr</td>
<td>string</td>
<td>Підстава платежу платником
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>transfer_id</td>
<td>string</td>
<td>Ідентифікатор переказу
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_bankid</td>
<td>string</td>
<td>Код банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_bankname</td>
<td>string</td>
<td>Найменування банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>recipient_ban</td>
<td>string</td>
<td>Номер рахунку в банку одержувача
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
<tr>
<td>pop</td>
<td>string</td>
<td>Призначення платежу (одержувача)
<strong>За наявності</strong></td>
<td>✅</td>
</tr>
</tbody>
</table>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище)
## чек_видачі_коштів_при_переказі {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 16,
"receipt": {
"sum": 50.00,
"comment_up": "Зразок! Коментар шапки чеку",
"comment_down": "Зразок! Дякуємо",
"rows": [
{
"code": "1",
"name": "Переказ коштів",
"pop": "Оплата за послуги користування ПРРО",
"recipient_name": "Вчасно Сервіс",
"recipient_code": "41231992",
"payer_name": "Кобилянська О. Ю.",
"payer_code": "774635422",
"cnt": 1,
"price": 40.00,
"cost": 40.00,
"commission": 10.0,
"taxgrp": 2,
"comment": "Коментар",
"disc": 0
}
],
"pays": []
},
"cash": {
"type": 1,
"sum": 40.00,
"commission": 10.00,
"bank_id": "EVOPAY",
"rrn": "rrn1234"
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 16,
"type": 1,
"ver": 6,
"source": "",
"device": "9999973304407430",
"tag": "b216810fd02c37ddeaa37a39944a0971",
"dt": "20250317124218",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 16,
"fisid": "9999973304407430",
"dataid": 104,
"doccode": "TEST_Mo173a74miyVDg",
"dt": "20250317124218",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 730,
"shift_link": 14,
"docno": 2,
"cancelid": "TEST_Mo173a74miyVDg",
"qr": "https://kasa.vchasno.ua/c/TEST_Mo173a74miyVDg?id=TEST_Mo173a74miyVDg&sm=50.00&fn=9999973304407430&date=20250317&time=12:42:18",
"mac": "12dbf3fcca612d99ebb85983d73cc91c3cf0ba01205ecdbe90932cccda20eab8"
},
"error_extra": null
}
```
</details>
## Службове внесення (`"task": 3`) {#fr--service-deposit}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище).
## службове_внесення {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 3,
"cash": {
"type": 0,
"comment_up": "Зразок! Тестове внесення готівка",
"sum": 500.50,
"comment_down": "Зразок! Внесення"
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 3,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "49c8b16e0ee40a2c3337fd97e9d0f8e7",
"dt": "20241114121717",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 3,
"fisid": "99997955555555",
"dataid": 156,
"doccode": "TEST_Kh3BQlxRKP0cUg",
"dt": "20241114121717",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 600.5,
"shift_link": 37,
"docno": 1,
"cancelid": "TEST_Kh3BQlxRKP0cUg",
"qr": "https://kasa.vchasno.ua/c/TEST_Kh3BQlxRKP0cUg?id=TEST_Kh3BQlxRKP0cUg&date=20241114&time=12:17:17&fn=99997955555555&sm=500.50&mac=ee8c01741c0b95cf28c6688e4e29b92fbb0c3fedf511482b8306ce0a7c75840e",
"mac": "ee8c01741c0b95cf28c6688e4e29b92fbb0c3fedf511482b8306ce0a7c75840e"
},
"error_extra": null
}
```
</details>
## Службова видача (`"task": 4`) {#fr--service-withdrawal}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структура відповіді аналогічна чеку продажу (описано вище)
## службова_видача {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 4,
"cash": {
"type": 0,
"comment_up": "Зразок! Тестова видача готівка",
"sum": 500.50,
"comment_down": "Зразок! Видача"
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 4,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "6cd1fb1f115381545a486ecffae7e0ed",
"dt": "20241114121744",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 4,
"fisid": "99997955555555",
"dataid": 157,
"doccode": "TEST_V4vcSOQWEKS06Q",
"dt": "20241114121744",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 100,
"shift_link": 37,
"docno": 2,
"cancelid": "TEST_V4vcSOQWEKS06Q",
"qr": "https://kasa.vchasno.ua/c/TEST_V4vcSOQWEKS06Q?id=TEST_V4vcSOQWEKS06Q&date=20241114&time=12:17:44&fn=99997955555555&sm=500.50&mac=40657d5bda76650d3e80138c8e6eeb369dff20655ac0a1403f947446aae7d674",
"mac": "40657d5bda76650d3e80138c8e6eeb369dff20655ac0a1403f947446aae7d674"
},
"error_extra": null
}
```
</details>
## X-звіт (`"task": 10`) {#fr--x-report}
<details>
<summary>Деталі</summary>
**Опис відповіді**
**Структура об'єкту info для завдань 10, 11 (X\Z-звіт)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>task</td>
<td>integer</td>
<td>Тип завдання</td>
<td>✅</td>
</tr>
<tr>
<td>dt</td>
<td>string</td>
<td>Дата та час проведення чеку в форматі <em>YYYYMMDDHHMMSS</em></td>
<td>✅</td>
</tr>
<tr>
<td>fisid</td>
<td>string</td>
<td>Фіскальний номер каси</td>
<td>✅</td>
</tr>
<tr>
<td>doccode</td>
<td>string</td>
<td>Фіскальний номер чеку (для X-звіту повертається пусте значення)</td>
<td>✅</td>
</tr>
<tr>
<td>docno</td>
<td>integer</td>
<td>Порядковий номер Z-звіту</td>
<td>✅</td>
</tr>
<tr>
<td>dataid</td>
<td>integer</td>
<td>Номер сформованого пакету</td>
<td>✅</td>
</tr>
<tr>
<td>shift_link</td>
<td>integer</td>
<td>Номер зміни каси</td>
<td>✅</td>
</tr>
<tr>
<td>shift_id</td>
<td>string</td>
<td>ID зміни</td>
<td>✅</td>
</tr>
<tr>
<td>cashier</td>
<td>string</td>
<td>Інформація про касира</td>
<td>✅</td>
</tr>
<tr>
<td>isoffline</td>
<td>bool</td>
<td>В якому режимі проведено чек
<br>true - в офлайні
<br>false - в онлайні</td>
<td>✅</td>
</tr>
<tr>
<td>safe</td>
<td>float</td>
<td>Сума готівки в касі</td>
<td>✅</td>
</tr>
<tr>
<td>dtype</td>
<td>integer</td>
<td>Тип девайсу
<br>0 - тестовий
<br>1 - фіскальний</td>
<td>✅</td>
</tr>
<tr>
<td>taxes</td>
<td>array</td>
<td>Підсумки по податкам в розрізі податкових груп</td>
<td>✅</td>
</tr>
<tr>
<td>pays</td>
<td>array</td>
<td>Підсумки по видам оплат</td>
<td>✅</td>
</tr>
<tr>
<td>money</td>
<td>array</td>
<td>Підсумки по службовим внесенням\видачам</td>
<td>✅</td>
</tr>
<tr>
<td>cash</td>
<td>array</td>
<td>Підсумки по операціям видачі готівки</td>
<td>✅</td>
</tr>
<tr>
<td>summary</td>
<td>object</td>
<td>Загальні підсумки по обороту, податкам, знижкам по продажам і поверненням за зміну</td>
<td>✅</td>
</tr>
<tr>
<td>receipt</td>
<td>object</td>
<td>Підсумки по кількості чеків</td>
<td>✅</td>
</tr>
<tr>
<td>lastcheck</td>
<td>object</td>
<td>Об'єкт із даними про останній фіскальний чек в зміні.</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єктів масиву info.taxes (підсумки по податкам)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>gr_code</td>
<td>integer</td>
<td>Код податкової групи</td>
<td>✅</td>
</tr>
<tr>
<td>base_sum_p</td>
<td>float</td>
<td>База, обкладена податком і акцизом (сума) по продажам</td>
<td>✅</td>
</tr>
<tr>
<td>base_sum_m</td>
<td>float</td>
<td>База, обкладена податком і акцизом (сума) по поверненням</td>
<td>✅</td>
</tr>
<tr>
<td>tax_name</td>
<td>string</td>
<td>Назва податку</td>
<td>✅</td>
</tr>
<tr>
<td>tax_fname</td>
<td>string</td>
<td>Назва податку (повна)</td>
<td>✅</td>
</tr>
<tr>
<td>tax_lit</td>
<td>string</td>
<td>Буква, що позначає податок</td>
<td>✅</td>
</tr>
<tr>
<td>tax_percent</td>
<td>float</td>
<td>Ставка податку</td>
<td>✅</td>
</tr>
<tr>
<td>tax_sum_p</td>
<td>float</td>
<td>Сума податку по продажам</td>
<td>✅</td>
</tr>
<tr>
<td>tax_sum_m</td>
<td>float</td>
<td>Сума податку по поверненням</td>
<td>✅</td>
</tr>
<tr>
<td>ex_name</td>
<td>string</td>
<td>Назва акцизу</td>
<td>✅</td>
</tr>
<tr>
<td>ex_percent</td>
<td>float</td>
<td>Ставка акцизу</td>
<td>✅</td>
</tr>
<tr>
<td>ex_sum_p</td>
<td>float</td>
<td>Сума акцизу по продажам</td>
<td>✅</td>
</tr>
<tr>
<td>ex_sum_m</td>
<td>float</td>
<td>Сума акцизу по поверненням</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єктів info.pays/money (підсумки по видам оплат, службовим внесенням/видачам)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>integer</td>
<td>Код виду оплати</td>
<td>✅</td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>Назва виду оплати</td>
<td>✅</td>
</tr>
<tr>
<td>sum_p</td>
<td>float</td>
<td>Сума по виду оплати по продажам</td>
<td>✅</td>
</tr>
<tr>
<td>sum_m</td>
<td>float</td>
<td>Сума по виду оплати по поверненням</td>
<td>✅</td>
</tr>
<tr>
<td>round_pu</td>
<td>float</td>
<td>Сума округлень, прийнятих в більшу сторону</td>
<td>✅</td>
</tr>
<tr>
<td>round_pd</td>
<td>float</td>
<td>Сума округлень прийнятих в меншу сторону</td>
<td>✅</td>
</tr>
<tr>
<td>round_mu</td>
<td>float</td>
<td>Сума округлень виданих в меншу сторону</td>
<td>✅</td>
</tr>
<tr>
<td>round_md</td>
<td>float</td>
<td>Сума округлень виданих в меншу сторону</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єктів info.сash (підсумки по операціям видачі готівки)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>integer</td>
<td>Код виду оплати</td>
<td>✅</td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>Назва виду оплати</td>
<td>✅</td>
</tr>
<tr>
<td>sum_m</td>
<td>float</td>
<td>Сума виданої готівки</td>
<td>✅</td>
</tr>
<tr>
<td>round_mu</td>
<td>float</td>
<td>Сума комісії</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єкту info.receipt (підсумки по кількості чеків)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>count_p</td>
<td>integer</td>
<td>Кількість чеків продажу</td>
<td>✅</td>
</tr>
<tr>
<td>count_m</td>
<td>integer</td>
<td>Кількість чеків повернень</td>
<td>✅</td>
</tr>
<tr>
<td>last_docno_p</td>
<td>integer</td>
<td>Останній локальний номер чеку продажу в зміні</td>
<td>✅</td>
</tr>
<tr>
<td>last_docno_m</td>
<td>integer</td>
<td>Останній локальний номер чеку повернення в зміні</td>
<td>✅</td>
</tr>
<tr>
<td>count_transfer</td>
<td>integer</td>
<td>Кількість чеків переказу коштів</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єкту info.summary (загальні підсумки)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>base_p</td>
<td>float</td>
<td>Загальний обіг по продажам (сума всіх податкових баз по продажам)</td>
<td>✅</td>
</tr>
<tr>
<td>base_m</td>
<td>float</td>
<td>Загальний обіг по поверненням (сума всіх податкових баз по поверненням)</td>
<td>✅</td>
</tr>
<tr>
<td>taxex_p</td>
<td>float</td>
<td>Загальна сума всіх податків і акцизів по продажам</td>
<td>✅</td>
</tr>
<tr>
<td>taxex_m</td>
<td>float</td>
<td>Загальна сума всіх податків і акцизів по поверненням</td>
<td>✅</td>
</tr>
<tr>
<td>disc_p</td>
<td>float</td>
<td>Загальна знижка по всім товарним позиціям всіх чеків</td>
<td>✅</td>
</tr>
<tr>
<td>disc_m</td>
<td>float</td>
<td>Загальна націнка по всім товарним позиціям всіх чеків</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єкту info.money_transfer**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>integer</td>
<td>Код виду оплати</td>
<td>✅</td>
</tr>
<tr>
<td>name</td>
<td>string</td>
<td>Назва</td>
<td>✅</td>
</tr>
<tr>
<td>sum_p</td>
<td>float</td>
<td>Чек переказу (гроші прийшли до нас)</td>
<td>✅</td>
</tr>
<tr>
<td>sum_m</td>
<td>float</td>
<td>Чек видачі коштів при переказі (кошти покидають нас)</td>
<td>✅</td>
</tr>
<tr>
<td>commission_p</td>
<td>float</td>
<td>Комісія переказу</td>
<td>✅</td>
</tr>
<tr>
<td>commission_m</td>
<td>float</td>
<td>Комісія видачі коштів</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Структура об'єкту info.lastcheck (Об'єкт із даними про останній фіскальний чек в зміні)**
У вибірку потрапляють чеки з task: 1, 2, 14, 15, 16.
Якщо у зміні немає чеків даного типу, відповідь info.lastcheck міститиме дефолтні значення для полів: integer=0, string=''.
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>packnum</td>
<td>integer</td>
<td>Номер пакету чеку ( == info.data_id з відповіді при фіскалізації чеку)</td>
<td>✅</td>
</tr>
<tr>
<td>docnum</td>
<td>integer</td>
<td>Номер чеку з зміні (локальний номер).</td>
<td>✅</td>
</tr>
<tr>
<td>fisnum</td>
<td>string</td>
<td>Фіскальний номер чеку.</td>
<td>✅</td>
</tr>
<tr>
<td>packtype</td>
<td>integer</td>
<td>Тип завдання чеку, відповідає task.</td>
<td>✅</td>
</tr>
</tbody>
</table>
## x-звіт {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 10
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 10,
"type": 1,
"ver": 6,
"source": "",
"device": "99997655555555",
"tag": "82cbb2831eee8f0d9617996670d45d43",
"dt": "20240521162236",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 10,
"fisid": "99997655555555",
"dataid": 0,
"doccode": "",
"dt": "20240521162236",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 377.88,
"shift_link": 0,
"shift_id": "6b72e68d-e596-4e11-a190-bedbded40cc2",
"docno": 0,
"receipt": {
"count_p": 7,
"count_m": 0,
"count_14": 1,
"count_transfer": 0,
"last_docno_p": 7,
"last_docno_m": 0
},
"summary": {
"base_p": 350,
"base_m": 0,
"taxex_p": 58.31,
"taxex_m": 0,
"disc_p": 100,
"disc_m": 0
},
"taxes": [
{
"gr_code": 1,
"base_sum_p": 350,
"base_sum_m": 0,
"base_tax_sum_p": 350,
"base_tax_sum_m": 0,
"base_ex_sum_p": 0,
"base_ex_sum_m": 0,
"tax_name": "ПДВ_А",
"tax_fname": "ПДВ 20%",
"tax_lit": "А",
"tax_percent": 20,
"tax_sum_p": 58.31,
"tax_sum_m": 0,
"ex_name": "",
"ex_percent": 0,
"ex_sum_p": 0,
"ex_sum_m": 0
}
],
"pays": [
{
"type": 0,
"name": "Готівка",
"sum_p": 350,
"sum_m": 0,
"round_pu": 0,
"round_pd": 0,
"round_mu": 0,
"round_md": 0
}
],
"money": [
{
"type": 0,
"name": "Готівка",
"sum_p": 500.5,
"sum_m": 572.62,
"round_pu": 0,
"round_pd": 0,
"round_mu": 0,
"round_md": 0
}
],
"cash": [
{
"type": 2,
"name": "Картка",
"sum_p": 0,
"sum_m": 100,
"round_pu": 0,
"round_pd": 0,
"round_mu": 1.01,
"round_md": 0
}
],
"money_transfer": []
},
"error_extra": null
}
```
</details>
## Z-звіт (Закриття зміни) (`"task": 11`) {#fr--z-report}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структура відповіді аналогічна X-звіту (описано вище)
## z-звіт_закриття_зміни {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 11
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 11,
"type": 1,
"ver": 6,
"source": "",
"device": "99997655555555",
"tag": "704e5fca77edf44d2ce8e379bdd68429",
"dt": "20240131101319",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 11,
"fisid": "99997655555555",
"dataid": 202,
"doccode": "TEST_cTMHA3qiU6DDvA",
"dt": "20240131101319",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 400.5,
"shift_link": 46,
"shift_id": "6b72e68d-e596-4e11-a190-bedbded40cc2",
"docno": 46,
"receipt": {
"count_p": 1,
"count_m": 1,
"count_14": 1,
"count_transfer": 0,
"last_docno_p": 1,
"last_docno_m": 1
},
"summary": {
"base_p": 199.99,
"base_m": 199.99,
"taxex_p": 27.17,
"taxex_m": 27.17,
"disc_p": 0,
"disc_m": 0
},
"taxes": [
{
"gr_code": 3,
"base_sum_p": 99.99,
"base_sum_m": 99.99,
"base_tax_sum_p": 95.23,
"base_tax_sum_m": 95.23,
"base_ex_sum_p": 99.99,
"base_ex_sum_m": 99.99,
"tax_name": "ПДВ_Г",
"tax_fname": "ПДВ 20% + акциз 5%",
"tax_lit": "ГД",
"tax_percent": 20,
"tax_sum_p": 15.87,
"tax_sum_m": 15.87,
"ex_name": "Акцизний податок 5% Д",
"ex_percent": 5,
"ex_sum_p": 4.76,
"ex_sum_m": 4.76
},
{
"gr_code": 4,
"base_sum_p": 100,
"base_sum_m": 100,
"base_tax_sum_p": 100,
"base_tax_sum_m": 100,
"base_ex_sum_p": 0,
"base_ex_sum_m": 0,
"tax_name": "ПДВ_В",
"tax_fname": "ПДВ 7%",
"tax_lit": "В",
"tax_percent": 7,
"tax_sum_p": 6.54,
"tax_sum_m": 6.54,
"ex_name": "",
"ex_percent": 0,
"ex_sum_p": 0,
"ex_sum_m": 0
}
],
"pays": [
{
"type": 0,
"name": "Готівка",
"sum_p": 150,
"sum_m": 150,
"round_pu": 0.01,
"round_pd": 0,
"round_mu": 0.01,
"round_md": 0
},
{
"type": 2,
"name": "Картка",
"sum_p": 50,
"sum_m": 50,
"round_pu": 0,
"round_pd": 0,
"round_mu": 0,
"round_md": 0
}
],
"money": [
{
"type": 0,
"name": "Готівка",
"sum_p": 1001,
"sum_m": 500.5,
"round_pu": 0,
"round_pd": 0,
"round_mu": 0,
"round_md": 0
}
],
"cash": [
{
"type": 2,
"name": "Картка",
"sum_p": 0,
"sum_m": 100,
"round_pu": 0,
"round_pd": 0,
"round_mu": 1.01,
"round_md": 0
}
],
"money_transfer": []
},
"error_extra": null
}
```
</details>
## Національний кешбек {#fr--national-cashback}
#### Чек продажу (`"task": 1`) {#fr--nk-sale-receipt}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структуру відповіді можна подивитись у чеках без Національного кешбеку
## чек_продажу {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 1,
"receipt": {
"sum": 200.00,
"rows": [
{
"code": "00001",
"code1": "73463253",
"code2": "54321",
"code_aa": [
"XX11111111111",
"XX11111111112"
],
"disc": 0,
"name": "Продукт 1",
"cnt": 1,
"price": 200.00,
"taxgrp": "1"
}
],
"pays": [
{
"purchase_dt": "20241210135800",
"type": 2,
"sum": 200.00,
"paysys": "paysys_test",
"rrn": "rrn_test",
"oper_type": "Оплата",
"cardmask": "cardmask****test",
"term_id": "term_id",
"bank_name": "bank_name",
"bank_id": "bank_id",
"auth_code": "auth_code",
"comment": "Зразок! СЛАВА*УКРАЇНІ",
"show_additional_info": true
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 1,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "7ad71ed9dfd812f73b4c39d6067cf864",
"dt": "20241210135738",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 1,
"fisid": "99997955555555",
"dataid": 166,
"doccode": "TEST_Qbpv_J3WUwT_lQ",
"dt": "20241210135738",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 0,
"shift_link": 39,
"docno": 4,
"cancelid": "TEST_Qbpv_J3WUwT_lQ",
"qr": "https://kasa.vchasno.ua/c/TEST_Qbpv_J3WUwT_lQ?id=TEST_Qbpv_J3WUwT_lQ&date=20241210&time=13:57:38&fn=99997955555555&sm=200.00&mac=53591fe4bce3b067a06253fc787c6a3e7e0e8b8d1460ceb550612321043db92f",
"mac": "53591fe4bce3b067a06253fc787c6a3e7e0e8b8d1460ceb550612321043db92f"
},
"error_extra": null
}
```
</details>
#### Чек повернення (`"task": 2`) {#fr--nk-return-receipt}
<details>
<summary>Деталі</summary>
**Опис відповіді**
Структуру відповіді можна подивитись у чеках без Національного кешбеку
## чек_повернення {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 2,
"receipt": {
"sum": 200.00,
"rows": [
{
"purchase_receipt_fisn": "TEST_Qbpv_J3WUwT_lQ",
"purchase_rro_fisn": "99997955555555",
"purchase_receipt_dt": "20241210",
"code": "00001",
"code1": "73463253",
"code2": "54321",
"code_aa": [
"XX11111111111",
"XX11111111112"
],
"name": "Продукт 1",
"cnt": 1,
"price": 200.00,
"disc": 0,
"taxgrp": "1"
}
],
"pays": [
{
"type": 2,
"sum": 200.00,
"paysys": "paysys_test",
"rrn": "rrn_test",
"oper_type": "Оплата",
"cardmask": "cardmask****test",
"term_id": "term_id",
"bank_id": "bank_id",
"auth_code": "auth_code",
"comment": "Зразок! СЛАВА*УКРАЇНІ",
"show_additional_info": true
}
]
}
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 2,
"type": 1,
"ver": 6,
"source": "",
"device": "99997955555555",
"tag": "9e079adf787629601a69148e3a997d4b",
"dt": "20241210135937",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"task": 2,
"fisid": "99997955555555",
"dataid": 167,
"doccode": "TEST_BLDVZH08aKpjrw",
"dt": "20241210135937",
"cashier": "",
"dtype": 0,
"isprint": 0,
"isoffline": false,
"safe": 0,
"shift_link": 39,
"docno": 1,
"cancelid": "TEST_BLDVZH08aKpjrw",
"qr": "https://kasa.vchasno.ua/c/TEST_BLDVZH08aKpjrw?id=TEST_BLDVZH08aKpjrw&date=20241210&time=13:59:37&fn=99997955555555&sm=200.00&mac=df6c67395c22429e58e1e29bb76a5997c464c5bad4388c9a4bd513448074687d",
"mac": "df6c67395c22429e58e1e29bb76a5997c464c5bad4388c9a4bd513448074687d"
},
"error_extra": null
}
```
</details>
# Службові запити {#service-requests}
## Статус пРРО (`"task": 18`) {#sr--prro-status}
<details>
<summary>Деталі</summary>
`POST https://kasa.vchasno.ua/api/v3/fiscal/execute`
Хоч даний АПІ запит має шлях як у запитів фіскалізації чеків, при його обробці не виконуються запити до ДПС, лише повертається статус з сервісу Вчасно.Каса.
**Опис відповіді**
**Структура об'єкту info для завдання 18 (статус пРРО)**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>edrpou</td>
<td>string</td>
<td>ЄДРПОУ/ІПН</td>
<td>✅</td>
</tr>
<tr>
<td>fisid</td>
<td>string</td>
<td>Фіскальний номер каси</td>
<td>✅</td>
</tr>
<tr>
<td>isFis</td>
<td>integer</td>
<td>ПРРО є фіскальним
<br><strong>0</strong> - не фіскальний (тестовий)
<br><strong>1</strong> - фіскальний</td>
<td>✅</td>
</tr>
<tr>
<td>shift_status</td>
<td>integer</td>
<td>Статус зміни:
<br><strong>-1</strong> - невідомо
<br><strong>0</strong> - закрита
<br><strong>1</strong> - відкрита</td>
<td>✅</td>
</tr>
<tr>
<td>shift_dt</td>
<td>string</td>
<td>Дата та час відкриття активної зміни:
<br><strong>""</strong> - невідомо
<br><strong>інакше</strong> - дата и та час відкриття в форматі <em>YYYYMMDDHHMMSS</em></td>
<td>✅</td>
</tr>
<tr>
<td>shift_id</td>
<td>string</td>
<td>ID зміни</td>
<td>✅</td>
</tr>
<tr>
<td>online_status</td>
<td>integer</td>
<td>Статус зв'язку з ДФС:
<br><strong>0</strong> - online
<br><strong>1</strong> - offline</td>
<td>✅</td>
</tr>
<tr>
<td>sign_status</td>
<td>integer</td>
<td>Статус ЕЦП:
<br><strong>-1</strong> - невідомо
<br><strong>0</strong> - підпис не використовується
<br><strong>1</strong> - підпис є і нема попереджень
<br><strong>2</strong> - підпис є попередження
<br><strong>3</strong> - підпису нема або помилка
<br><strong></strong>зараз завжди повертається -1, інші статуси буде імплементовано пізніше</td>
<td>✅</td>
</tr>
<tr>
<td>safe</td>
<td>float</td>
<td>Сума залишку готівки в касі</td>
<td>✅</td>
</tr>
</tbody>
</table>
## статус_прро {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/fiscal/execute' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"fiscal": {
"task": 18
}
}'
```
#### Приклад успішної json відповіді
```json
{
"task": 18,
"type": 1,
"ver": 6,
"source": "",
"device": "99999955555555",
"tag": "42fff4e7e105865f7155ac6a08cf3869",
"dt": "20250321093818",
"res": 0,
"res_action": 0,
"errortxt": "",
"warnings": [],
"info": {
"edrpou": "55555555",
"fisid": "99999955555555",
"isFis": 0,
"shift_status": -1,
"shift_dt": "",
"shift_id": "6b72e68d-e596-4e11-a190-bedbded40cc2",
"online_status": 0,
"sign_status": -1,
"safe": 0
},
"error_extra": null
}
```
</details>
## Отримати JSON завдання фіскального чеку {#sr--get-check-task-json}
<details>
<summary>Деталі</summary>
`GET https://kasa.vchasno.ua/api/v3/check-task/<check_fisn>`
Запит на отримання JSON-у запиту фіскалізованого чеку. Повертає весь json body, по якому було створено чек
**check_fisn - Фіскальний номер чеку**
**Опис відповіді**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>fiscal_number</td>
<td>string</td>
<td>Фіскальний номер чеку</td>
<td>✅</td>
</tr>
<tr>
<td>task</td>
<td>object</td>
<td>boby чеку (опис вище)</td>
<td>✅</td>
</tr>
</tbody>
</table>
## отримати_json_завдання_фіскального_чеку {.tabset}
#### Приклад запиту
```json
curl --location --request GET 'https://kasa.vchasno.ua/api/v3/check-task/<check_fisn>' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN'
```
#### Приклад успішної json відповіді
```json
{
"fiscal_number": "TEST_FFFFFFFFFF",
"task": {
"tag": "af19aacc778509cb4a9fbf28ffd4a68c",
"device": "99997655555555",
"fiscal": {
"task": 1,
"cashier": "",
"receipt": {
"sum": 199.99,
"pays": [
{
"sum": 150,
"type": 0,
"change": 50,
"comment": "Зразок! Тест"
},
{
"rrn": "rrn_test",
"sum": 50,
"type": 2,
"paysys": "paysys_test",
"bank_id": "bank_id",
"comment": "Зразок! СЛАВА*УКРАЇНІ",
"term_id": "term_id",
"cardmask": "cardmask****test",
"auth_code": "auth_code",
"oper_type": "Оплата",
"commission": 1,
"show_additional_info": true
}
],
"rows": [
{
"cnt": 2,
"code": "00001",
"disc": 10,
"name": "Продукт 1",
"code1": "73463253",
"code2": "54321",
"price": 55,
"taxgrp": "4",
"code_aa": [
"XX11111111111",
"XX11111111112"
],
"comment": "Зразок! Коментар"
},
{
"cnt": 1,
"code": "00002",
"disc": -10,
"name": "Продукт 2",
"code1": "73463254",
"code2": "45667",
"price": 89.99,
"code_a": "XX11111111113",
"taxgrp": 3,
"comment": "Зразок! \"Have a good day\""
}
],
"round": 0.01,
"comment_up": "Зразок! Коментар шапки чеку",
"comment_down": "Зразок! ДЯКУЄМО за покупку"
}
},
"source": ""
}
}
```
</details>
## Отримати JSON чеку {#sr--get-check-json}
<details>
<summary>Деталі</summary>
`GET https://kasa.vchasno.ua/c/{fiscal_number}.json`
Запит на отримання фіскалізованого чеку у форматі JSON. Цей роут не працює з сервісними чеками та Z-звітом.
fiscal_number **- Фіскальний номер чеку**
Типи даних:
- кількість одиниць - decimal рядок
- вага - 3 знаки - '1.000'
- сума - decimal рядок
- відсотки - 2 знаки - '55.00'
**Опис полів:**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>fiscal_number</td>
<td>Фіскальний номер чеку</td>
</tr>
<tr>
<td>company_name</td>
<td>Назва компанії</td>
</tr>
<tr>
<td>notification_company_name</td>
<td>Назва компанії для сповіщень</td>
</tr>
<tr>
<td>company_edrpou</td>
<td>ЄДРПОУ</td>
</tr>
<tr>
<td>company_tax_number</td>
<td>ПН</td>
</tr>
<tr>
<td>shop_name</td>
<td>Назва Торгової Точки</td>
</tr>
<tr>
<td>shop_type</td>
<td>Тип Торгової Точки</td>
</tr>
<tr>
<td>shop_address</td>
<td>Адреса ТТ</td>
</tr>
<tr>
<td>rro_fiscal_number</td>
<td>Фіскальний номер ПРРО</td>
</tr>
<tr>
<td>is_offline</td>
<td>Чи видано чек в офлайні</td>
</tr>
<tr>
<td>is_test</td>
<td>Чи це тестовий чек</td>
</tr>
<tr>
<td>date_created</td>
<td>Дата створення запису чеку</td>
</tr>
<tr>
<td>check_flow</td>
<td>0-продаж,1-повернення,2-службове внесення-винесення,4-переказ коштів,7-видача коштів при переказі,14-видача готівки</td>
</tr>
<tr>
<td>check_url</td>
<td>Посилання на чек в нашому кабінеті</td>
</tr>
<tr>
<td>qr_content</td>
<td>Сформований рядок для QR коду в чеці</td>
</tr>
<tr>
<td>target_url</td>
<td>Посилання на чек в ДПС</td>
</tr>
<tr>
<td>data</td>
<td>Об'єкт з деталями по чеку</td>
</tr>
</tbody>
</table>
**Об'єкт data**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>data:cash</td>
<td>Об'єкт, опис окремо</td>
</tr>
<tr>
<td>data:check_type</td>
<td>1-продаж,2-повернення,3-сервісне внесення,4-сервісне винесення,14-видача готівки,15-переказ коштів,16-видача готівки при переказі</td>
</tr>
<tr>
<td>data:items</td>
<td>Список об'єктів, опис окремо</td>
</tr>
<tr>
<td>data:close</td>
<td>Об'єкт, опис окремо</td>
</tr>
<tr>
<td>data:pays</td>
<td>Список об'єктів, опис окремо</td>
</tr>
<tr>
<td>data:taxes</td>
<td>Список об'єктів, опис окремо</td>
</tr>
<tr>
<td>data:markups</td>
<td>Сума націнки</td>
</tr>
<tr>
<td>data:top_comment</td>
<td>Верхній коментар чеку. Список з рядків, розділених по довжині в N символів</td>
</tr>
<tr>
<td>data:last_comment</td>
<td>Верхній коментар чеку. Структура як у верхнього коментаря.</td>
</tr>
<tr>
<td>data:date</td>
<td>Дата з чеку</td>
</tr>
<tr>
<td>data:mac</td>
<td>Контрольне число чеку</td>
</tr>
<tr>
<td>data:rounding</td>
<td>Сума заокруглення</td>
</tr>
<tr>
<td>data:service_move_data</td>
<td>Об'єкт, опис окремо</td>
</tr>
<tr>
<td>data:global_discounts</td>
<td>Список, опис окремо</td>
</tr>
</tbody>
</table>
**Об'єкт data:cash - в чеці видачі готівки**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>cash_sum</td>
<td>Сума готівки</td>
</tr>
<tr>
<td>commission</td>
<td>Сума комісії</td>
</tr>
<tr>
<td>bank_id</td>
<td>Ідентифікатор єквайера торговця</td>
</tr>
<tr>
<td>term_id</td>
<td>Ідентифікатор платіжного пристрою</td>
</tr>
<tr>
<td>cardmask</td>
<td>Реквізити ЕПЗ</td>
</tr>
<tr>
<td>auth_code</td>
<td>Код авторизації</td>
</tr>
<tr>
<td>paysys</td>
<td>Назва платіжної системи</td>
</tr>
<tr>
<td>rrn</td>
<td>Ідентифікатор транзакції</td>
</tr>
</tbody>
</table>
**Об'єкт data:items**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Назва товару, послуги, або операції</td>
</tr>
<tr>
<td>tg_print</td>
<td>Позначення податку, яким обкладається товар</td>
</tr>
<tr>
<td>sum</td>
<td>Сума операції</td>
</tr>
<tr>
<td>cnt</td>
<td>Кількість</td>
</tr>
<tr>
<td>price</td>
<td>Ціна товару</td>
</tr>
<tr>
<td>code</td>
<td>Код товару в обліковій системі підприємства</td>
</tr>
<tr>
<td>code1</td>
<td>Штрихкод</td>
</tr>
<tr>
<td>code2</td>
<td>Код товарної підкатегорії згідно з УКТЗЕД</td>
</tr>
<tr>
<td>comment</td>
<td>Список рядків коментарів</td>
</tr>
<tr>
<td>excise_codes</td>
<td>Список з акцизних кодів</td>
</tr>
<tr>
<td>markup</td>
<td>Об'єкт, націнка</td>
</tr>
<tr>
<td>discount</td>
<td>Об'єкт, знижка</td>
</tr>
</tbody>
</table>
**Об'єкт data:items::markup/discount**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>sum</td>
<td>Сума операції</td>
</tr>
<tr>
<td>tg_print</td>
<td>Позначення податку</td>
</tr>
</tbody>
</table>
**Об'єкт data:close**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>sum</td>
<td>Сума чеку</td>
</tr>
<tr>
<td>to_pay</td>
<td>Сума до оплати</td>
</tr>
</tbody>
</table>
**Об'єкт data:pays**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Тип</td>
</tr>
<tr>
<td>pay_sum</td>
<td>Сума оплати</td>
</tr>
<tr>
<td>change</td>
<td>Решта</td>
</tr>
<tr>
<td>sum</td>
<td>Сума з урухуванням решти</td>
</tr>
<tr>
<td>comment</td>
<td>Коментар</td>
</tr>
<tr>
<td>bank_id</td>
<td>Ідентифікатор єквайера торговця</td>
</tr>
<tr>
<td>term_id</td>
<td>Ідентифікатор платіжного пристрою</td>
</tr>
<tr>
<td>operation</td>
<td>Тип операції(платіж/повернення/переказ тощо)</td>
</tr>
<tr>
<td>cardmask</td>
<td>Реквізити ЕПЗ</td>
</tr>
<tr>
<td>auth_code</td>
<td>Код авторизації</td>
</tr>
<tr>
<td>commission</td>
<td>Сума комісії</td>
</tr>
<tr>
<td>paysys</td>
<td>Назва платіжної системи</td>
</tr>
<tr>
<td>rrn</td>
<td>Ідентифікатор транзакції</td>
</tr>
</tbody>
</table>
**Об'єкт data:taxes**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>tax_caption</td>
<td>позначення податку</td>
</tr>
<tr>
<td>tax_percent</td>
<td>відсоток податку</td>
</tr>
<tr>
<td>tax_sum</td>
<td>сума податку</td>
</tr>
<tr>
<td>dt_caption</td>
<td>назва додаткового збору (акциз/в.збір)</td>
</tr>
<tr>
<td>dt_percent</td>
<td>відсоток додаткового збору</td>
</tr>
<tr>
<td>dt_sum</td>
<td>сума додаткового збору</td>
</tr>
</tbody>
</table>
**Об'єкт data:service_move_data**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>tag</td>
<td>I-внесення, O-видача</td>
</tr>
<tr>
<td>name</td>
<td>назва оплати</td>
</tr>
</tbody>
</table>
**Об'єкт data:global_discounts**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>sum</td>
<td>сума загальної знижки</td>
</tr>
<tr>
<td>name</td>
<td>назва загальної знижки</td>
</tr>
</tbody>
</table>
## отримати_json_чеку {.tabset}
#### Приклад запиту
```json
curl --location --request GET 'https://kasa.vchasno.ua/c/{fiscal_number}.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN'
```
#### Приклад успішної json відповіді
```json
{
"fiscal_number": "TEST_KkcD6uzuYeq08g",
"company_name": "Приватне підприємство \"Тестер\"",
"notification_company_name": "Приватне підприємство \"Тестер\"",
"company_edrpou": "55555555",
"company_tax_number": "",
"shop_name": "Тестова торгова точка",
"shop_type": "Тип Торгової Точки",
"shop_address": "Україна, м.Київ, вул. Хрещатик, 999",
"rro_fiscal_number": "99997655555555",
"is_offline": false,
"is_test": true,
"date_created": "2024-01-31T10:05:55.798668+02:00",
"check_flow": 0,
"check_url": "https://kasa.vchasno.ua/c/TEST_KkcD6uzuYeq08g",
"qr_content": "https://kasa.vchasno.ua/c/TEST_KkcD6uzuYeq08g?id=TEST_KkcD6uzuYeq08g&date=20240131&time=10:05:55&fn=99997655555555&sm=200.00&mac=160cf7bebc397274f765d73d6174b3dfc8b299786070227a31f0483a80c7d9b6",
"target_url": "https://kasa.vchasno.ua/c/TEST_KkcD6uzuYeq08g?id=TEST_KkcD6uzuYeq08g&date=20240131&time=10:05:55&fn=99997655555555&sm=200.00&mac=160cf7bebc397274f765d73d6174b3dfc8b299786070227a31f0483a80c7d9b6",
"data": {
"cash": null,
"check_type": "0",
"items": [
{
"name": "Продукт 1",
"tg_print": "В",
"sum": "110.00",
"cnt": "2.000",
"price": "55.00",
"code": "00001",
"code1": "73463253",
"code2": "54321",
"comment": [
"Зразок! Коментар"
],
"excise_codes": [
"XX11111111111",
"XX11111111112"
],
"discount": {
"sum": "10.00",
"tg_print": "В"
},
"markup": null
},
{
"name": "Продукт 2",
"tg_print": "ГД",
"sum": "89.99",
"cnt": "1.000",
"price": "89.99",
"code": "00002",
"code1": "73463254",
"code2": "45667",
"comment": [
"Зразок! \"Have a good day\""
],
"excise_codes": [
"XX11111111113"
],
"discount": null,
"markup": {
"sum": "10.00",
"tg_print": "ГД"
}
}
],
"close": {
"sum": "199.99",
"to_pay": "200.00"
},
"pays": [
{
"name": "Готівка",
"pay_sum": "200.00",
"change": "50.00",
"sum": "150.00",
"comment": [
"Зразок! Тест"
],
"bank_id": "",
"term_id": "",
"operation": "Оплата",
"oper_type": "Оплата",
"cardmask": "",
"auth_code": "",
"commission": "0.00",
"paysys": "",
"rrn": "",
"show_additional_info": true
},
{
"name": "Картка",
"pay_sum": "50.00",
"change": "0.00",
"sum": "50.00",
"comment": [
"Зразок! СЛАВА*УКРАЇНІ"
],
"bank_id": "bank_id",
"term_id": "term_id",
"operation": "Оплата",
"oper_type": "Оплата",
"cardmask": "cardmask****test",
"auth_code": "auth_code",
"commission": "1.00",
"paysys": "paysys_test",
"rrn": "rrn_test",
"show_additional_info": true
}
],
"taxes": [
{
"tax_caption": "ПДВ_Г",
"tax_percent": "20",
"tax_sum": "15.87",
"dt_caption": "Акцизний податок 5% Д",
"dt_percent": "0.05",
"dt_sum": "4.76"
},
{
"tax_caption": "ПДВ_В",
"tax_percent": "7",
"tax_sum": "6.54",
"dt_caption": "",
"dt_percent": "0.00",
"dt_sum": "0.00"
}
],
"markups": "10.00",
"top_comment": [
"Зразок! Коментар шапки чеку"
],
"last_comment": [
"Зразок! ДЯКУЄМО за покупку"
],
"date": "2024-01-31T10:05:55+02:00",
"mac": "b7c9d8cc246acaaace9d2ce1b2c375173a9262d87a34067d56a89351bd23087a",
"rounding": "0.01",
"service_move_data": null
}
}
```
</details>
## Отримати зміни по касі {#sr--get-shifts}
<details>
<summary>Деталі</summary>
`GET https://kasa.vchasno.ua/api/v3/shifts`
Запит на отримання змін по касі, ідентифікатором каси служить токен каси.
За замовчуванням повертає відсортований по date_closed список об'єктів з лімітом 100
Додаткові параметри: пагінація **page=n&limit=n** (значення n не може бути менше 1)
**Опис відповіді об'єкту items**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>Ідентифікатор зміни</td>
</tr>
<tr>
<td>date_started</td>
<td>Дата і час початку зміни</td>
</tr>
<tr>
<td>date_closed</td>
<td>Дата і час кінця зміни</td>
</tr>
<tr>
<td>cash_started</td>
<td>Залишок готівки на початку зміни</td>
</tr>
<tr>
<td>cash_current</td>
<td>Поточний залишок готівки</td>
</tr>
<tr>
<td>cash_closed</td>
<td>Залишок готівки при закритті зміни</td>
</tr>
</tbody>
</table>
## отримати_зміни_по_касі {.tabset}
#### Приклад запиту
```json
curl --location --request GET 'https://kasa.vchasno.ua/api/v3/shifts' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN'
```
#### Приклад успішної json відповіді
```json
{
"page_num": 1,
"page_size": 100,
"has_prev": false,
"has_next": false,
"items": [
{
"id": "0f9c3ef1-7f6d-d8ee-5d54-2fa68dc8b6cb",
"date_started": "2024-05-22T13:42:12+03:00",
"date_closed": "2024-05-22T13:42:52+03:00",
"cash_started": 0,
"cash_current": 5000,
"cash_closed": 5000
},
{
"id": "0f9c3eeb-91cb-340a-e3ca-e5eb65124614",
"date_started": "2024-05-22T13:41:33+03:00",
"date_closed": "2024-05-22T13:42:00+03:00",
"cash_started": 0,
"cash_current": 0,
"cash_closed": 0
}
]
}
```
</details>
## Отримати чеки по зміні {#sr--get-shift-checks}
<details>
<summary>Деталі</summary>
`GET https://kasa.vchasno.ua/api/v3/shift/checks?shift_id=<shift_id>`
Запит на отримання чеків по зміні, **shift_id - ідентифікатор зміни**
За замовчуванням повертає відсортований по date_created список об'єктів з лімітом 100
Додаткові параметри: пагінація **page=n&limit=n** (значення n не може бути менше 1)
**Опис відповіді об'єкту items**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>Ідентифікатор чеку</td>
</tr>
<tr>
<td>shift_id</td>
<td>Ідентифікатор зміни</td>
</tr>
<tr>
<td>local_number</td>
<td>Локальний номер чеку відносно зміни</td>
</tr>
<tr>
<td>fiscal_number</td>
<td>Фіскальний номер чеку</td>
</tr>
<tr>
<td>type</td>
<td>Тип чеку:
<strong>chk</strong> - чек
<strong>z_report</strong> - З-звіт
<strong>service</strong> - сервісний чек</td>
</tr>
<tr>
<td>status</td>
<td>Підтвердження фіскалізації чеку:
<br>0 - Unknown, не визначений;
<br>1 - OK, чек фіскалізовано, надано номер;
<br>-1 - ERROR_VEREFY, помилка перевірки підпису;
<br>-2 - ERROR_CHECK, помилка перевірки РРО;
<br>-3 - ERROR_SAVE, помилка запису;
<br>-4 - ERROR_UNKNOWN, загальна помилка;
<br>-5 - ERROR_TYPE, помилка типу посилки;
<br>-6 - ERROR_NOT_PREV_ZREPORT, нема Z-звіту за попередній день;
<br>-7 - ERROR_XML, невірний формат XML ( структура , фіскальний номер);
<br>-8 - ERROR_XML_DATE, невірний формат XML дата не відповідає Check.date;
<br>-9 - ERROR_XML_CHK, невірний формат XML чеку;
<br>-10 - ERROR_XML_ZREPORT, невірний формат Z-звіту;
<br>-11 - ERROR_OFFLINE_168, РРО заблокований, перевищено ліміт 168 годин офлайну;
<br>-12 - ERROR_BAD_HASH_PREV, невірний хеш попереднього чеку;
<br>-13 - ERROR_NOT_REGISTERED_RRO, не зареєстровано ПРРО;
<br>-14 - ERROR_NOT_REGISTERED_SIGNER, не зареєстрований підписант;
<br>-15 - ERROR_NOT_OPEN_SHIFT, не відкрита зміна;
<br>-16 - ERROR_OFFLINE_ID, невірний оффлайн ID</td>
</tr>
<tr>
<td>source</td>
<td>Ідентифікація джерела видачі чеку:
<br>1 - device_manager,
<br>2 - кабінет без офлайну або аварійне закриття,
<br>3 - веб API,
<br>4 - автозгенерований кабінетом,
<br>5 - мобільний додаток,
<br>6 - вебкабінет з офлайном</td>
</tr>
<tr>
<td>date_created</td>
<td>Дата створення</td>
</tr>
<tr>
<td>data_id</td>
<td>Загальний номер чеку відносно каси</td>
</tr>
<tr>
<td>check_hash</td>
<td>Хеш чеку, генерація SHA256 від xml чеку</td>
</tr>
<tr>
<td>flow</td>
<td>Який чек створено:
<br>0 - Чек продажу
<br>1 - Чек повернення
<br>2 - Службовий чек внесення коштів
<br>4 - Переказ коштів
<br>7 - Чек видачі коштів при переказі
<br>8 - Відкриття зміни
<br>9 - Чек переходу в офлайн
<br>10 - Чек виходу з офлайн
<br>12 - Запит фіскальних номерів
<br>14 - Видача готівки</td>
</tr>
<tr>
<td>safe_cash</td>
<td>Залишок готівки у касі</td>
</tr>
<tr>
<td>tag</td>
<td>Мітка завдання для ідентифікації</td>
</tr>
<tr>
<td>is_offline</td>
<td>Чи видано чек в офлайні</td>
</tr>
</tbody>
</table>
## отримати_чеки_по_зміні {.tabset}
#### Приклад запиту
```json
curl --location --request GET 'https://kasa.vchasno.ua/api/v3/shift/checks?shift_id=<shift_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN'
```
#### Приклад успішної json відповіді
```json
{
"page_num": 1,
"page_size": 100,
"has_prev": false,
"has_next": false,
"items": [
{
"id": "0f878d94-cbb2-79a3-be3b-3afebe38aa12",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 6,
"fiscal_number": "TEST_BwA32_ONSQuY-g",
"type": "z_report",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:57:14.052979+02:00",
"data_id": 19,
"check_hash": "40a965329822e629305acc6d45092f785e581fe080b44a03a2e56c0aa921612f",
"flow": null,
"safe_cash": 127700,
"tag": "78a513d91ed485c4d40c1494ce305a91",
"is_offline": false
},
{
"id": "0f878d93-8ac6-bae7-f2b8-5a6b45a339ca",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 2,
"fiscal_number": "TEST_p72E1ZvyYG7nWg",
"type": "chk",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:57:05.837365+02:00",
"data_id": 18,
"check_hash": "171c1fde6dd0e1c18fdeac1bc7853cf728bfb00fc06b15bad1d02d2902d912db",
"flow": 2,
"safe_cash": null,
"tag": "8x2pdUWGzZAWrj6ECCiMm",
"is_offline": false
},
{
"id": "0f878d92-a070-d84a-4e38-70fc8e56bbbd",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 1,
"fiscal_number": "TEST_6dBu2HbHwwXlkg",
"type": "chk",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:56:59.838403+02:00",
"data_id": 17,
"check_hash": "2e71d9890a2f42732d276e42ff6f0f655245d08da88ba7f91177722f3b8dad0b",
"flow": 2,
"safe_cash": null,
"tag": "OOFDZ1RQW2P9wPYE3WuTa",
"is_offline": false
},
{
"id": "0f878d91-94c8-71d1-2718-1fc6c2891dd0",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 2,
"fiscal_number": "TEST_3cN5dDgeeOOo4A",
"type": "chk",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:56:52.986339+02:00",
"data_id": 16,
"check_hash": "da41659c4044d14d89b7634a553c6c16981de58ab31189d5b76fd23fe6fa778c",
"flow": 0,
"safe_cash": null,
"tag": "y5aLwUMX5OTenyBV0jM0w",
"is_offline": false
},
{
"id": "0f878d90-d072-605a-975f-5ef986d6e9b5",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 1,
"fiscal_number": "TEST_EixB0aXSylhhJw",
"type": "chk",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:56:47.960189+02:00",
"data_id": 15,
"check_hash": "f13025fe880c2c9c111540df49d8a8c074d13104d2630a593aaf9d437084fc18",
"flow": 0,
"safe_cash": null,
"tag": "wX764EHfcV83mAcbuIVEr",
"is_offline": false
},
{
"id": "0f878d90-1d41-cef0-4f84-667b4f889154",
"shift_id": "0f878d90-1d33-94b3-52e1-4a1b522eb12b",
"local_number": 0,
"fiscal_number": "TEST_nUgNU8xboXD9Jw",
"type": "service",
"status": 1,
"source": 6,
"date_created": "2024-02-09T15:56:43.371487+02:00",
"data_id": 14,
"check_hash": "67e9dd0df87c1353043fed0b679817ba0579493f4aa559d399c5b538a45ec0e1",
"flow": 8,
"safe_cash": 10000,
"tag": "3627c284440d2b67a22ea580a75537bb",
"is_offline": false
}
]
}
```
</details>
## Надіслати посилання чеку на email/sms/viber {#sr--send-check-notification}
<details>
<summary>Деталі</summary>
`POST https://kasa.vchasno.ua/api/v3/notifications/checks`
Запит для надсилання посилання на чек користувачу через email, sms чи viber.
**Структура запиту**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>recipient</td>
<td>string</td>
<td>email або номер телефону отримувача</td>
<td>✅</td>
</tr>
<tr>
<td>channel</td>
<td>string</td>
<td>Канал відправки:
<br>- email
<br>- sms
<br>- viber
<br>- cascade (спробує надіслати через viber, якщо користувач не зареєстрований у viber - відправить sms)</td>
<td>✅</td>
</tr>
<tr>
<td>check</td>
<td>string</td>
<td>Фіскальний номер чеку</td>
<td>✅</td>
</tr>
</tbody>
</table>
**Опис відповіді**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Тип json даних</th>
<th>Зміст</th>
<th>Обов'язковий</th>
</tr>
</thead>
<tbody>
<tr>
<td>recipient</td>
<td>string</td>
<td>email або номер телефону отримувача</td>
<td>✅</td>
</tr>
<tr>
<td>channel</td>
<td>string</td>
<td>Канал відправки:
<br>- email
<br>- sms
<br>- viber
<br>- cascade (спробує надіслати через viber, якщо користувач не зареєстрований у viber - відправить sms)</td>
<td>✅</td>
</tr>
<tr>
<td>check_id</td>
<td>string</td>
<td>ID надісланого чеку</td>
<td>✅</td>
</tr>
</tbody>
</table>
## Приклади відправлених повідомлень {#sr--notification-examples}
**Текст sms:**
```
Chek vid {COMPANY_NAME} za {CHECK_DATE}
https://kasa.vchasno.ua/c/{CHECK_FN}
```
**Текст viber:**
```
Ви отримали фіскальний чек від {COMPANY_NAME}
https://kasa.vchasno.ua/c/{CHECK_FN}
```
## надіслати_посилання_чеку_на_email_sms_viber {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/notifications/checks' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"recipient": "RECIPIENT_EMAIL",
"channel": "email",
"check": "CHECK_FISCAL_NUMBER"
}'
```
#### Приклад успішної json відповіді
```json
{
"recipient": "RECIPIENT_EMAIL",
"channel": "email",
"check_id": "0f85b1ee-75fa-ea9f-b3dd-b4c0e88a5d64"
}
```
</details>
## Створення звіту {#sr--create-report}
<details>
<summary>Деталі</summary>
`POST https://kasa.vchasno.ua/api/v3/reports/acquire?report_type=<type>`
`report_type` приймає такі значення:
- `z_reports` - З-звіти. Фіскальні звітні чеки у вигляді таблиці (максимум 366 днів)
- `z_reports_views` - З-звіти (періодичні звіти). Фіскальні звітні чеки (максимум 366 днів)
- `z_reports_archive` - Архів z-звітів. Архів зі з-звітами (html) на кожну касу + "zreports.csv", що містить ФН каси, ФН звіту, дату звіту
- `checks` - Звіт по продажах. Всі продажі та повернення товарів (максимум 31 день, до 50 тис. чеків)
- `checks_split_products` - Звіт по чеках. Чеки продажу та повернення (максимум 31 день, до 10 тис. чеків)
- `checks_daily` - Звіт про щоденні чеки. Чеки продажу та повернення згруповані по дням (максимум 31 день)
- `checks_control_tape` - Контрольна стрічка. Основна інформація по чеках (максимум 31 день, до 300 тис. чеків)
- `checks_archive` - Контрольна стрічка + архів чеків. Копії розрахункових документів (максимум 31 день, до 1 тис. чеків)
- `z_reports_funds_circulation` - Оборот компанії. Сума всіх продажів компанії (максимум 366 днів)
- `rros_offline_time` - Лічильник offline. Кількість годин в режимі офлайн (максимум 366 днів)
Повертає `id` сформованого звіту
## створення_звіту {.tabset}
#### Приклад запиту
```json
curl --location --request POST 'https://kasa.vchasno.ua/api/v3/reports/acquire?report_type=<type>' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN' \
--data-raw '{
"date_from": "2024-04-19T09:00:00",
"date_to": "2024-04-19T13:59:59"
}'
```
#### Приклад успішної json відповіді
```json
{
"id": "0f959fa6-d771-5421-91df-389c210faa9e",
"pollingInterval": {
"milliseconds": 2000
}
}
```
</details>
## Вивантаження сформованого звіту {#sr--download-report}
<details>
<summary>Деталі</summary>
`GET https://kasa.vchasno.ua/api/v3/reports/download?id=<report_id>`
**id** - ідентифікатор сформованого звіту
**Опис відповіді**
<table>
<thead>
<tr>
<th>Ключ</th>
<th>Зміст</th>
</tr>
</thead>
<tbody>
<tr>
<td>id</td>
<td>Ідентифікатор</td>
</tr>
<tr>
<td>status</td>
<td>Статус</td>
</tr>
<tr>
<td>type</td>
<td>Тип звіту</td>
</tr>
<tr>
<td>filename</td>
<td>Назва файлу</td>
</tr>
<tr>
<td>content</td>
<td>Дані у форматі base64</td>
</tr>
</tbody>
</table>
## вивантаження_сформованого_звіту {.tabset}
#### Приклад запиту
```json
curl --location --request GET 'https://kasa.vchasno.ua/api/v3/reports/download?id=<report_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: VCHASNO_KASA_PRRO_TOKEN'
```
#### Приклад успішної json відповіді
```json
{
"id": "0f959fa6-d771-5421-91df-389c210faa9e",
"status": "done",
"type": "checks",
"filename": "Vchasno_Kasa_checks_19_04_2024_19_04_2024.xlsx",
"content": "cGxhY2Vob2xkZXI="
}
```
</details>
# Робота з помилками {#error-handling}
У відповіді на запит фіскалізації наявні поля, що відображають статус операції.
- Поле `res_action` у якому система рекомендує наступні дії дотримання транзакційної цілісності. В першу чергу, слід звертати увагу на значення цього поля і в разі отримання значення `3` - дивитися додаткові поля з кодами/текстом помилок.
- Поле `res` - це код відповіді, що дорівнює 0 у разі успішного виконання запиту. У разі помилки поле містить код помилки.
- Поле `errortxt` містить текст помилки та може містити технічну інформацію, призначене більше для логування та подальших досліджень причин.
- Об'єкт `error_extra: object | null` - опційний об'єкт, в якому повертаються деталі щодо помилки. Наприклад перелік полів, та причини, чому вони не пройшли валідацію.
Приклад помилки при запиті на фіскалізацію (наведено виключно поля, що відповідають за помилку):
```json
{
"res": 1001,
"res_action": 3,
"errortxt": "Сума всіх позицій товару відрізняється від загальної суми чеку",
"error_extra": {
"sum": 10050,
"rows_sum": 10000
}
}
```
## Перелік значень поля `res_action` {#eh--res-action-values}
- 0 - ОК, можна переходити до наступного запиту
- 1 - Помилка, запит не пройшов
Запит не виконано через “випадкові помилки” від податкової (ДПС). Рекомендується повторити запит, який не пройшов, але можна зробити й інший запит.
- 2 - Помилка + колізія
Запит було надіслано до ДПС, але відповіді не було отримано. За будь-якого наступного звернення система спочатку намагатиметься виправити колізію. Тому настійно рекомендується робити повторення вихідного запиту до тих пір, поки колізію не буде вирішено.
- 3 - Помилка, що вимагає зупинки та ручного втручання
Виникла помилка, яка може не виправитись шляхом повтору запиту.
Необхідно дослідити `res, errortxt, error_extra`, котрі містять деталі помилки.
**Повторні запити слід надсилати з параметром** **`tag`** **рівним початковому запиту/відповіді.**
## Перелік значень поля `res` {#eh--res-values}
<table>
<thead>
<tr>
<th><strong>Код</strong></th>
<th><strong>Опис</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td>1001</td>
<td>Помилка валідації вхідних даних</td>
</tr>
<tr>
<td>1006</td>
<td>Внутрішня помилка сервісу Вчасно.Каса</td>
</tr>
<tr>
<td>1011</td>
<td>Об'єкт не знайдено у базі</td>
</tr>
<tr>
<td>1013</td>
<td>Для вхідних даних не реалізовано функціонал (Not Implemented Error)</td>
</tr>
<tr>
<td>1014</td>
<td>Об'єкт вже існує у базі</td>
</tr>
<tr>
<td>1015</td>
<td>Каса зайнята попереднім запитом (Lock Error)</td>
</tr>
<tr>
<td>1016</td>
<td>Перевищено таймаут на обробку запиту</td>
</tr>
<tr>
<td>1017</td>
<td>Дію заборонено (Action not allowed error)</td>
</tr>
<tr>
<td>1019</td>
<td>Ключ ЕЦП не зареєстровано у ДПС</td>
</tr>
<tr>
<td>1020</td>
<td>Каса не активна (скасована) у ДПС</td>
</tr>
<tr>
<td>1029</td>
<td>Помилка пов'язана з підписами чи ключами ЕЦП</td>
</tr>
<tr>
<td>1062</td>
<td>Ключ ЕЦП скасовано у АЦСК</td>
</tr>
<tr>
<td>2000</td>
<td>Базова помилка. Може бути пов'язана з різними причинами (дивитися значення поля “errortxt”)</td>
</tr>
<tr>
<td>2001</td>
<td>Помилка зв'язку з ДПС</td>
</tr>
<tr>
<td>2002</td>
<td>Запит у ДПС перевищив допустимий таймаут</td>
</tr>
<tr>
<td>2003</td>
<td>Отримано код відповіді від ДПС, який вважається "випадковою помилкою"</td>
</tr>
<tr>
<td>2004</td>
<td>Отримано код критичної помилки під час роботи з ДПС, запит не може бути виконаний (точніший опис причини дивитись у полі “errortxt”)</td>
</tr>
<tr>
<td>2005</td>
<td>Каса (ПРРО) у стані колізії</td>
</tr>
<tr>
<td>2006</td>
<td>Помилка під час перевірки хешу чеку</td>
</tr>
<tr>
<td>2007</td>
<td>Необхідно відкрити зміну</td>
</tr>
<tr>
<td>2008</td>
<td>Необхідно закрити зміну</td>
</tr>
<tr>
<td>2009</td>
<td>ПРРО заблоковано</td>
</tr>
<tr>
<td>2011</td>
<td>Помилка при спробі змінити режим роботи каси</td>
</tr>
<tr>
<td>2012</td>
<td>Не можна виконати дію, оскільки останній чек було проведено з Девайс Менеджеру. Для проведення чеків з іншого джерела потрібно закрити зміну у Девайс Менеджері.</td>
</tr>
</tbody>
</table>
## HTTP статус коди {#eh--http-status-codes}
АПІ запити на фіскалізацію (`POST /api/v3/fiscal/execute`) повертають 200 OK HTTP статус також при клієнтських помилках (деталі по помилці у тілі відповіді).
Виключення:
- `401` - Помилка при авторизації, потрібно перевірити авторизаційний токен каси
- `5**` - Непередбачена помилка на стороні сервісу, потрібно повторити запит пізніше.
# Changelog {#changelog}
<table>
<thead>
<tr>
<th>Дата</th>
<th>Зміни</th>
</tr>
</thead>
<tbody>
<tr>
<td>2026-02-17</td>
<td>Додано параметр <code>shift_id</code> у відповіді на task: 0,10,11,18</td>
</tr>
<tr>
<td>2025-08-18</td>
<td>Додано можливість задавати список загальних знижок (fiscal.receipt.discounts). <br>Запит "Статус пРРО" перенесено до службових запитів.</td>
</tr>
<tr>
<td>2025-05-28</td>
<td>data.global_discounts у відповіді на json чеку</td>
</tr>
<tr>
<td>2025-05-06</td>
<td>info.lastcheck об'єкт у відповіді при запиті на x/z-звіт</td>
</tr>
<tr>
<td>2025-04-28</td>
<td>Додано можливість вивантажити архів z-звітів</td>
</tr>
<tr>
<td>2025-03-03</td>
<td>Додано нові засоби оплат</td>
</tr>
<tr>
<td>2024-12-10</td>
<td>Додано нові параметри <strong>purchase_dt</strong> в об'єкт fiscal.receipt.pays та <br><strong>purchase_receipt_dt</strong> в об'єкт fiscal.receipt.rows по програмі "Національний кешбек"</td>
</tr>
<tr>
<td>2024-11-14</td>
<td>Додано параметр bank_name в об'єкт fiscal.receipt.pays <br>Додано mac параметр у відповідь фіскалізації чеків</td>
</tr>
<tr>
<td>2024-09-23</td>
<td>Додано підтримку загальної знижки на чек. Параметри disc та disc_type в об'єкт fiscal.receipt</td>
</tr>
<tr>
<td>2024-09-03</td>
<td>Додано нові параметри purchase_receipt_fisn та purchase_rro_fisn в об'єкт fiscal.receipt для чеків повернення по програмі "Національний кешбек"</td>
</tr>
<tr>
<td>2024-04-19</td>
<td>Додано чеки передплати, післясплати. <br>Додано запити створення / вивантаження звітів</td>
</tr>
<tr>
<td>2024-02-23</td>
<td>Додано службові запити: Отримати зміни по касі, Отримати чеки по зміні</td>
</tr>
<tr>
<td>2024-02-15</td>
<td>Розширено формати поля userinfo: phone <br>Запит на отримання JSON чеку повертає <br>shop_type</td>
</tr>
<tr>
<td>2024-01-31</td>
<td>Оновлено документацію. Додано опис error_extra. Прибрано fiscal.receipt.pays.currency (параметр не оброблювався)</td>
</tr>
<tr>
<td>2023-09-18</td>
<td>Розширення виводу ЕПЗ даних</td>
</tr>
<tr>
<td>2023-07-18</td>
<td>Додано перегляд фіскалізованого JSON чеку</td>
</tr>
<tr>
<td>2023-03-16</td>
<td>Додано підтримку чеку видачі готівки (task 14)</td>
</tr>
<tr>
<td>2022-09-07</td>
<td>Внесено інформацію про автоматичне відкриття зміни разом із проведенням першого чеку (<em>Запити на фіскалізацію -> Відкриття зміни</em>)</td>
</tr>
<tr>
<td>2022-08-04</td>
<td>Initial version</td>
</tr>
</tbody>
</table>