/v1/version Версія збірки сервісу
Відповіді
-
200Версія збірки.Поле Тип Обовʼязковий Опис version string так Тег збірки: dev для локальної збірки, номер версії для релізу.
OpenAPI v0.11.0
REST API сервісу PRRO.cloud: реєстрація чеків, зміни, білінг і вебхуки. Джерело правди — специфікація OpenAPI 3.1. Сайт генерує цю сторінку зі специфікації під час збірки, тому довідник збігається з контрактом.
https://api.prro.cloud Усі шляхи на цій сторінці вказано від базової адреси. Тіла запитів і відповідей — JSON (application/json) у кодуванні UTF-8.
Сервіс автентифікує машинні запити за Bearer-токеном (JWT) із довгим строком дії. Токен створюють у кабінеті PRRO.cloud, у розділі токенів. Кабінет показує значення токена лише один раз, тому збережіть його одразу. Надсилайте токен у заголовку Authorization: Bearer <token>. Необмежений токен діє на всі каси клієнта. Обмежений токен діє лише на каси зі свого переліку. Якщо токен відкликали в кабінеті, сервіс перестає приймати його протягом приблизно 2 секунд. Запит для перевірки токена:
curl -H "Authorization: Bearer $PRRO_TOKEN" \
"$BASE_URL/v1/whoami" Один запит повертає id каси. Ще три запити виконують фіскальний цикл і реєструють перший чек. На касі в тестовому режимі (test) цей цикл безкоштовний: ДПС перевіряє документи, але не фіскалізує їх. Для Go той самий цикл є в бібліотеці prro-go. Бібліотека сама створює ключі ідемпотентності, повторює запити і перевіряє підпис вебхуків.
Відповідь містить каси, на які діє токен. Значення id використовують як cash_register_id у запиті на чек і як {id} у шляхах /cash-registers/{id}. Фіскальний номер каси тут не підходить. Цей запит потрібен лише один раз: збережіть id у налаштуваннях своєї програми.
curl -H "Authorization: Bearer $PRRO_TOKEN" \
"$BASE_URL/v1/cash-registers" Цей крок потрібен лише в режимі змін shift_mode: manual. В автоматичному режимі змін перший чек відкриває зміну.
curl -X POST "$BASE_URL/v1/cash-registers/$REGISTER_ID/shifts" \
-H "Authorization: Bearer $PRRO_TOKEN" \
-H "Idempotency-Key: shift-2026-07-14" \
-H "Content-Type: application/json" \
-d '{"cashier": "Каса самообслуговування"}' Суми — десяткові рядки, а не числа. Типовий режим відповіді — sync. У цьому режимі відповідь одразу містить фіскальний номер чека і посилання на чек для покупця.
curl -X POST "$BASE_URL/v1/receipts" \
-H "Authorization: Bearer $PRRO_TOKEN" \
-H "Idempotency-Key: order-10412" \
-H "Content-Type: application/json" \
-d '{
"cash_register_id": "'$REGISTER_ID'",
"type": "sale",
"items": [
{ "name": "Кава американо", "quantity": "1", "price": "65.00", "tax_letters": "А" }
],
"payments": [
{ "type": "card", "sum": "65.00" }
]
}' Одна операція створює Z-звіт і закриває зміну. Якщо налаштувати shift_close_times каси, сервіс закриває зміну автоматично. Поле result.zreport.totals містить підсумки Z-звіту — ті самі суми, що в документі, який отримала ДПС: продажі й повернення за формами оплати та податковими ставками, службові внесення і службові видачі.
curl -X DELETE "$BASE_URL/v1/cash-registers/$REGISTER_ID/shifts/current" \
-H "Authorization: Bearer $PRRO_TOKEN" \
-H "Idempotency-Key: close-2026-07-14" Цю документацію можна не читати вручну. Дайте її своєму ШІ-асистенту (Claude, ChatGPT, Copilot тощо), і асистент напише код для роботи з API. Для цього сайт публікує машиночитані версії за конвенцією llms.txt:
— індекс для ШІ-агентів: короткий опис сервісу і посилання на машиночитані документи. Почніть із цього файла.
— уся ця сторінка одним markdown-файлом: автентифікація, швидкий старт, чек для покупця, вебхуки, повний довідник маршрутів і схем. Файл вміщується в контекст моделі. Для написання коду іншого джерела не потрібно.
— специфікація OpenAPI 3.1, з якої згенеровано довідник. Це джерело правди для кодогенерації та валідації.
Сайт генерує всі три файли під час збірки з тих самих джерел, що й цю сторінку. Тому файли збігаються зі сторінкою.
Заголовок Idempotency-Key обовʼязковий для всіх фіскальних операцій. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. Тому повторний запит після помилки мережі безпечний. Для того самого ключа з іншою операцією сервіс повертає 409.
Типовий режим sync чекає на результат до 30 секунд. Якщо за цей час результату немає, сервіс повертає 202 і завдання. Режим async повертає 202 одразу. Результат завдання повертає GET /v1/tasks/{id}, а також вебхук. Режим задають параметром ?mode= або полем mode у тілі запиту. Параметр має пріоритет над полем.
Усі суми — десяткові рядки ("259.90"), ніколи не числа з рухомою комою. Кількість має до 3 знаків після коми, ціна — до 2. Суми тарифікації (GET /v1/billing/usage) — копійки десятковим рядком.
Сервіс ігнорує поле тіла запиту, якого немає в специфікації, на будь-якому рівні. Заголовок відповіді X-Unknown-Fields містить шляхи цих полів через кому, наприклад discount, items[0].unit. Якщо невідомих полів немає, заголовка немає.
Сервіс повертає помилку в конверті {code, message, details}. code — стабільний машинний код: програма клієнта обробляє помилку за цим кодом. message — текст для людини. Не використовуйте цей текст у логіці програми. 422 означає, що запит не пройшов валідацію або завдання завершилося помилкою. Приклади: немає відкритої зміни, ДПС відхилила документ. Завдання, яке завершилося помилкою, містить поле fault: code (dps.*, fiscal.*, return.*, storno.*, signer.*, state.*) і class — дію, яка може виправити помилку.
Сервіс працює за передплатою. Коли баланс стає нижчим за поріг, сервіс відхиляє нові чеки з 402, доки клієнт не поповнить баланс. Операції зі змінами доступні. Коли баланс наближається до порога, сервіс надсилає попередження: вебхук client.balance_low і лист на адресу сповіщень клієнта. Поле data події містить баланс, поріг, ціну чека і кількість чеків до порога.
Чек може надійти до сервісу пізніше за фактичний продаж. Приклад: автомат годину тримав замовлення в черзі. Тоді надішліть поле sold_at. Сервіс друкує в чеку рядок «Продаж від 03.09.2026 18:11» перед приміткою з comment. sold_at — не фіскальний час чека. ДПС приймає час чека лише в межах приблизно однієї хвилини від свого часу. Тому фіскальний час чека — час надсилання. Для часу в майбутньому або часу, старшого за 31 день, сервіс повертає 422.
payments[].type — форма оплати з переліку закону: cash, card, certificate, bank_transfer, direct_debit. Фіскальний код і назву форми оплати визначає сервіс. Поле payments[].means задає точнішу назву, яку сервіс друкує в чеку. Приклади: «ПЕРЕКАЗ З КАРТКИ», «ТАЛОН», сертифікат мережі. Фіскальний код форми оплати і далі визначає type. Тому залишок готівки і підсумки Z-звіту збігаються з чеком. Для cash сервіс не приймає means. Реквізити еквайрингу (ідентифікатор і податковий номер еквайра, платіжний пристрій, код авторизації, комісія) — у payments[].card.
Запит type: return посилається на початковий чек через original.fiscal_number. Якщо сервіс створив початковий чек, сервіс перевіряє повернення за цим чеком. Початковий чек має бути чеком продажу в тому самому режимі: тестовому або фіскальному. Сторно не має скасовувати цей чек. Сума всіх повернень за чеком не може перевищувати суми продажу до заокруглення. Якщо умову не виконано, завдання завершується помилкою з кодом return.*, і сервіс не реєструє чек. Початковий чек з іншої каси сервіс шукає за original.register_fiscal_number. Якщо початкового чека в сервісі немає, сервіс приймає повернення без перевірки. Тоді результат містить result.receipt.original.verified: false.
Запит type: storno містить лише original.fiscal_number. Для позицій, оплат і сум у запиті сторно сервіс повертає 422. Сторно може скасувати лише останній документ каси. Цей документ має бути чеком продажу або повернення, який створив сервіс і який сторно ще не скасовувало. Інакше завдання завершується помилкою з кодом storno.*. Щоб скасувати чек, після якого є інші документи, зареєструйте повернення. В офлайн-сесії сервіс не реєструє сторно: код state.storno_needs_dps. Сторно змінює підсумки зміни і залишок готівки на суми скасованого чека у зворотному напрямку.
ДПС приймає лише це кодування. Символ поза кодуванням не спричиняє помилки: сервіс замінює символ сам. Поширені символи мають заміну: апостроф ʼ → ’, × → x, ₴ → грн, мінус → -. Знаки з діакритикою та індекси сервіс спрощує: é → e, ² → 2, ½ → 1/2. Літери інших абеток сервіс замінює на ?. Емодзі та невидимі символи сервіс видаляє. Текст у межах кодування сервіс не змінює. Надрукований текст є в receipt.registered і на receipt_url.
Відповідь на запит на чек містить не лише фіскальний номер. Поле result.receipt містить також два посилання: копію чека в сервісі і цей самий чек в Електронному кабінеті платника податків ДПС. Надішліть ці посилання покупцю листом або в месенджері, або покажіть QR-код на екрані каси. Створювати зображення чека самостійно не потрібно.
{
"task_id": "0197a2c1-…",
"type": "receipt",
"status": "succeeded",
"result": {
"receipt": {
"document_id": "0197a2c3-…",
"local_number": 42,
"fiscal_number": "7466800082",
"register_fiscal_number": "4001063533",
"receipt_url": "https://r.prro.cloud/aB3xK9pQvT2mNr7c",
"tax_url": "https://cabinet.tax.gov.ua/cashregs/check?fn=4001063533&id=7466800082&date=20260803&time=010754&sm=65.00"
}
}
} Сторінка відкривається без авторизації: доступ дає 16-символьний код у посиланні, як паперовий чек у кишені. Формат задає параметр ?format=. html (типовий) повертає сторінку чека. png повертає зображення чека шириною 576 px із QR-кодом: це ширина стрічки 80 мм для термопринтера. qr повертає PNG із QR-кодом адреси сторінки. Сторінка показує лише чек для людини: без XML, CMS і квитанцій ДПС. Для невідомого коду і для документа, який сервіс не показує, сервіс повертає однаковий 404.
Посилання відкриває цей чек в Електронному кабінеті платника податків ДПС. Там покупець перевіряє чек без довіри до сервісу. Підтвердження фіскалізації — fiscal_number і tax_url. receipt_url лише показує копію чека.
Документ з offline: true має фіскальний номер, який сервіс обчислив локально (<sid>.<n>.<crc>). Поля tax_url немає, доки ДПС не отримала пакет офлайн-сесії. receipt_url працює одразу: сервіс показує копію зі свого журналу.
Коли ДПС відхиляє пакет офлайн-сесії, сервіс призупиняє надсилання. Нові документи каси сервіс відхиляє з кодом state.offline_backlog_undeliverable. Стан каси містить час паузи і помилку ДПС: offline_session.submit_paused_at і offline_session.submit_fault. Виправте причину і відновіть надсилання (.../offline-session/retry). Якщо ДПС відхиляє сесію постійно, відмовтеся від сесії (.../offline-session/abandon). Сервіс позначає статусом abandoned документи, яких ДПС не отримала. Фіскальних номерів цих документів у ДПС немає, поля tax_url немає, а receipt_url повертає 404. Перелік цих документів є в результаті завдання і в події register.offline_abandoned. Клієнт вирішує, чи реєструвати ці чеки знову. Якщо ДПС обмежує частоту запитів (HTTP 429), сервіс не призупиняє надсилання, а надсилає пакет пізніше.
Фіскальний номер каси, у якій сервіс створив документ. У чеку це «ФН ПРРО». Поле є завжди. На відміну від fiscal_number, цей номер однаковий в онлайн-режимі і в офлайн-сесії. За цим номером клієнт зіставляє свої записи з касою. Брати номер з параметра fn= у tax_url не потрібно: в офлайн-документа поля tax_url немає.
Z-звіт, документ відкриття зміни і документ закриття зміни не мають друкованої форми. Їхні DocResult не містять посилань. Власну форму Z-звіту будують з його totals.
Сервіс зберігає код разом із документом і не обчислює код заново. Посилання, які покупці вже отримали, працюють і далі. Пошукові системи не індексують сторінку чека.
Вебхук замінює опитування завдань. Зареєструйте вебхук через POST /v1/webhooks, і сервіс доставлятиме події у ваш приймач.
task.completed — завдання завершилося успішно. task.failed — завдання завершилося помилкою. receipt.registered — сервіс зареєстрував чек будь-якого типу (подробиці нижче).
shift.opened і shift.closed — зміну відкрито або закрито (схема ShiftEventData). shift.closed містить Z-звіт із підсумками (data.zreport). Сервіс надсилає shift.closed на кожне закриття зміни. Зміну також може закрити чек, якщо попереднє закриття не завершилося, або автоматичне виправлення розбіжності з ДПС.
key.expiring — строк дії сертифіката ключа закінчується протягом 30 днів. Сервіс надсилає цю подію раз на добу. register.offline — каса перейшла в офлайн-режим. register.online — каса повернулася в онлайн-режим. register.offline_limit — каса досягла законодавчої межі офлайн-режиму: 36 годин на офлайн-сесію, 168 годин на місяць. register.offline_abandoned — від офлайн-сесії відмовилися. Поле data містить документи, яких ДПС не отримала. register.remediated — сервіс автоматично виправив розбіжність із ДПС. register.needs_attention — сервіс не може виправити розбіжності автоматично. Потрібне рішення людини.
client.balance_low — баланс наближається до порога. Ця подія належить клієнту, а не касі. Тому подія не містить cash_register_id і sequence.
Сервіс надсилає receipt.registered на кожен зареєстрований чек: продаж, повернення, сторно, службове внесення і службову видачу, онлайн і в офлайн-сесії. Подія надходить також для чеків, які касир зареєстрував у кабінеті PRRO.cloud, а не через API. Поле data містить чек у тому вигляді, у якому його отримала ДПС: позиції, оплати, податки, суму і заокруглення, касира, номери, зміну, початковий чек повернення або чек, який скасовує сторно, receipt_url і tax_url. Сума сторно — 0.00. В офлайн-чеку поля tax_url немає, доки ДПС не отримала чек. Поле source вказує джерело запиту на чек: api або cabinet. Для cabinet поле user_id містить обліковий запис кабінету. Опис полів — схема ReceiptRegisteredData (розділ «Схеми даних»). Тому програмі обліку не потрібно опитувати журнал, щоб бачити чеки з кабінету.
Сервіс доставляє подію запитом POST на URL приймача. Тіло запиту: {delivery_id, event, attempt, sequence, occurred_at, data}. data — дані події. sequence — номер події в межах каси. Події клієнта не мають sequence.
Заголовок X-Signature: sha256=<hex> містить HMAC-SHA256 тіла запиту. Сервіс обчислює підпис із секретом вебхука. Якщо поля secret у запиті немає, сервіс створює секрет. Сервіс повертає секрет лише один раз, у відповіді на створення вебхука. Перевіряйте підпис до обробки події.
Сервіс гарантує доставку «щонайменше один раз». Приймач має відкидати повторні доставки за delivery_id. Після невдалої спроби сервіс виконує повторну спробу. Коли спроби закінчуються, доставка отримує статус dead. Доставку зі статусом dead можна повторити через replay.
Сервіс зберігає доставки зі статусом delivered 30 днів, доставки зі статусом dead — 14 днів від останньої спроби. Потім сервіс видаляє доставки з історії. Replay доступний, поки доставка є в історії. Тому повторити доставку dead можна протягом 14 днів.
Сервіс доставляє події однієї каси по одній і за порядком. Якщо приймач не прийняв подію, сервіс доставляє наступні події без затримки. Після повторної спроби або replay ця подія може надійти пізніше за наступні. Упорядковуйте події каси за sequence. Номер зростає, але може мати пропуски. Поточний стан каси повертає GET /v1/cash-registers/{id}.
Поле last_error в історії доставок містить результат останньої невдалої спроби: код і початок відповіді приймача або причину помилки зʼєднання. Приклад — помилка TLS: строк дії сертифіката закінчився, сертифікат іншого домену, звичайний HTTP на адресі https.
Максимум — кількість кас клієнта плюс один. Призупинені вебхуки входять у цю кількість, видалені — ні. Понад максимум POST /v1/webhooks повертає 409 з кодом webhook_limit_reached. Поле details містить limit і used. GET /v1/webhooks повертає ті самі limit і used, тому клієнт знає максимум заздалегідь.
active: false призупиняє доставку. Черга доставок зберігається. Після відновлення (active: true) сервіс доставляє події з черги. Видалення вебхука переводить недоставлені події в статус dead. Тому на час ремонту приймача призупиніть вебхук, а не видаляйте його.
Події, які має побачити людина, сервіс надсилає також листом на адресу сповіщень клієнта: client.balance_low, key.expiring, register.needs_attention і поповнення балансу. Адресу сповіщень і окремі листи налаштовують у кабінеті. Ці налаштування не змінюють доставки вебхуків. Покупцю сервіс листів не надсилає. Копію чека покупцю надсилає клієнт.
POST https://example.com/prro-hook
X-Signature: sha256=2b7e9f…
{
"delivery_id": "0197a2c4-…",
"event": "task.completed",
"attempt": 1,
"sequence": 17,
"occurred_at": "2026-07-14T10:15:04Z",
"data": { "task_id": "0197a2c1-…", "status": "succeeded" }
} Згенеровано зі специфікації OpenAPI. Маршрути кабінету (сесійна cookie кабінету) сюди не входять. Клієнти працюють лише з машинним API.
/v1/version Версія збірки сервісу
200 Версія збірки. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| version | string | так | Тег збірки: dev для локальної збірки, номер версії для релізу. |
/v1/whoami Bearer Клієнт і дозволи токена
200 Клієнт, дозволи (scopes) і каси токена. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| client_id | string (uuid) | так | Клієнт, від імені якого діє токен. |
| scopes | array<string> | так | Дозволи токена. |
| all_cash_registers | boolean | так | true: токен необмежений, він діє на всі каси клієнта, поточні й майбутні. false: токен обмежений, він діє лише на каси з cash_registers. |
| cash_registers | array<string (uuid)> | — | Перелік uuid кас, на які діє обмежений токен. Поля немає, якщо all_cash_registers = true. |
| jti | string (uuid) | так | Ідентифікатор токена. За цим ідентифікатором токен відкликають у кабінеті. |
| expires_at | string (date-time) | — | Час, коли строк дії токена закінчується. Поля немає, якщо токен безстроковий. |
/v1/system/dps Bearer Поточний режим роботи з ДПС (онлайн/офлайн)
Режим, у якому сервіс працює з ДПС зараз. Маршрут доступний для будь-якого машинного токена.
/v1/receipts Bearer Зареєструвати чек
Типи чеків: - sale — продаж - return — повернення - storno — сторно попереднього чека - service_in — службове внесення - service_out — службова видача Сервіс виконує повний фіскальний цикл. Сервіс присвоює локальний номер, створює XML за схемою check01 і підписує його КЕП (CAdES-T). Потім сервіс надсилає документ до ДПС і отримує квитанцію. Режим відповіді sync (типовий) чекає на результат до 30 секунд. Якщо за цей час результату немає, сервіс повертає 202 і завдання. Режим async повертає 202 одразу. Заголовок Idempotency-Key обов'язковий. Повторний запит із тим самим ключем повертає те саме завдання. Сервіс не реєструє другий чек.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| Idempotency-Key header | string | так | Ключ операції. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. |
| mode query | string | — | Режим відповіді. Параметр має пріоритет над полем mode у тілі запиту. sync (типовий) чекає на результат до 30 секунд. async одразу повертає 202 і завдання. |
/v1/tasks/{id} Bearer Статус і результат завдання
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор завдання з відповіді на фіскальну операцію. |
/v1/cash-registers Bearer Каси, доступні токену
Для необмеженого токена сервіс повертає всі каси клієнта. Для обмеженого токена сервіс повертає лише каси цього токена. Значення id використовують як cash_register_id і як {id} в інших маршрутах. Поточний стан каси: GET /v1/cash-registers/{id}.
200 Каси токена, від найстарішої. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_registers | array<CashRegisterListItem> | так | Каси токена, від найстарішої. |
/v1/cash-registers/{id} Bearer Стан каси
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
/v1/cash-registers/{id}/shifts Bearer Відкрити зміну
Завдання, режим відповіді та Idempotency-Key працюють так само, як у POST /v1/receipts.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
| Idempotency-Key header | string | так | Ключ операції. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. |
| mode query | string | — | Режим відповіді. Параметр має пріоритет над полем mode у тілі запиту. sync (типовий) чекає на результат до 30 секунд. async одразу повертає 202 і завдання. |
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cashier | string | — | Ім'я касира. Сервіс друкує його в документі відкриття зміни. |
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
/v1/cash-registers/{id}/shifts/current Bearer Закрити поточну зміну
Операція створює Z-звіт і документ закриття зміни.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
| Idempotency-Key header | string | так | Ключ операції. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. |
| mode query | string | — | Режим відповіді. Параметр має пріоритет над полем mode у тілі запиту. sync (типовий) чекає на результат до 30 секунд. async одразу повертає 202 і завдання. |
/v1/cash-registers/{id}/offline-session/close Bearer Надіслати й закрити офлайн-сесію зараз
Сервіс надсилає пакети офлайн-сесії до ДПС і закриває сесію. Сервіс не чекає на фонове надсилання. Каса повертається в онлайн-режим, лише коли ДПС отримала всі документи сесії. Якщо ДПС недоступна, сервіс відхиляє операцію з кодом state.offline_close_needs_dps. У цьому випадку сервіс надсилає й закриває сесію автоматично, коли ДПС знову доступна.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
| Idempotency-Key header | string | так | Ключ операції. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. |
| mode query | string | — | Режим відповіді. Параметр має пріоритет над полем mode у тілі запиту. sync (типовий) чекає на результат до 30 секунд. async одразу повертає 202 і завдання. |
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cashier | string | — | Ім'я касира. Сервіс друкує його в документі закриття офлайн-сесії. |
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
/v1/cash-registers/{id}/offline-session/retry Bearer Відновити надсилання офлайн-пакетів
Сервіс призупиняє надсилання, коли ДПС відхиляє пакет офлайн-сесії. Спочатку виправте причину. Потім надішліть запит на цей маршрут. Якщо ДПС відхиляє сесію постійно, відмовтеся від сесії через POST .../offline-session/abandon.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
200 Кількість офлайн-сесій, для яких сервіс відновив надсилання. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| resumed_sessions | integer | так | Кількість офлайн-сесій, для яких сервіс відновив надсилання. 0: призупинених сесій не було. |
/v1/cash-registers/{id}/offline-session/abandon Bearer Відмовитися від офлайн-сесії, яку відхиляє ДПС
Операція доступна, лише коли виконано обидві умови: - надсилання сесії призупинено (state.offline_backlog_undeliverable) - ДПС доступна Інакше сервіс повертає помилку state.offline_session_not_paused або state.offline_abandon_needs_dps. Сервіс позначає статусом abandoned документи сесії, яких ДПС не отримала. Офлайн-фіскальних номерів цих документів у ДПС немає. Їхні локальні номери отримують наступні документи. Сервіс закриває сесію в ДПС із документами, які ДПС уже отримала. Каса отримує нові офлайн-ключі. Перелік документів зі статусом abandoned є в результаті завдання і в події register.offline_abandoned. Клієнт вирішує, чи реєструвати ці чеки знову.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
| Idempotency-Key header | string | так | Ключ операції. Значення ключа обирає клієнт. Повторний запит із тим самим ключем повертає початкове завдання. Сервіс не виконує фіскальну операцію вдруге. |
| mode query | string | — | Режим відповіді. Параметр має пріоритет над полем mode у тілі запиту. sync (типовий) чекає на результат до 30 секунд. async одразу повертає 202 і завдання. |
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
/v1/cash-registers/{id}/attention Bearer Зняти позначку «потребує уваги» з каси
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
/v1/cash-registers/{id}/cash-balance Bearer Заявити фактичний залишок готівки
Операція встановлює залишок готівки, який перерахували в касі. Операцію використовують, коли касу підключили з готівкою в касовому ящику або коли залишок готівки не збігається з фактичним. Операція не фіскальна. Заявлений залишок готівки не потрапляє в документи і не змінює підсумків зміни. Рух готівки реєструють чеками service_in і service_out. Для від'ємної суми сервіс повертає 422.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор каси з GET /v1/cash-registers. |
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| amount | CashAmount | так | Перерахований залишок готівки. Від'ємне значення не допускається. |
/v1/billing/usage Bearer Передплачений баланс і підсумок тарифікації за період
Суми — копійки десятковим рядком. Типовий період — поточний календарний місяць за UTC. Дата to не входить у період. Для періоду понад 366 днів сервіс повертає 422. Сервіс тарифікує чеки асинхронно. Тому підсумок може не містити чеків за останні кілька секунд.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| from query | string (date) | — | Початок періоду, дата за UTC. Дата входить у період. Типово — перше число поточного місяця. |
| to query | string (date) | — | Кінець періоду. Дата не входить у період. Типово — перше число наступного місяця. Для періоду понад 366 днів сервіс повертає 422. |
/v1/invoices Bearer Рахунки клієнта, від найновішого періоду
Один рахунок відповідає одному розрахунковому періоду, а не одному платежу.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| limit query | integer | — | Кількість рахунків у відповіді: 1–200, типово 50. |
| offset query | integer | — | Кількість рахунків, які сервіс пропускає. Параметр використовують для посторінкового читання. |
200 Рахунки клієнта. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| invoices | array<Invoice> | так | Рахунки, від найновішого періоду. |
/v1/webhooks Bearer Вебхуки клієнта без секретів
200 Вебхуки клієнта. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| webhooks | array<WebhookEndpoint> | так | Вебхуки клієнта. Відповідь не містить секретів. |
| limit | integer | так | Максимальна кількість вебхуків: кількість кас клієнта плюс один. |
| used | integer | так | Кількість зареєстрованих вебхуків, разом із призупиненими. |
/v1/webhooks Bearer Зареєструвати вебхук
Сервіс доставляє подію запитом POST. Тіло запиту: {delivery_id, event, attempt, sequence, occurred_at, data}. Заголовок X-Signature має вигляд "sha256=<HMAC-SHA256 тіла у hex>". Сервіс обчислює підпис із секретом цього вебхука. Сервіс гарантує доставку «щонайменше один раз». Приймач має відкидати повторні доставки за delivery_id. Сервіс доставляє події однієї каси по одній і за порядком. Якщо приймач не прийняв подію, сервіс доставляє наступні події без затримки. Після повторної спроби або replay ця подія може надійти пізніше за наступні. Упорядковуйте події каси за sequence. sequence — номер події в межах каси. Номер зростає, але може мати пропуски. Поточний стан каси: GET /v1/cash-registers/{id}.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| url | string | так | Абсолютний http(s)-URL приймача. |
| events | array<WebhookEvent> | — | Події, на які підписано вебхук. Порожній список означає всі події. Якщо поля немає, вебхук підписано на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered |
| secret | string | — | Секрет HMAC. Якщо поля немає, сервіс створює секрет. |
201 Вебхук створено. Сервіс повертає секрет лише один раз. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор вебхука. |
| url | string | так | Абсолютний http(s)-URL приймача. |
| events | array<WebhookEvent> | так | Порожній список означає підписку на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered |
| active | boolean | так | Доставка ввімкнена. false: сервіс призупиняє доставку, черга доставок зберігається. |
| created_at | string (date-time) | так | Час створення вебхука. |
| updated_at | string (date-time) | так | Час останньої зміни вебхука. |
| secret | string | так | Сервіс не повертає секрет повторно. |
409 Кількість вебхуків досягла максимуму (код webhook_limit_reached). Максимум — кількість кас клієнта плюс один. Призупинені вебхуки входять у цю кількість. Поле details містить limit і used. Error /v1/webhooks/{id} Bearer Змінити URL, події або активність вебхука
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор вебхука. |
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| url | string | — | Новий абсолютний http(s)-URL приймача. |
| events | array<WebhookEvent> | — | Новий перелік подій. Порожній список означає всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered |
| active | boolean | — | false: сервіс призупиняє доставку. Черга доставок зберігається. |
/v1/webhooks/{id} Bearer Видалити вебхук
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор вебхука. |
/v1/webhooks/{id}/deliveries Bearer Історія доставок вебхука
Сервіс зберігає доставки зі статусом delivered 30 днів, доставки зі статусом dead — 14 днів від останньої спроби. Потім сервіс видаляє доставки з історії.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор вебхука. |
| status query | string | — | Лише доставки з цим статусом. |
| limit query | integer | — | Кількість доставок у відповіді: 1–200, типово 50. |
200 Доставки. | Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| deliveries | array<WebhookDelivery> | так | Доставки, від найновішої. |
/v1/webhooks/{id}/deliveries/{deliveryId}/replay Bearer Повторити доставку
Сервіс повертає доставку в чергу з новою кількістю спроб. Зазвичай це доставка зі статусом dead. Операція доступна, поки доставка є в історії. Доставка зі статусом dead є в історії 14 днів від останньої спроби.
| Параметр | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id path | string (uuid) | так | Ідентифікатор вебхука. |
| deliveryId path | string (uuid) | так | Ідентифікатор доставки з історії. |
200 Доставку повернуто в чергу. Сервіс виконує спробу одразу. Сервіс не повторює події, які доставив за цей час. Ця подія надійде після них. WebhookDelivery Обʼєкти, на які посилаються маршрути довідника. Обовʼязкові поля позначено «так».
Error object Конверт помилки: машинний код, текст для людини і подробиці, якщо вони є.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| code | string | так | Стабільний машинний код помилки. Програма клієнта обробляє помилку за цим кодом. |
| message | string | так | Текст для людини. Не використовуйте цей текст у логіці програми. |
| details | any | — | Подробиці помилки, якщо вони є. Приклад: перелік полів, які не пройшли валідацію. |
CashRegisterState object Поточний стан каси: режим, зміна, залишок готівки, офлайн-сесія.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор каси в цьому API. Це те саме значення, що cash_register_id у запиті на чек. |
| fiscal_number | string | так | Фіскальний номер каси, який присвоїла ДПС. У чеку це «ФН ПРРО». |
| local_number | string | так | CASHDESKNUM: номер каси, який присвоїв клієнт. |
| mode | string | так | - production — фіскальний режим - test — тестовий режим, усі документи тестові Документи зміни мають режим, у якому зміну відкрито. Змінити режим можна, лише коли зміну закрито.productiontest |
| state | string | так | - closed — зміну закрито - opened — зміну відкрито - offline — офлайн-сесія відкритаclosedopenedoffline |
| offline_ready | boolean | — | Чи має каса офлайн-ключі від ДПС. ДПС надсилає офлайн-ключі разом із квитанцією на відкриття зміни. |
| shift_mode | ShiftMode | — | Як сервіс керує змінами каси: - manual — клієнт відкриває і закриває зміни сам. - round_the_clock — сервіс закриває зміну в кожен час із shift_close_times. Наступний чек відкриває нову зміну. - working_hours — денне вікно між двома значеннями shift_close_times. round_the_clock і working_hours — автоматичні режими змін. В автоматичному режимі змін перший чек відкриває зміну. |
| shift_close_times | ShiftCloseTimes | — | Час щоденного закриття зміни за київським часом. Масив порожній лише тоді, коли shift_mode — manual. Час прив'язано до годинника, а не до часу відкриття зміни. Масив містить щонайменше два значення. Проміжок між сусідніми значеннями — не більше 20 годин, також через північ. Для round_the_clock — два або більше значень у порядку зростання. Для working_hours — рівно два значення: початок і кінець дня, у цьому порядку. Приклад вікна через північ: "08:00", потім "02:00". |
| cash_balance | CashBalance | — | Залишок готівки в касі. Це не фіскальне значення. Залишок готівки дорівнює нулю, коли касу створено. Залишок готівки враховує лише документи, які пройшли через цей сервіс. Залишок готівки змінюють: - готівкові оплати: продаж додає суму, повернення віднімає суму, сторно скасовує зміну від скасованого чека - службове внесення і службова видача Безготівкові оплати не змінюють залишок готівки. Сервіс бере sum оплати, решту вже враховано. Залишок готівки належить касі, а не зміні. Z-звіт не скидає залишок готівки. Від'ємне значення означає, що в касі було більше готівки, ніж зареєстрував сервіс. Встановити залишок готівки: PUT /v1/cash-registers/{id}/cash-balance. |
| current_shift | object | — | Поточна зміна каси. Поля немає після закриття зміни. |
| id | string (uuid) | — | Ідентифікатор зміни. |
| number | integer (int64) | — | Наскрізний номер зміни в межах каси («Зміна №147»). Номер присвоює сервіс. ДПС не присвоює номерів змін. |
| status | string | — | - opening — відкриття зміни виконується - opened — зміну відкрито - closing — закриття зміни виконується - closed — зміну закритоopeningopenedclosingclosed |
| testing | boolean | — | Зміну відкрито в тестовому режимі каси. Усі документи зміни тестові. |
| opened_at | string (date-time) | — | Час відкриття зміни. |
| documents | integer | — | Кількість документів зміни всіх типів, не лише чеків. Поля немає, якщо сервіс не зміг підрахувати документи. |
| shift_totals | ShiftTotals | — | Підсумки відкритої зміни на поточний момент. З цих сум сервіс створить Z-звіт під час закриття зміни. realiz — продажі, return — повернення. Скасовані чеки не входять у підсумки. Сервіс віднімає скасований чек із продажів або повернень. Службові внесення і службові видачі входять окремо: у service_in і service_out. Сум за податками тут немає. Суми за податками є в підсумках Z-звіту (ZReportTotals) після закриття зміни. |
| offline_session | object | — | Поле є лише тоді, коли офлайн-сесія відкрита. |
| id | string (uuid) | — | Ідентифікатор офлайн-сесії в сервісі. |
| dps_session_id | integer (int64) | — | Номер офлайн-сесії, який присвоїла ДПС. Номер входить у фіскальний номер офлайн-документа. |
| started_at | string (date-time) | — | Час відкриття офлайн-сесії. Від цього часу сервіс рахує межу 36 годин. |
| documents | integer (int64) | — | Кількість документів, які сервіс створив у цій офлайн-сесії. |
| last_significant_at | string (date-time) | — | Час останнього документа, який продовжує офлайн-сесію. За цим часом сервіс рахує використаний місячний час. |
| submit_paused_at | string (date-time) | — | Час, коли сервіс призупинив надсилання офлайн-пакетів, бо ДПС відхилила пакет. Поле є лише тоді, коли надсилання призупинено. |
| submit_fault | Fault | — | Помилка, з якою ДПС відхилила офлайн-пакет. Поле є лише тоді, коли надсилання призупинено. |
| code | string | так | Стабільний ідентифікатор помилки. Приклад: dps.check_local_number_invalid. |
| class | string | так | Дія, яка може виправити помилку: - resync — звірити стан каси з ДПС - config — виправити налаштування каси - precursor — виконати пропущений попередній крок - user_action — потрібне рішення людини - transient — тимчасова недоступність, повторіть запит - request — виправити запит - internal — внутрішня помилка сервісуresyncconfigprecursoruser_actiontransientrequestinternal |
| params | object | — | Значення для підстановки в message. |
| message | string | — | Текст для людини з каталогу помилок, перекладений мовою з Accept-Language. |
| upstream_message | string | — | Текст помилки від ДПС без змін. |
| remediation | array<string> | — | Автоматичні виправлення, які сервіс виконав під час завдання.local_number_syncedshift_adoptedshift_abandonedzreport_recoveredzreport_autofiledregister_config_filled |
| offline_limits | object | так | Законодавчі межі офлайн-режиму в секундах: 36 годин на одну офлайн-сесію і 168 годин на календарний місяць. Використаний час рахують від offline_session.started_at або від restored_at, якщо він пізніший, і за offline_month_used_seconds. |
| session_seconds | integer (int64) | так | Межа однієї офлайн-сесії, 36 годин у секундах. |
| month_seconds | integer (int64) | так | Межа на календарний місяць, 168 годин у секундах. |
| enforced | boolean | так | Межі діють. Значення false: межі знято за пунктом 13 розділу «Прикінцеві положення» Закону № 265. Сервіс рахує час в офлайн-режимі, але не відхиляє документи через межі. |
| restored_at | string (date-time) | — | Час, коли межі повернули після зняття. Сервіс рахує межі від цього часу, якщо він пізніший за початок офлайн-сесії або місяця. Поля немає, якщо межі не знімали. |
| offline_month_used_seconds | integer (int64) | — | Час в офлайн-режимі за поточний календарний місяць, у секундах. Сервіс рахує місяць за київським часом. |
| attention | object | — | Поле є лише тоді, коли каса має позначку «потребує уваги». Зняти позначку: DELETE .../attention. Якщо надсилання офлайн-пакетів призупинено, відновіть його через POST .../offline-session/retry. |
| reason | string | так | - recurring_remediation — сервіс виправляє розбіжності з ДПС знову і знову - offline_submission_paused — надсилання офлайн-пакетів призупинено - auto_close_failing — автоматичне закриття зміни завершується помилкоюrecurring_remediationoffline_submission_pausedauto_close_failing |
| since | string (date-time) | — | Час, коли сервіс поставив позначку. |
ShiftMode string Як сервіс керує змінами каси: - manual — клієнт відкриває і закриває зміни сам. - round_the_clock — сервіс закриває зміну в кожен час із shift_close_times. Наступний чек відкриває нову зміну. - working_hours — денне вікно між двома значеннями shift_close_times. round_the_clock і working_hours — автоматичні режими змін. В автоматичному режимі змін перший чек відкриває зміну.
manualround_the_clockworking_hours ShiftCloseTimes array Час щоденного закриття зміни за київським часом. Масив порожній лише тоді, коли shift_mode — manual. Час прив'язано до годинника, а не до часу відкриття зміни. Масив містить щонайменше два значення. Проміжок між сусідніми значеннями — не більше 20 годин, також через північ. Для round_the_clock — два або більше значень у порядку зростання. Для working_hours — рівно два значення: початок і кінець дня, у цьому порядку. Приклад вікна через північ: "08:00", потім "02:00".
CashRegisterListItem object Каса в переліку: ідентифікатор для запитів і реквізити, за якими людина впізнає касу.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор каси в цьому API. Значення використовують як cash_register_id у запиті на чек і як {id} в інших маршрутах. |
| fiscal_number | string | так | Фіскальний номер каси, який присвоїла ДПС. |
| local_number | string | так | CASHDESKNUM: номер каси, який присвоїв клієнт. |
| org_name | string | — | Назва суб'єкта господарювання. |
| point_name | string | — | Назва господарської одиниці. |
| point_address | string | — | Адреса господарської одиниці. |
| mode | string | так | - production — фіскальний режим - test — тестовий режим, усі документи тестові Документи зміни мають режим, у якому зміну відкрито. Змінити режим можна, лише коли зміну закрито.productiontest |
| state | string | так | - closed — зміну закрито - opened — зміну відкрито - offline — офлайн-сесія відкритаclosedopenedoffline |
Task object Завдання фіскального конвеєра. Кожен запит до ДПС сервіс виконує як завдання.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| task_id | string (uuid) | так | Ідентифікатор завдання. Статус завдання: GET /v1/tasks/{id}. |
| type | string | так | Операція завдання: - receipt — чек - open_shift — відкриття зміни - close_shift — закриття зміни - close_offline_session — закриття офлайн-сесії - abandon_offline_session — відмова від офлайн-сесії, яку відхиляє ДПС - verify_key — перевірка ключа КЕП - sync_register — звіряння каси з ДПС - dps_objects — запит господарських одиниць власника ключаreceiptopen_shiftclose_shiftclose_offline_sessionabandon_offline_sessionverify_keysync_registerdps_objects |
| status | string | так | - pending — завдання в черзі - processing — завдання виконується - succeeded — завдання завершилося успішно, дані в result - failed — завдання завершилося помилкою, дані в faultpendingprocessingsucceededfailed |
| created_at | string (date-time) | так | Час створення завдання. |
| finished_at | string (date-time) | — | Час завершення завдання. Поля немає, поки завдання виконується. |
| error | string | — | Текст помилки завдання. Структурований опис цієї помилки — у полі fault. |
| fault | Fault | — | Структурований опис помилки завдання. Мову message визначає заголовок Accept-Language. Типова мова — українська. Простори імен коду: - dps.* — помилка ДПС - fiscal.* — валідація документа - return.* — перевірка повернення за початковим чеком - storno.* — перевірка сторно за чеком, який сторно скасовує - signer.* — помилка КЕП - state.* — стан каси |
| result | TaskResult | — | Фіскальні поля (prro_id, shift_id, testing та інші) є в результаті завдань на чек, зміну та офлайн-сесію. Завдання verify_key повертає лише key_verification. |
Fault object Структурований опис помилки завдання. Мову message визначає заголовок Accept-Language. Типова мова — українська. Простори імен коду: - dps.* — помилка ДПС - fiscal.* — валідація документа - return.* — перевірка повернення за початковим чеком - storno.* — перевірка сторно за чеком, який сторно скасовує - signer.* — помилка КЕП - state.* — стан каси
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| code | string | так | Стабільний ідентифікатор помилки. Приклад: dps.check_local_number_invalid. |
| class | string | так | Дія, яка може виправити помилку: - resync — звірити стан каси з ДПС - config — виправити налаштування каси - precursor — виконати пропущений попередній крок - user_action — потрібне рішення людини - transient — тимчасова недоступність, повторіть запит - request — виправити запит - internal — внутрішня помилка сервісуresyncconfigprecursoruser_actiontransientrequestinternal |
| params | object | — | Значення для підстановки в message. |
| message | string | — | Текст для людини з каталогу помилок, перекладений мовою з Accept-Language. |
| upstream_message | string | — | Текст помилки від ДПС без змін. |
| remediation | array<string> | — | Автоматичні виправлення, які сервіс виконав під час завдання.local_number_syncedshift_adoptedshift_abandonedzreport_recoveredzreport_autofiledregister_config_filled |
TaskResult object Фіскальні поля (prro_id, shift_id, testing та інші) є в результаті завдань на чек, зміну та офлайн-сесію. Завдання verify_key повертає лише key_verification.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| prro_id | string (uuid) | — | Каса, на якій сервіс виконав завдання. |
| shift_id | string (uuid) | — | Зміна, у якій сервіс створив документи завдання. |
| shift_number | integer (int64) | — | Наскрізний номер зміни в межах каси. Номер присвоює сервіс. ДПС не присвоює номерів змін, у квитанції ДПС цього поля немає. |
| testing | boolean | — | Документи завдання тестові: каса в тестовому режимі. |
| receipt | DocResult | — | Чек, який створило завдання receipt. |
| shift_open | DocResult | — | Документ відкриття зміни. |
| zreport | DocResult | — | Z-звіт, яким сервіс закрив зміну. |
| shift_close | DocResult | — | Документ закриття зміни. |
| offline_end | DocResult | — | Документ закриття офлайн-сесії. |
| offline_abandon | OfflineAbandonResult | — | Результат відмови від офлайн-сесії (abandon_offline_session). |
| key_verification | KeyVerificationResult | — | Результат перевірки ключа КЕП. Це поле повертає завдання verify_key. |
| key_password_check | KeyPasswordCheckResult | — | Результат швидкої перевірки пароля контейнера. Сервіс лише розшифровує контейнер і не надсилає запитів у мережу. Завдання завершується успішно і при ok = false, тому що перевірка дала результат. Якщо сталася внутрішня помилка, результату немає, і сервіс повторює завдання. |
| reconcile | ReconcileReport | — | Результат звіряння каси з ДПС (sync_register): дані ДПС і виправлення, які сервіс виконав у своїх даних. |
| dps_objects | array<DPSTaxObject> | — | Господарські одиниці власника ключа. Це поле повертає завдання dps_objects. |
OfflineAbandonResult object Результат відмови від офлайн-сесії (abandon_offline_session).
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| session_id | string (uuid) | так | Офлайн-сесія, від якої відмовилися. |
| dps_session_id | integer (int64) | так | Номер офлайн-сесії, який присвоїла ДПС. |
| held_documents | integer (int64) | так | Кількість документів сесії, які ДПС отримала. Ці документи залишаються зареєстрованими. |
| abandoned | array<AbandonedDocument> | так | Документи сесії, яких ДПС не отримала. |
| closure_session_id | string (uuid) | — | Офлайн-сесія, якою сервіс закриває в ДПС сесію, від якої відмовилися. Поля немає, якщо ДПС не отримала жодного документа сесії або ДПС уже закрила сесію сама. |
| closed | boolean | так | true: сесію закрито в ДПС, каса знову в онлайн-режимі. false: сервіс ще надсилає документ закриття сесії. Доти нові документи каси чекають у черзі. |
AbandonedDocument object Документ офлайн-сесії, від якої відмовилися. Покупець отримав цей документ. Фіскального номера документа в ДПС немає.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| document_id | string (uuid) | так | Ідентифікатор документа в журналі сервісу. |
| task_id | string (uuid) | — | Завдання, яке створило документ. |
| class | string | так | Тип документа.checkzreportopen_shiftclose_shiftoffline_beginoffline_end |
| kind | string | — | Тип чека. Поле є лише для class = check.salereturnstornoservice_inservice_out |
| local_number | integer (int64) | так | Локальний номер документа. |
| fiscal_number | string | — | Офлайн-фіскальний номер, надрукований у документі. |
| total | string | — | Сума документа в гривнях. Поле є лише для чеків. |
| pay_form | string | — | Форма оплати. Поле є лише для чеків.cashcashlessmixed |
| created_at | string (date-time) | так | Час створення документа. |
ReconcileReport object Результат звіряння каси з ДПС (sync_register): дані ДПС і виправлення, які сервіс виконав у своїх даних.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| fiscal_number | string | так | Фіскальний номер каси, яку звіряли. |
| dps_shift_opened | boolean | так | Чи відкрита зміна каси за даними ДПС. |
| dps_next_local_number | integer (int64) | так | Локальний номер, який ДПС очікує в наступному документі. |
| dps_testing | boolean | — | Чи тестова каса за даними ДПС. |
| counter_old | integer (int64) | — | Лічильник локальних номерів сервісу до звіряння. |
| counter_new | integer (int64) | — | Лічильник локальних номерів сервісу після звіряння. |
| shift_adopted | boolean | — | Сервіс прийняв як свою зміну, відкриту в ДПС. |
| shift_abandoned | boolean | — | Сервіс закрив у своїх даних зміну, якої в ДПС немає. |
| offline_credentials_refreshed | boolean | — | Сервіс оновив офлайн-ключі каси з даних ДПС. |
| cash | object | — | Рух готівки за поточну зміну: за даними сервісу (ours) і за даними ДПС (dps). Поле є лише тоді, коли зміна відкрита в ДПС. Поле довідкове. Сервіс не виправляє розбіжність. |
| ours | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| dps | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| match | boolean | так | Чи збігаються дані сервісу і дані ДПС. |
| totals | object | — | Підсумки поточної зміни за даними сервісу і за даними ДПС. Поле є лише тоді, коли зміна відкрита і в ДПС, і в сервісі. Якщо підсумки не збігаються, сервіс надсилає Z-звіт зміни з підсумками ДПС. ДПС не приймає інших підсумків. |
| ours | ShiftTotalsBrief | так | Суми й кількості чеків зміни, за якими ДПС перевіряє Z-звіт. |
| dps | ShiftTotalsBrief | — | Поля немає, якщо ДПС не повернула підсумків. |
| match | boolean | так | Чи збігаються підсумки сервісу і підсумки ДПС. |
| z_report_source | string | так | Джерело підсумків для Z-звіту зміни.localdps |
| forced | boolean | — | Це звіряння перевело Z-звіт зміни на підсумки ДПС. |
| held | string | — | Причина, з якої сервіс не звірив підсумки або не виправив розбіжність: - dps_totals_unavailable — ДПС не повернула підсумків. У цьому випадку match = false і поля dps немає. - shift_closing — сервіс уже надіслав Z-звіт зміни. - offline_backlog — сервіс ще не надіслав офлайн-документи до ДПС.dps_totals_unavailableshift_closingoffline_backlog |
| attention_cleared | boolean | — | Сервіс зняв позначку auto_close_failing. Автоматичне закриття зміни знову працює. |
| skipped | string | — | Причина, з якої сервіс не виконав звіряння. offline_session: сервіс не звіряє касу, коли офлайн-сесія відкрита.offline_session |
ShiftTotalsBrief object Суми й кількості чеків зміни, за якими ДПС перевіряє Z-звіт.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| sales | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| sales_count | integer | так | Кількість чеків продажу. |
| returns | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| returns_count | integer | так | Кількість чеків повернення. |
| service_input | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| service_output | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
DPSTaxObject object Господарська одиниця власника ключа (dps_objects).
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| name | string | так | Назва господарської одиниці. |
| address | string | — | Адреса господарської одиниці. |
| tin | string | так | Податковий номер власника: ЄДРПОУ або РНОКПП. |
| ipn | string | — | Індивідуальний податковий номер платника ПДВ. |
| org_name | string | так | Назва суб'єкта господарювання. |
| registrars | array<DPSRegistrar> | так | Каси, зареєстровані в ДПС за цією господарською одиницею. |
DPSRegistrar object Каса, зареєстрована в ДПС за господарською одиницею.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| fiscal_number | string | так | Фіскальний номер каси, який присвоїла ДПС. |
| local_number | string | так | Локальний номер каси, який присвоїв власник. |
| name | string | — | Назва каси з реєстраційних даних ДПС. |
| closed | boolean | — | Касу скасовано в ДПС. |
KeyPasswordCheckResult object Результат швидкої перевірки пароля контейнера. Сервіс лише розшифровує контейнер і не надсилає запитів у мережу. Завдання завершується успішно і при ok = false, тому що перевірка дала результат. Якщо сталася внутрішня помилка, результату немає, і сервіс повторює завдання.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| signing_key_id | string (uuid) | так | Ключ, пароль якого перевіряли. |
| ok | boolean | так | Пароль правильний: сервіс розшифрував контейнер. |
| verify_code | string | — | Код причини. Поле є завжди при ok = false. Приклад: wrong_password. |
| verify_error | string | — | Текст помилки бібліотеки підпису без змін. |
KeyVerificationResult object Результат повної перевірки ключа КЕП: чи можна підписувати ключем документи каси і хто власник ключа.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| signing_key_id | string (uuid) | так | Ключ, який перевіряли. Якщо deleted = true, ключа в сервісі вже немає. |
| status | string | так | - active — ключ можна використовувати - invalid — сервіс відхилив ключ, причина в verify_codeactiveinvalid |
| verify_code | string | — | Причина відхилення. Ключ із причиною not_prro можна активувати через POST /cabinet/signing-keys/{id}/activate.wrong_passwordcert_not_foundcert_expirednot_prroverify_failedca_unreachable |
| verify_error | string | — | Текст помилки перевірки без змін. |
| key_type | string | — | Тип власника ключа за даними сертифіката.individuallegal |
| prro_capable | boolean | так | Сертифікат дозволяє підписувати документи каси. |
| cert_subject | string | — | Поле subject сертифіката, як його записав АЦСК. |
| org_name | string | — | Назва суб'єкта господарювання або ім'я фізичної особи з сертифіката. |
| edrpou | string | — | ЄДРПОУ юридичної особи з сертифіката, лише цифри. |
| drfo | string | — | РНОКПП (ДРФО) фізичної особи з сертифіката, лише цифри. |
| deleted | boolean | — | Сервіс видалив ключ. Сервіс видаляє ключ за будь-якої причини відхилення, крім not_prro. |
DocResult object Документ, який створило завдання: номери в сервісі і в ДПС, посилання для покупця.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| document_id | string (uuid) | так | Ідентифікатор документа в журналі сервісу. |
| local_number | integer | так | Наскрізний номер документа в межах каси (ORDERNUM). |
| fiscal_number | string | так | Фіскальний номер документа, який присвоїла ДПС. |
| register_fiscal_number | string | так | Фіскальний номер каси, у якій сервіс створив документ. У чеку це «ФН ПРРО» (CASHREGISTERNUM). Це номер каси, а не документа. На відміну від fiscal_number, цей номер однаковий в онлайн-режимі і в офлайн-сесії. Поле є завжди. |
| offline | boolean | — | Сервіс підписав документ в офлайн-сесії. Сервіс обчислив фіскальний номер локально (<sid>.<n>.<crc>). ДПС отримає документ лише разом із пакетом офлайн-сесії. |
| receipt_url | string (uri) | — | Копія чека для покупця на короткому домені сервісу (https://r.prro.cloud/<код>). Посилання надсилають покупцю або перетворюють на QR-код. Сторінка відкривається без авторизації: доступ дає код у посиланні. Формат задає параметр запиту ?format=: - html (типовий) — сторінка чека - png — зображення чека шириною 576 px (стрічка 80 мм для термопринтера) з QR-кодом - qr — PNG із QR-кодом адреси цієї сторінки Поле є лише в чеках. Посилання працює одразу, також в офлайн-сесії. Сторінка — копія чека, а не підтвердження фіскалізації. Підтвердження фіскалізації: fiscal_number і tax_url. |
| tax_url | string (uri) | — | Цей документ в Електронному кабінеті платника податків ДПС. Це незалежне підтвердження фіскалізації. Поля немає, доки ДПС не отримала документ. До надсилання пакета офлайн-сесії офлайн-чек має лише фіскальний номер, який сервіс обчислив локально. |
| original | ReturnOriginal | — | Початковий чек повернення. Поле є лише в чеку повернення. |
| totals | ZReportTotals | — | Підсумки Z-звіту: ті самі суми, що в документі, який сервіс надіслав до ДПС. Поле є лише в Z-звіті. realiz — продажі, return — повернення. Якщо в зміні не було повернень, службових внесень або службових видач, відповідні суми дорівнюють нулю. Z-звіт, який сервіс створив в офлайн-сесії (offline: true), ДПС отримує пізніше, разом з іншими документами офлайн-сесії. |
ReturnOriginal object Початковий чек повернення. Поле є лише в чеку повернення.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| fiscal_number | string | так | Фіскальний номер початкового чека. |
| document_id | string (uuid) | — | Початковий чек у журналі сервісу. Поля немає, якщо verified = false. |
| verified | boolean | так | true: сервіс створив початковий чек і перевірив повернення за залишком цього чека. false: початкового чека в сервісі немає, його створила інша каса. Сервіс прийняв повернення без перевірки. |
ReceiptInput oneOf Три форми запиту на чек. Форму визначає поле type: - продаж і повернення — позиції та оплати - сторно — лише посилання на чек - службове внесення і службова видача — лише сума Сервіс не ігнорує поля іншої форми. Для таких полів сервіс повертає 422.
type SettlementReceiptInput object Чек продажу або повернення товарів.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_register_id | string (uuid) | — | Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422. |
| type | string | так | - sale — продаж - return — поверненняsalereturn |
| cashier | string | — | Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка. |
| comment | string | — | Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Приклад: номер замовлення. |
| sold_at | string (date-time) | — | Час фактичного продажу, якщо чек надійшов до сервісу пізніше. Це не фіскальний час чека. ДПС приймає ORDERDATE/ORDERTIME лише в межах приблизно однієї хвилини від свого часу. Тому фіскальний час чека — час надсилання. Сервіс друкує в чеку рядок «Продаж від 03.09.2026 18:11» перед приміткою з comment. Для часу в майбутньому або часу, старшого за 31 день, сервіс повертає 422. |
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
| original | object | — | Посилання на початковий чек. Поле обов'язкове для повернення. Якщо сервіс створив початковий чек, сервіс перевіряє повернення за цим чеком. Початковий чек має відповідати всім умовам: - це чек продажу - режим чека той самий: тестовий або фіскальний - сторно не скасовувало цей чек - сума всіх повернень за чеком не перевищує суми продажу до заокруглення Якщо умову не виконано, завдання завершується помилкою з кодом return.*, і сервіс не реєструє чек. Якщо початкового чека в сервісі немає, сервіс приймає повернення без перевірки. Див. result.receipt.original.verified. |
| fiscal_number | string | так | Фіскальний номер початкового чека. |
| register_fiscal_number | string | — | Фіскальний номер каси, у якій створено початковий чек, якщо це інша каса. Якщо поля немає, сервіс шукає початковий чек на касі повернення. |
| date | string (date) | — | Дата початкового чека у форматі РРРР-ММ-ДД. |
| items | array<ReceiptItem> | так | Позиції чека, щонайменше одна. |
| payments | array<ReceiptPayment> | так | Оплати чека, щонайменше одна. |
| rounding_step | string | — | Крок заокруглення готівки, десятковий рядок ("0.10" за правилами НБУ). Якщо поля немає, сервіс не заокруглює суму. |
StornoReceiptInput object Сторно попереднього чека (DOCSUBTYPE 5). Сторно скасовує чек продажу або повернення, який зареєстрували помилково. Сторно не містить позицій, оплат і суми. ДПС реєструє сторно з нульовою сумою. Сторно може скасувати лише останній документ каси. Цей документ має бути чеком продажу або повернення, який створив сервіс і який сторно ще не скасовувало. Інакше завдання завершується помилкою з кодом storno.*, і сервіс не реєструє сторно. Щоб скасувати чек, після якого є інші документи, зареєструйте повернення. Сервіс змінює підсумки зміни і залишок готівки на суми скасованого чека у зворотному напрямку.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_register_id | string (uuid) | — | Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422. |
| type | string | так | storno |
| cashier | string | — | Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка. |
| comment | string | — | Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Приклад: причина сторно. |
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
| original | object | так | Чек, який скасовує сторно. |
| fiscal_number | string | так | Фіскальний номер чека, який скасовує сторно. |
ServiceReceiptInput object Рух готівки без продажу: - service_in — службове внесення (DOCSUBTYPE 2) - service_out — службова видача (DOCSUBTYPE 4) Сервіс обробляє цей чек так само, як інші чеки. В автоматичному режимі змін чек відкриває зміну. Чек працює в офлайн-сесії. Сервіс записує чек у журнал і тарифікує його як чек. У підсумках зміни сума входить окремо в service_input/service_output і в ZREPBODY Z-звіту. Сервіс змінює cash_balance на всю суму. Сервіс не підтримує отримання підкріплення (DOCSUBTYPE 3).
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_register_id | string (uuid) | — | Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422. |
| type | string | так | - service_in — службове внесення - service_out — службова видачаservice_inservice_out |
| cashier | string | — | Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка. |
| comment | string | — | Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Для руху готівки лише примітка вказує призначення суми. Приклади: «Інкасація», «Розмінна монета». |
| sold_at | string (date-time) | — | Час фактичного продажу, якщо чек надійшов до сервісу пізніше. Це не фіскальний час чека. ДПС приймає ORDERDATE/ORDERTIME лише в межах приблизно однієї хвилини від свого часу. Тому фіскальний час чека — час надсилання. Сервіс друкує в чеку рядок «Продаж від 03.09.2026 18:11» перед приміткою з comment. Для часу в майбутньому або часу, старшого за 31 день, сервіс повертає 422. |
| mode | string | — | Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync |
| sum | string | так | Сума руху готівки: додатний десятковий рядок, до 2 знаків після коми. Чек не містить позицій. |
ReceiptItem object Грошові значення — десяткові рядки ("259.90"). Кількість має до 3 знаків після коми, ціна — до 2.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| code | string | — | Внутрішній код товару. |
| barcode | string | — | Штрихкод товару. |
| uktzed | string | — | Код УКТЗЕД. Не використовуйте разом із dkpp. |
| dkpp | string | — | Код ДКПП. Не використовуйте разом із uktzed. |
| name | string | так | Назва позиції, яку сервіс друкує в чеку. |
| unit_code | integer | — | Код одиниці виміру (UNITCD). |
| unit_name | string | — | Назва одиниці виміру. Приклади: «шт», «кг». |
| quantity | string | так | Кількість, десятковий рядок, до 3 знаків після коми. |
| price | string | так | Ціна за одиницю, десятковий рядок, до 2 знаків після коми. |
| tax_letters | string | — | Податкові літери з tax_rates каси. Приклади: "А", "АГ". Порожнє значення застосовує default_tax_letter каси. Якщо типової літери немає, позиція не має податку. Значення "-" робить позицію неоподатковуваною. |
| discount | object | — | Знижка на позицію. |
| percent | string | — | Позначає знижку як відсоткову. Суму знижки вказують у sum. |
| sum | string | так | Сума знижки, десятковий рядок. Поле обов'язкове також для відсоткової знижки. |
| excise_labels | array<string> | — | Коди акцизних марок. |
| comment | string | — | Примітка до позиції. |
PaymentType string Форма оплати. Фіскальний код і назву форми оплати в чеку визначає сервіс: - cash — 0 ГОТІВКА - card — 301 КАРТКА - certificate — 305 СЕРТИФІКАТ - bank_transfer — 306 ПЕРЕКАЗ З ПОТОЧНОГО РАХУНКУ - direct_debit — 100000 ПРЯМИЙ ДЕБЕТ Залишок готівки каси змінює лише cash.
cashcardcertificatebank_transferdirect_debit ReceiptPayment object Одна оплата чека: форма оплати, сума і, для картки, реквізити еквайрингу.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| type | PaymentType | так | Форма оплати. Фіскальний код і назву форми оплати в чеку визначає сервіс: - cash — 0 ГОТІВКА - card — 301 КАРТКА - certificate — 305 СЕРТИФІКАТ - bank_transfer — 306 ПЕРЕКАЗ З ПОТОЧНОГО РАХУНКУ - direct_debit — 100000 ПРЯМИЙ ДЕБЕТ Залишок готівки каси змінює лише cash. |
| sum | string | так | Сума цієї оплати. |
| provided | string | — | Сума, яку покупець дав готівкою. Решта = provided − sum. |
| means | string | — | Засіб оплати: чим саме покупець оплатив. Положення № 13 (розд. II п. 2, рядок 19) вимагає вказувати засіб оплати окремо від форми оплати. Значення — ті самі, що в прикладах ДПС: «Картка», «Переказ з поточного рахунку», «Подарунковий сертифікат», «Попередня оплата», «Прямий дебет». Також значення, яких немає в type: «ПЕРЕКАЗ З КАРТКИ», «ТАЛОН», «ЖЕТОН». Поле замінює лише назву форми оплати, яку сервіс друкує (PAYFORMNM). Фіскальний код форми оплати (PAYFORMCD) визначає type. Для cash сервіс не приймає це поле. |
| card | object | — | Реквізити еквайрингу (рядки 12–17). Усі три поля acquirer_* описують еквайра торговця, а не торговця. |
| system_name | string | — | Назва платіжної системи (рядок 17). |
| acquirer_id | string | — | Ідентифікатор еквайра (рядок 12). |
| acquirer_tax_id | string | — | Податковий номер еквайра (рядок 12). |
| acquirer_name | string | — | Назва еквайра (рядок 12). |
| transaction_date | string (date-time) | — | Дата й час транзакції на платіжному пристрої (POSTRANSDATE). |
| transaction_number | string | — | Номер транзакції на платіжному пристрої (POSTRANSNUM). |
| device_id | string | — | Ідентифікатор платіжного пристрою (рядок 13). |
| epz_details | string | — | Замаскований номер картки. |
| auth_code | string | — | Код авторизації (рядок 17). |
| commission | string | — | Сума комісії еквайра за цією оплатою: рядок 14 форми ФКЧ-1, «у разі наявності». Для звичайного продажу поле порожнє. Поле заповнюють, лише коли комісію сплачує держатель картки: приймання коштів для подальшого переказу і видача готівки держателям карток (розділи VI і VII Положення № 13). Нуль означає, що комісії немає. Тоді сервіс не друкує рядок 14. |
WebhookEvent string - task.completed — завдання завершилося успішно. - task.failed — завдання завершилося помилкою. - shift.opened, shift.closed — зміну відкрито або закрито. Дані: ShiftEventData. - key.expiring — строк дії сертифіката ключа закінчується протягом 30 днів. Сервіс надсилає цю подію раз на добу. - register.offline — каса перейшла в офлайн-режим. - register.online — каса повернулася в онлайн-режим. - register.offline_limit — каса досягла законодавчої межі офлайн-режиму (36 годин на офлайн-сесію, 168 годин на місяць). Якщо межі знято, дані містять limits_lifted: true, і сервіс не відхиляє документи через межі. - register.offline_abandoned — від офлайн-сесії відмовилися. Подія містить перелік документів, яких ДПС не отримала. - register.remediated — сервіс автоматично виправив розбіжність із ДПС. - register.needs_attention — сервіс не може виправити розбіжності автоматично. Потрібне рішення людини. - client.balance_low — баланс наближається до порога. Коли баланс стане нижчим за поріг, сервіс відхилятиме чеки з 402. - receipt.registered — сервіс зареєстрував чек будь-якого типу. Подія містить повний вміст чека. Дані: ReceiptRegisteredData.
task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered ShiftEventData object Дані подій shift.opened і shift.closed.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_register_id | string (uuid) | так | Каса. |
| shift_id | string (uuid) | так | Зміна. |
| task_id | string (uuid) | так | Завдання, яке відкрило або закрило зміну. Зазвичай це завдання open_shift або close_shift. Зміну також може закрити завдання receipt, якщо попереднє закриття не завершилося, або автоматичне виправлення розбіжності з ДПС. |
| testing | boolean | так | Тестова зміна: каса в тестовому режимі. |
| zreport | DocResult | — | Поле є лише в shift.closed. Z-звіт, яким сервіс закрив зміну, разом із підсумками (totals). Якщо зміну закрило завдання close_shift, це той самий об'єкт, що в result.zreport цього завдання. Поля немає, якщо в сервісі немає Z-звіту цієї зміни. |
ReceiptRegisteredData object Дані події receipt.registered: чек у тому вигляді, у якому його отримала ДПС. Суми — десяткові рядки в гривнях, як у запиті на чек.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| cash_register_id | string (uuid) | так | Каса. |
| register_fiscal_number | string | так | Фіскальний номер каси. |
| document_id | string (uuid) | так | Чек у журналі сервісу. |
| task_id | string (uuid) | так | Завдання, яке зареєструвало чек. |
| type | string | так | Тип чека.salereturnstornoservice_inservice_out |
| source | string | так | Джерело запиту на чек — API або кабінет.apicabinet |
| user_id | string (uuid) | — | Обліковий запис кабінету, з якого надіслано запит на чек. Поле є лише для source = cabinet. Власник бачить цей обліковий запис у переліку команди. |
| cashier | string | — | Ім'я касира, надруковане в чеку. |
| local_number | integer (int64) | так | Локальний номер чека. |
| fiscal_number | string | так | Фіскальний номер чека. В офлайн-сесії сервіс обчислює номер локально. |
| offline | boolean | так | Сервіс створив чек в офлайн-сесії. |
| testing | boolean | так | Тестовий чек. |
| shift_id | string (uuid) | так | Зміна. |
| shift_number | integer (int64) | — | Номер зміни в межах каси. |
| issued_at | string (date-time) | так | Дата й час чека, як їх надруковано. |
| total | string | так | Сума до сплати. Для службового внесення і службової видачі — сума руху готівки. Для сторно — 0.00. |
| rounding | string | — | Сума заокруглення готівки. Поля немає, якщо заокруглення не було. |
| items | array<object> | — | Позиції чека. |
| code | string | — | |
| barcode | string | — | |
| uktzed | string | — | |
| dkpp | string | — | |
| name | string | так | |
| unit_name | string | — | |
| quantity | string | так | |
| price | string | так | |
| cost | string | — | Вартість позиції до знижки. |
| tax_letters | string | — | |
| discount | string | — | Сума знижки. |
| payments | array<object> | — | Оплати чека. |
| type | string | — | Форма оплати, як у запиті на чек. |
| name | string | так | Назва форми оплати, надрукована в чеку. |
| sum | string | так | |
| taxes | array<TaxTotal> | — | Податки чека. |
| comment | string | — | Примітка, надрукована в чеку. |
| original | object | — | Початковий чек повернення або чек, який скасовує сторно. |
| fiscal_number | string | так | |
| document_id | string (uuid) | — | Початковий чек у журналі сервісу. Поля немає, якщо чека немає в журналі. |
| verified | boolean | так | Лише для повернення: сервіс знайшов початковий чек у журналі і перевірив залишок за ним. |
| receipt_url | string | — | Копія чека для покупця. |
| tax_url | string | — | Чек в Електронному кабінеті платника податків ДПС. Поля немає, доки ДПС не отримала офлайн-чек. |
WebhookEndpoint object Вебхук: URL приймача і події, які сервіс доставляє.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор вебхука. |
| url | string | так | Абсолютний http(s)-URL приймача. |
| events | array<WebhookEvent> | так | Порожній список означає підписку на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered |
| active | boolean | так | Доставка ввімкнена. false: сервіс призупиняє доставку, черга доставок зберігається. |
| created_at | string (date-time) | так | Час створення вебхука. |
| updated_at | string (date-time) | так | Час останньої зміни вебхука. |
WebhookDelivery object Одна доставка події та її статус.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор доставки. Це значення вказують у шляху replay. |
| event | string | так | Тип події. Крім значень WebhookEvent, доставка може мати зарезервовані типи без підписки: webhook.ping (тестова доставка) і system.dps_* (події доступності ДПС). |
| status | string | так | - pending — доставка в черзі - delivering — спроба виконується - delivered — подію доставлено - failed — спроба невдала, сервіс виконає повторну спробу - dead — спроби закінчилисяpendingdeliveringdeliveredfaileddead |
| attempts | integer | так | Кількість виконаних спроб. |
| cash_register_id | string (uuid) | — | Каса події. Поля немає для подій рівня клієнта. |
| sequence | integer (int64) | — | Номер події в межах каси (поле sequence конверта). За цим номером упорядковують події. Поля немає для подій рівня клієнта. |
| data | any | так | Дані події (поле data конверта). |
| last_error | string | — | Результат останньої невдалої спроби: код і початок відповіді приймача або причина помилки з'єднання (наприклад, TLS). |
| next_attempt_at | string (date-time) | — | Час наступної спроби. Поля немає, якщо спроб більше не буде. |
| created_at | string (date-time) | так | Час, коли сервіс поставив подію в чергу. |
| delivered_at | string (date-time) | — | Час, коли приймач повернув успішну відповідь. |
Money string Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.
CashAmount string Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
CashBalance object Залишок готівки в касі. Це не фіскальне значення. Залишок готівки дорівнює нулю, коли касу створено. Залишок готівки враховує лише документи, які пройшли через цей сервіс. Залишок готівки змінюють: - готівкові оплати: продаж додає суму, повернення віднімає суму, сторно скасовує зміну від скасованого чека - службове внесення і службова видача Безготівкові оплати не змінюють залишок готівки. Сервіс бере sum оплати, решту вже враховано. Залишок готівки належить касі, а не зміні. Z-звіт не скидає залишок готівки. Від'ємне значення означає, що в касі було більше готівки, ніж зареєстрував сервіс. Встановити залишок готівки: PUT /v1/cash-registers/{id}/cash-balance.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| amount | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| as_of | string (date-time) | — | Час останньої зміни залишку готівки. null: змін ще не було. Тоді нуль означає «немає даних», а не «каса порожня». |
ShiftTotalsSide object Продажі або повернення: кількість чеків, сума і суми за формами оплати.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| count | integer | так | Кількість чеків. |
| sum | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| pay_forms | array<object> | — | Суми за формами оплати. code і name — код і назва форми оплати, як у Z-звіті (PAYFORMCD і PAYFORMNM). Поля немає, якщо чеків немає. |
| code | integer | так | PAYFORMCD: фіскальний код форми оплати. |
| name | string | так | PAYFORMNM: назва форми оплати, яку сервіс друкує. |
| sum | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
ShiftTotals object Підсумки відкритої зміни на поточний момент. З цих сум сервіс створить Z-звіт під час закриття зміни. realiz — продажі, return — повернення. Скасовані чеки не входять у підсумки. Сервіс віднімає скасований чек із продажів або повернень. Службові внесення і службові видачі входять окремо: у service_in і service_out. Сум за податками тут немає. Суми за податками є в підсумках Z-звіту (ZReportTotals) після закриття зміни.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| realiz | ShiftTotalsSide | так | Продажі або повернення: кількість чеків, сума і суми за формами оплати. |
| return | ShiftTotalsSide | так | Продажі або повернення: кількість чеків, сума і суми за формами оплати. |
| service_in | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| service_out | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
TaxTotal object Податок за однією ставкою: оборот і сума податку.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| letter | string | — | Податкова літера. Приклад: «А». |
| name | string | так | Назва податку. Приклад: «ПДВ». |
| rate | string | так | Ставка у відсотках. Приклад: «20.00». |
| turnover | string | так | Оборот: сума продажів за цією ставкою. |
| sum | string | так | Сума податку. |
| excluded | boolean | — | true: сервіс додав податок до ціни, податок не входить у ціну. |
ZReportTotalsSide object Продажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| count | integer | так | Кількість чеків. |
| sum | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| pay_forms | array<object> | — | Суми за формами оплати. code і name — код і назва форми оплати, як у Z-звіті (PAYFORMCD і PAYFORMNM). Поля немає, якщо чеків немає. |
| code | integer | так | PAYFORMCD: фіскальний код форми оплати. |
| name | string | так | PAYFORMNM: назва форми оплати, яку сервіс друкує. |
| sum | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| taxes | array<TaxTotal> | — | Податки за ставками. Поля немає, якщо податків не було. |
ZReportTotals object Підсумки Z-звіту: ті самі суми, що в документі, який сервіс надіслав до ДПС. Поле є лише в Z-звіті. realiz — продажі, return — повернення. Якщо в зміні не було повернень, службових внесень або службових видач, відповідні суми дорівнюють нулю. Z-звіт, який сервіс створив в офлайн-сесії (offline: true), ДПС отримує пізніше, разом з іншими документами офлайн-сесії.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| realiz | ZReportTotalsSide | так | Продажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками. |
| return | ZReportTotalsSide | так | Продажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками. |
| service_in | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| service_out | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
CashBalanceDeclaration object Залишок готівки до заяви, після заяви і різниця між ними.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| amount | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| previous | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
| adjustment | CashAmount | так | Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація. |
BillingUsage object Баланс і підсумок тарифікації за період.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| balance | Money | так | Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою. |
| soft_limit | Money | так | Поріг балансу. Поки balance < soft_limit, сервіс відхиляє чеки. |
| blocked | boolean | так | Сервіс зараз відхиляє чеки через баланс або за рішенням оператора. |
| period | object | так | Період підсумку. |
| from | string (date) | так | Дата входить у період. |
| to | string (date) | так | Дата не входить у період. |
| receipts | integer (int64) | так | Кількість тарифікованих чеків за період. |
| charged | Money | так | Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою. |
| tariff | object | так | Тариф, за яким сервіс тарифікував чеки. |
| plan_id | string (uuid) | так | Ідентифікатор тарифного плану. |
| price_per_receipt | Money | так | Ціна чека до першого порога з price_tiers. |
| price_tiers | array<PriceTier> | так | Ціни чека за обсягом, від найменшого порога. Сервіс рахує чеки кожної каси окремо за календарний місяць за київським часом. Порожній масив означає одну ціну для всіх чеків. |
PriceTier object Ціна чека понад порогову кількість чеків каси за місяць.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| above_receipts | integer (int32) | так | Порог. Ціна діє для чеків каси, номер яких у місяці більший за порог. |
| price | Money | так | Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою. |
Invoice object Рахунок за один розрахунковий період.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| id | string (uuid) | так | Ідентифікатор рахунка. |
| period_start | string (date) | так | Дата входить у період. |
| period_end | string (date) | так | Дата входить у період. |
| amount | Money | так | Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою. |
| currency | string | так | Валюта рахунка за ISO 4217: UAH. |
| status | string | так | - draft — чернетка - issued — рахунок виставлено - paid — рахунок оплачено - overdue — рахунок простроченоdraftissuedpaidoverdue |
| created_at | string (date-time) | так | Час створення рахунка. |
DPSPulse object Режим роботи з ДПС і телеметрія, яка пояснює цей режим. Сервіс працює з ДПС за значенням effective.
| Поле | Тип | Обовʼязковий | Опис |
|---|---|---|---|
| effective | string | так | Поточний режим роботи сервісу з ДПС.onlineoffline |
| verdict | string | так | Результат детектора. Значення degraded означає «повільно», offline — «недоступно».onlinedegradedoffline |
| since | string (date-time) | так | Час, з якого діє поточне значення effective. |
| latency_ms | integer (int64) | так | Затримка успішних запитів у вікні детектора, у мілісекундах. Значення 0 означає, що у вікні немає успішних запитів. |
| samples | integer | так | Кількість запитів у вікні детектора. |
| failures | integer | так | Кількість невдалих запитів у вікні детектора. |
| last_ok_at | string (date-time) | — | Час останньої успішної відповіді ДПС. |
| last_probe_at | string (date-time) | — | Час останньої перевірки доступності ДПС. |
| tunables | object | так | Пороги для значень вище: ширина вікна детектора, поріг degraded і інтервал перевірок. |
| window_seconds | integer (int64) | так | Ширина вікна детектора, у секундах. |
| degraded_latency_ms | integer (int64) | так | Затримка, від якої відповідь вважається повільною, у мілісекундах. |
| probe_interval_seconds | integer (int64) | так | Інтервал перевірок, у секундах. |