Цей документ описує публічний JSON API сервісу ProCheckCloud для інтеграції касових, облікових та POS-систем з хмарним ПРРО.
У штатному режимі кожна фіскальна операція одразу надсилається до ДПС і повертає результат виконання. Якщо ДПС тимчасово недоступна та для конкретного ПРРО дозволений офлайн-режим, операції check, retcheck і inout можуть бути сформовані офлайн з подальшою передачею до ДПС.
Додаткові приклади запитів доступні на сторінці Приклади Cloud API.
pingstatexreportcheckretcheckinoutzreportchecks_listconfig_testingcheck_getbilling_statushttps://cprro.procheck.com.ua/
Усі запити виконуються методом POST з JSON-тілом.
POST / HTTP/1.1
Host: cprro.procheck.com.ua
Content-Type: application/json; charset=UTF-8
Authorization: Bearer <token>
Кожен ПРРО має власний токен доступу. Передавайте його в заголовку:
Authorization: Bearer <token>
Альтернативний заголовок:
X-ProCheck-Token: <token>
Не передавайте токен у URL.
У кожному розділі нижче наведено готове JSON-тіло запиту:
ping — перевірка доступності;state — стан ПРРО та зміни;xreport — X-звіт;check — чек продажу;retcheck — чек повернення;inout — службове внесення або видача;zreport — Z-звіт і закриття зміни;checks_list — реєстр документів;config_testing — тестовий режим;check_get — отримання чека;billing_status — тариф, ліміт і баланс.Загальна структура:
{
"operation": "check",
"fiscalnum": "4000000001",
"operation_id": "unique-operation-id",
"data": {}
}
Поля:
| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
operation |
string | так | Назва операції. |
fiscalnum |
string | так | Фіскальний номер ПРРО. |
operation_id |
string | так для фіскальних операцій | Унікальний ідентифікатор операції на стороні клієнта. |
data |
object | залежить від операції | Дані операції. |
Для operation_id можна використовувати UUID, номер документа з вашої системи або інший стабільний унікальний ключ.
Якщо запит не отримав відповідь через timeout, повторіть його з тим самим operation_id. Сервіс поверне результат першої обробки і не створить дубль документа.
Успішна відповідь:
{
"error": 0,
"message": "OK",
"operation": "check",
"mode": "online",
"check_data": {
"check_num": "101234567890123",
"local_check_num": "123",
"shift_num": "157956253",
"link": "https://cabinet.tax.gov.ua/cashregs/check?id=101234567890123&fn=4000000001&sm=20.00&date=20260528&time=12:34",
"text": "",
"html": ""
}
}
Головне правило:
error = 0 - операція успішна;error != 0 - операція завершилась з помилкою, текст помилки в message.Основні поля відповіді:
| Поле | Опис |
|---|---|
error |
Код результату. |
message |
Текст результату або помилки. |
operation |
Назва виконаної операції. |
mode |
Режим формування фіскального документа: online або offline. |
check_data.check_num |
Фіскальний номер документа. |
check_data.local_check_num |
Локальний номер документа. |
check_data.shift_num |
Номер зміни. |
check_data.link |
Посилання на перевірку документа в електронному кабінеті ДПС. Це саме посилання кодується в QR-коді HTML-чека. Може бути порожнім, якщо посилання не застосовується або документ сформований офлайн. |
check_data.text |
Текстове представлення звіту або документа, якщо доступне. |
check_data.html |
HTML-представлення чека для перегляду або друку, якщо доступне. Містить текст чека і QR-код посилання ДПС. |
billing_data |
Дані списання з грошового балансу ПРРО. Назви полів залишені сумісними: charged_credits означає списану суму в грн, balance_credits означає поточний баланс у грн. |
cash_data |
Дані службового внесення або видачі. |
xreport_data |
Дані X-звіту. |
zreport_data |
Дані Z-звіту. |
close_shift_data |
Дані документа закриття зміни після Z-звіту. |
tax_data |
Дані, отримані від ДПС або сформовані на основі відповіді ДПС. |
config_data |
Дані зміненого налаштування ПРРО. |
Клієнтська програма має ігнорувати невідомі додаткові поля.
Для успішних фіскальних операцій поле mode має такі значення:
online - документ переданий до ДПС та прийнятий нею під час виконання запиту;offline - документ сформований офлайн для подальшої передачі до ДПС. У такій відповіді додатково повертається блок offline_data.| Код | Опис |
|---|---|
0 |
Успіх. |
-1 |
Невідома операція. |
1 |
Помилка запиту або помилка під час виконання операції. |
2 |
Не передано fiscalnum. |
3 |
Не передано operation_id для фіскальної операції. |
4 |
Операція з таким operation_id вже виконується. |
32 |
Зміна не відкрита для операції, яка потребує відкритої зміни. |
33 |
Зміна має бути закрита перед зміною тестового режиму. |
401 |
Невірний або відсутній токен. |
402 |
Недостатньо коштів на балансі або вичерпано місячний ліміт тарифу. |
500 |
Внутрішня помилка сервісу. |
Окремі помилки можуть містити текст, отриманий від ДПС. Для користувача показуйте message.
pingПеревірка доступності сервісу.
Запит:
{
"operation": "ping"
}
Відповідь:
{
"error": 0,
"message": "OK"
}
Приклад:
curl -X POST "https://cprro.procheck.com.ua/" \
-H "Content-Type: application/json" \
-d '{"operation":"ping"}'
stateПовертає поточний стан ПРРО та зміни. Операція не створює фіскальний документ, не змінює стан ПРРО і не потребує operation_id.
Запит:
{
"operation": "state",
"fiscalnum": "4000000001"
}
Відповідь для відкритої зміни:
{
"error": 0,
"message": "OK",
"operation": "state",
"fiscalnum": "4000000001",
"state_data": {
"status": "online",
"shift_open": true,
"shift_id": "157956253",
"shift_opened_at": "2026-09-06T09:29:45+03:00",
"shift_duration": "02:30:15",
"shift_duration_seconds": 9015,
"open_shift_fiscal_num": "6962431618",
"first_local_num": 3280,
"next_local_num": 3293,
"last_fiscal_num": "6970269120",
"z_report_present": false,
"testing": true,
"operator_name": "Тестовий касир",
"state_timestamp": "2026-09-06T12:00:00+03:00"
}
}
Основні поля:
| Поле | Опис |
|---|---|
state_data.status |
Поточний режим ПРРО: online, offline або service. |
state_data.shift_open |
true, якщо зміна відкрита. |
state_data.shift_id |
Ідентифікатор поточної зміни. |
state_data.open_shift_fiscal_num |
Фіскальний номер документа відкриття саме поточної зміни. |
state_data.shift_opened_at |
Час відкриття зміни у форматі ISO 8601. Для закритої зміни повертається порожній рядок. |
state_data.shift_duration |
Тривалість відкритої зміни у форматі HH:MM:SS. |
state_data.shift_duration_seconds |
Тривалість відкритої зміни у секундах. Для закритої зміни повертається null. |
state_data.first_local_num |
Перший локальний номер документа поточної зміни. |
state_data.next_local_num |
Наступний локальний номер документа. |
state_data.last_fiscal_num |
Останній фіскальний номер документа поточної зміни. |
state_data.testing |
Ознака тестового режиму ПРРО. |
state_data.state_timestamp |
Час стану, отриманий від ДПС, у форматі ISO 8601. |
xreportОтримує X-звіт: стан поточної зміни та поточні підсумки. Операція не створює фіскальний документ і не закриває зміну.
Запит:
{
"operation": "xreport",
"fiscalnum": "4000000001"
}
Приклад:
curl -X POST "https://cprro.procheck.com.ua/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{"operation":"xreport","fiscalnum":"4000000001"}'
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "xreport",
"check_data": {
"shift_num": "157956253",
"text": "X-звіт\nФіскальний номер: 4000000001\n..."
},
"xreport_data": {
"shift_open": true,
"next_local_num": 3293,
"totals": {
"real": {
"sum": 271.0,
"orders_count": 7
},
"return": {
"sum": 0.0,
"orders_count": 0
},
"service_input": 110.0,
"service_output": 0.0,
"cash_total": 381.0
}
}
}
checkСтворює фіскальний чек продажу.
Якщо зміна закрита, сервіс відкриє її автоматично перед створенням чека.
Запит:
{
"operation": "check",
"fiscalnum": "4000000001",
"operation_id": "check-000001",
"data": {
"sales": [
{
"code": 101,
"barcode": "4820000000000",
"name": "Товар 1",
"tax": 1,
"price": 100.0,
"amount": 2
}
],
"payments": [
{
"type": 0,
"sum": 200.0
}
]
}
}
Поля товарного рядка sales:
| Поле | Тип | Опис |
|---|---|---|
code |
string/number | Код товару. |
barcode |
string | Штрихкод. |
name |
string | Назва товару або послуги. Обов'язково. |
tax |
number | Код податкової групи. |
price |
number | Ціна одиниці. |
amount |
number | Кількість. |
discount_perc |
number | Відсоток знижки. |
discount_sum |
number | Сума знижки. |
uktzed |
string | Код УКТ ЗЕД. |
excise_stamp |
string | Акцизна марка. |
unit_code |
string/number | Код одиниці виміру. |
unit_name |
string | Назва одиниці виміру. |
Поля оплати payments:
| Поле | Тип | Опис |
|---|---|---|
type |
number | Тип оплати: 0 готівка, 1 картка, 2 передплата, 3 кредит. |
sum |
number | Сума оплати. |
provided |
number | Сума, отримана від покупця. |
remains |
number | Решта. |
Якщо payments не передано, сервіс автоматично створить оплату готівкою на суму чека.
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "check",
"mode": "online",
"check_data": {
"check_num": "101234567890125",
"local_check_num": "125",
"shift_num": "157956253",
"text": "...",
"html": "<!doctype html>...",
"link": "https://cabinet.tax.gov.ua/cashregs/check?id=101234567890125&fn=4000000001&sm=20.00&date=20260528&time=12:34"
},
"billing_data": {
"charged_credits": 0.2,
"balance_credits": 2999.8
}
}
retcheckСтворює фіскальний чек повернення.
Якщо зміна закрита, сервіс відкриє її автоматично перед створенням чека повернення.
Запит:
{
"operation": "retcheck",
"fiscalnum": "4000000001",
"operation_id": "retcheck-000001",
"data": {
"retcheck_num": "101234567890125",
"sales": [
{
"code": 101,
"barcode": "4820000000000",
"name": "Товар 1",
"tax": 1,
"price": 100.0,
"amount": 1
}
],
"payments": [
{
"type": 0,
"sum": 100.0
}
]
}
}
Поле retcheck_num обов'язкове. Це фіскальний номер початкового чека продажу, за яким виконується повернення.
Товарні рядки sales і оплати payments мають таку саму структуру, як в операції check. Значення передаються без знака мінус: amount > 0, price >= 0, payments[].sum >= 0. Ознаку повернення сервіс формує автоматично.
Додаткові поля, які вказуються, якщо чек продажу був створений на іншому ПРРО:
| Поле | Тип | Опис |
|---|---|---|
orderret_cashreg_num |
string/number | Фіскальний номер ПРРО. |
orderret_date |
string | Дата чеку продажу у форматі ддммрррр. |
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "retcheck",
"mode": "online",
"check_data": {
"check_num": "101234567890130",
"local_check_num": "130",
"shift_num": "157956253",
"link": "https://cabinet.tax.gov.ua/cashregs/check?id=101234567890130&fn=4000000001&sm=20.00&date=20260528&time=12:40"
}
}
inoutСтворює службове внесення або службову видачу коштів.
Якщо зміна закрита, сервіс відкриє її автоматично.
Правило:
sum > 0 - службове внесення;sum < 0 - службова видача.Запит:
{
"operation": "inout",
"fiscalnum": "4000000001",
"operation_id": "inout-000001",
"data": {
"sum": 500.0
}
}
Відповідь:
{
"error": 0,
"message": "OK",
"operation": "inout",
"mode": "online",
"check_data": {
"check_num": "101234567890124",
"local_check_num": "124",
"shift_num": "157956253",
"link": "https://cabinet.tax.gov.ua/cashregs/check?id=101234567890124&fn=4000000001&sm=500.00&date=20260528&time=12:30"
},
"cash_data": {
"cash_sum": 500.0,
"cash_in": 500.0,
"cash_out": 0.0
}
}
zreportСтворює Z-звіт і після нього закриває зміну.
Запит:
{
"operation": "zreport",
"fiscalnum": "4000000001",
"operation_id": "zreport-2026-05-28"
}
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "zreport",
"check_data": {
"check_num": "101234567890200",
"local_check_num": "200",
"shift_num": "157956253"
},
"zreport_data": {
"check_num": "101234567890200",
"local_check_num": "200",
"error_code": 0,
"error_text": "",
"totals": {
"real": {
"sum": 271.0,
"orders_count": 7
},
"return": {
"sum": 0.0,
"orders_count": 0
},
"service_input": 110.0,
"service_output": 0.0,
"cash_total": 381.0
}
},
"close_shift_data": {
"check_num": "101234567890201",
"local_check_num": "201",
"error_code": 0,
"error_text": ""
}
}
Поле zreport_data.totals містить підсумки зміни, за якими сформовано Z-звіт. Структура підсумків така сама, як у xreport_data.totals.
checks_listПовертає список документів ПРРО за період. У відповідь можуть входити чеки продажу, чеки повернення, службові внесення/видачі та Z-звіти.
Операція не створює фіскальний документ і не потребує operation_id.
Запит:
{
"operation": "checks_list",
"fiscalnum": "4000000001",
"date_from": "2026-05-31",
"date_to": "2026-05-31"
}
Поля запиту:
| Поле | Тип | Обов'язкове | Опис |
|---|---|---|---|
date_from |
string | так | Початок періоду. Можна передати YYYY-MM-DD, DD.MM.YYYY або ISO datetime. |
date_to |
string | так | Кінець періоду. Якщо передана тільки дата, сервіс використовує кінець дня. |
include_shift_documents |
boolean | ні | Якщо true, сервіс поверне всі документи змін, що потрапили в період, навіть якщо дата самого документа виходить за межі date_from/date_to. За замовчуванням false. |
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "checks_list",
"fiscalnum": "4000000001",
"date_from": "2026-05-31T00:00:00+03:00",
"date_to": "2026-05-31T23:59:59.999000+03:00",
"documents": [
{
"check_num": "6962431618",
"local_check_num": 3283,
"shift_id": 157956253,
"open_shift_fiscal_num": "6962431618",
"doc_class": "Check",
"doc_type": "OpenShift",
"doc_subtype": "CheckGoods",
"operation_type": "check",
"date_time": "2026-05-27T21:02:07",
"revoked": false,
"storned": false
}
],
"documents_count": 1,
"date_filter_applied": true
}
Основні поля документа:
| Поле | Опис |
|---|---|
check_num |
Фіскальний номер документа у ДПС. |
local_check_num |
Локальний номер документа у зміні. |
shift_id |
Ідентифікатор зміни. |
doc_class, doc_type, doc_subtype |
Класифікація документа з боку ДПС. |
operation_type |
Узагальнений тип для клієнта: check, retcheck, inout, zreport або document. |
date_time |
Дата і час документа. |
revoked, storned |
Ознаки скасування або сторнування, якщо їх повернула ДПС. |
config_testingПеремикає тестовий режим ПРРО.
Для читання поточного тестового режиму передайте data.action=get:
{
"operation": "config_testing",
"fiscalnum": "4000000001",
"data": {"action": "get"}
}
Відповідь: {"error": 0, "config_data": {"testing": true}}. Читання не змінює
конфігурацію; воно доступне також під час відкритої зміни.
Токен має належати цьому ПРРО. Якщо конфігурації немає, повертається помилка, а не testing=false.
Для зміни тестового режиму клієнтським токеном ПРРО зміна має бути закрита. Якщо зміна відкрита, сервіс поверне помилку і режим не буде змінено.
Операція не створює фіскальний документ і не потребує operation_id.
Увімкнути тестовий режим:
{
"operation": "config_testing",
"fiscalnum": "4000000001",
"data": {
"testing": true
}
}
Вимкнути тестовий режим:
{
"operation": "config_testing",
"fiscalnum": "4000000001",
"data": {
"testing": false
}
}
Успішна відповідь:
{
"error": 0,
"message": "OK",
"operation": "config_testing",
"fiscalnum": "4000000001",
"config_data": {
"fiscalNum": "4000000001",
"testing": true
}
}
Приклад помилки, якщо зміна відкрита:
{
"error": 33,
"message": "Зміна має бути закрита перед зміною режиму тестування",
"operation": "config_testing"
}
check_getПовертає представлення чека за його фіскальним номером. Відповідь завжди містить структурований receipt_data з товарними рядками, оплатами і податками.
Операція не створює фіскальний документ і не потребує operation_id.
Запит:
{
"operation": "check_get",
"fiscalnum": "4000000001",
"check_num": "6962431618"
}
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "check_get",
"fiscalnum": "4000000001",
"check_num": "6962431618",
"check_data": {
"check_num": "6962431618",
"local_check_num": "3283",
"shift_num": "157956253",
"link": "https://cabinet.tax.gov.ua/cashregs/check?id=6962431618&fn=4000000001&sm=20.00&date=20260528&time=12:34",
"text": "...",
"html": "<!doctype html>..."
},
"receipt_data": {
"check_num": "6962431618",
"total_sum": 20.0,
"discount_sum": 0.0,
"sales": [
{
"code": "101",
"barcode": "4820000000000",
"name": "Товар 1",
"amount": "2",
"price": "10.00",
"cost": "20.00",
"letters": "А",
"discount_sum": "0"
}
],
"payments": [
{"type": "0", "name": "Готівка", "sum": 20.0, "provided": 20.0, "remains": 0.0}
],
"taxes": [
{"type": "0", "name": "ПДВ", "letter": "А", "percent": 20.0, "turnover": 16.67, "source_sum": 20.0, "sum": 3.33}
],
"link": "https://cabinet.tax.gov.ua/cashregs/check?..."
}
}
Якщо чек або конфігурацію ПРРО не знайдено, команда повертає error: 404. Якщо ДПС тимчасово недоступна, повертається error: 503 з retryable: true.
billing_statusПовертає поточний стан тарифу, місячного ліміту і балансу ПРРО.
Операція не створює фіскальний документ і не потребує operation_id.
Запит:
{
"operation": "billing_status",
"fiscalnum": "4000000001"
}
Скорочена відповідь:
{
"error": 0,
"message": "OK",
"operation": "billing_status",
"fiscalnum": "4000000001",
"billing_data": {
"tariff_id": "mini",
"tariff_status": "active",
"monthly_limit": 500,
"usage_month": "2026-06",
"billable_checks": 123,
"included_checks": 120,
"overage_checks": 3,
"balance_credits": 2997.25,
"over_limit_mode": "balance",
"over_limit_price_uah": 0.1,
"tariff_started_at": "2026-06-13T12:00:00+03:00",
"tariff_paid_until": "2026-07-13T12:00:00+03:00",
"pending_tariff_id": "pro",
"pending_monthly_limit": 20000,
"pending_over_limit_mode": "block",
"pending_over_limit_price_uah": 0.03,
"pending_tariff_effective_at": "2026-07-13T12:00:00+03:00",
"pending_tariff_paid_until": "2026-08-13T12:00:00+03:00"
}
}
Поля billable_checks, included_checks і overage_checks належать до поточного usage_month.
https://cprro.procheck.com.ua/.operation_id.operation_id.state, щоб перевірити стан ПРРО та зміни. Використовуйте xreport, коли разом зі станом потрібні поточні підсумки зміни.zreport зміна буде закрита.