Документація API

Автентифікація

Машинні запити автентифікуються довгоживучим Bearer-токеном (JWT). Випустіть його в кабінеті PRRO.cloud у розділі токенів — значення показується рівно один раз, збережіть його одразу. Токен передається в заголовку Authorization: Bearer <token>; відкликання в кабінеті набирає чинності на всіх репліках протягом ~2 секунд. Перевірити токен можна запитом:

curl -H "Authorization: Bearer $PRRO_TOKEN" \
  "$BASE_URL/v1/whoami"

Швидкий старт

Разовий виклик, щоб узяти id каси, і три запити фіскального циклу — перший чек зареєстровано. На касі в режимі test цей цикл безкоштовний: ДПС перевіряє документи, але не фіскалізує їх. Пишете на Go — той самий цикл є в клієнті prro-go: ключі ідемпотентності, повтори та перевірку підпису вебхуків він бере на себе.

1. 01 Візьміть id каси.

   Токен показує ті каси, на які він діє. id з відповіді — те саме значення, що далі йде у cash_register_id чека і в шляхи /cash-registers/{id}; фіскальний номер для цього не годиться. Виклик разовий — збережіть id у налаштуваннях інтеграції.

   curl -H "Authorization: Bearer $PRRO_TOKEN" \
     "$BASE_URL/v1/cash-registers"

2. 02 Відкрийте зміну.

   Якщо каса не в режимі 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": "Каса самообслуговування"}'

3. 03 Зареєструйте чек.

   Суми — десяткові рядки, а не числа. У синхронному режимі (за замовчуванням) фіскальний номер — одразу у відповіді, а поруч із ним — посилання на чек для покупця.

   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" }
       ]
     }'

4. 04 Закрийте день.

   Z-звіт і закриття зміни — одна операція (або налаштуйте shift_close_times на касі, і день закриватиметься сам).

   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 тощо), і він напише код інтеграції за вас. Для цього сайт публікує машиночитані версії за конвенцією llms.txt:

• /llms.txt

  — індекс для ШІ-агентів: короткий опис сервісу та посилання на машиночитані документи. Почніть звідси.

• /llms-full.txt

  — уся ця сторінка одним markdown-файлом: автентифікація, швидкий старт, чек для покупця, вебхуки, повний довідник ендпоінтів і схем. Вміщується в контекст моделі — цього файла достатньо, щоб написати інтеграцію без жодного іншого джерела.

• /api/openapi.yaml

  — специфікація OpenAPI 3.1, з якої згенеровано довідник: джерело правди для кодогенерації та валідації.

Усі три файли генеруються під час збірки з тих самих джерел, що й ця сторінка, тож не розходяться з нею.

Ключові механіки

• Ідемпотентність.

  Заголовок Idempotency-Key обовʼязковий для всіх фіскальних операцій. Повтор запиту з тим самим ключем повертає оригінальну задачу, а не другий чек — мережеві збої та ретраї безпечні. Той самий ключ з іншою операцією — 409.

• Sync та async.

  За замовчуванням запит тримає зʼєднання до відповіді ДПС (до 30 с); якщо не встигли — 202 із задачею для опитування. mode=async повертає 202 одразу, а результат приходить через GET /v1/tasks/{id} та/або вебхук.

• Гроші — рядки.

  Усі суми — десяткові рядки ("259.90"), ніколи не float. Кількість — до 3 знаків після коми, ціни — до 2.

• Помилки.

  Єдиний конверт {code, message, details}: code — машинний код для обробки, message — людський текст. 422 — помилка валідації або відхилення операції (немає відкритої зміни, відмова ДПС).

• Баланс.

  Сервіс передплатний: коли баланс перетинає мʼякий ліміт, нові чеки відповідають 402, доки баланс не поповнено. Операції зі змінами при цьому доступні. Перед тим приходить попередження, що кошти добігають кінця: вебхук client.balance_low — у data баланс, мʼякий ліміт, ціна чека і скільки чеків лишилося — і лист на адресу сповіщень клієнта.

• Час продажу.

  Якщо ваша інтеграція дійшла до нас пізніше за касу (автомат, що годину тримав замовлення в черзі), передайте sold_at — і на чеку зʼявиться окремий рядок «Продаж від 03.09.2026 18:11», перед приміткою comment, якщо вона є. Фіскальним часом документа він не стає: ДПС приймає його лише в межах хвилини від власного годинника, тож документ завжди позначено моментом подання. Час у майбутньому або старіший за 31 день — 422.

• Форма оплати й засіб.

  payments[].type — одна з форм, закритих законом (cash, card, certificate, bank_transfer, direct_debit); фіскальний код і назву за неї підставляє сервіс. Коли надрукувати треба точніше — «ПЕРЕКАЗ З КАРТКИ», талон, сертифікат мережі — назву задає payments[].means, а код форми лишається за type, тож лічильник готівки та розбивка Z-звіту не розходяться з чеком. Реквізити еквайрингу (ідентифікатор і податковий номер еквайра, платіжний пристрій, код авторизації, комісія) — у payments[].card.

• Повернення.

  Повернення (type: return) звіряється з чеком з original.fiscal_number, якщо той видано в нашому сервісі: це має бути продаж у тому самому режимі (test чи production), не сторнований, і всі повернення за ним разом не перевищують суми продажу до заокруглення. Чек з іншої каси шукається за original.register_fiscal_number. Не зійшлося — задача завершується помилкою з кодом return.*, документ не реєструється й до ДПС не йде. Чек, виданий іншим ПРРО, приймається без звірки — тоді в результаті result.receipt.original.verified: false.

• Текст чека — у windows-1251.

  Інших кодувань ДПС не приймає, але символ поза ним чек не валить — сервіс замінює його сам: поширені мають заміну (апостроф ʼ → ’, × → 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"
    }
  }
}

• receipt_url — копія чека.

  Сторінка відкривається без авторизації: 16-символьний код і є доступом, як паперовий чек у кишені. Подання обирає параметр ?format=: html (типово), png (сам чек картинкою завширшки 576 px — це растрова ширина стрічки 80 мм, тож на термопринтер вона йде як є, разом із QR) і qr (PNG з адресою цієї ж сторінки). Назовні віддається лише людиночитаний чек — ні XML, ні CMS, ні квитанції ДПС. Невідомий код і документ, який не можна показати, відповідають однаково — 404.

• tax_url — незалежна перевірка.

  Той самий документ у кабінеті платника податків — підтвердження, яке покупець читає, не довіряючи нам. Доказ фіскалізації — це fiscal_number і tax_url; receipt_url лише показує чек.

• Офлайн-чек.

  У документа з offline: true фіскальний номер обчислено локально (<sid>.<n>.<crc>), тож tax_url зʼявиться лише після того, як пакет сесії прийме фіскальний сервер. receipt_url є одразу — копія віддається з нашого журналу.

• Сесія, якої ДПС не прийняла.

  Коли ДПС відхиляє пакети сесії, каса зупиняється: нові документи відповідають кодом state.offline_backlog_undeliverable. Усунувши причину, надсилання відновлюють (.../offline-session/retry) або від сесії відмовляються (.../offline-session/abandon). Документи, яких ДПС так і не отримала, стають abandoned: їхнього фіскального номера в ДПС не існує, tax_url не зʼявиться, а receipt_url відповідає 404. Перелік таких документів приходить у результаті задачі та в події register.offline_abandoned; чи видавати ці продажі знову, вирішує інтеграція.

• register_fiscal_number — ФН ПРРО.

  Фіскальний номер каси, на якій видано документ, — той самий «ФН ПРРО», що друкується на чеку. Присутній завжди й однаковий у будь-якому режимі, на відміну від fiscal_number. Це те, за чим інтеграція зіставляє свої записи з касою: діставати номер із параметра fn= посилання tax_url не треба — саме його в офлайн-документа й немає.

• Тільки розрахункові документи.

  Z-звіт, відкриття та закриття зміни друкованої форми не мають, тож посилань у їхніх DocResult не буде.

• Посилання не протухають.

  Код зберігається разом із документом, а не перераховується, тож ротація ключів сервісу не ламає адрес, які вже в руках у покупців. Сторінку не індексують пошукові системи.

Вебхуки

Замість опитування задач підпишіться на події: зареєструйте endpoint через POST /v1/webhooks — і сервіс сам постукає у ваш бекенд.

• Події.

  Завдання — task.completed і task.failed. Чеки — receipt.registered (див. нижче). Зміни — shift.opened і 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 у ній немає.

• Кожен чек — з повним вмістом.

  receipt.registered приходить на кожен зареєстрований чек — продаж, повернення, сторно, службове внесення й видачу, онлайн і офлайн — і зокрема на ті, що касир провів у кабінеті PRRO.cloud, а не через API. У data — документ у тому вигляді, в якому його отримала ДПС: позиції, оплати, податки, сума й заокруглення, касир, номери, зміна, оригінал повернення чи сторно, receipt_url і tax_url (у офлайн-чека — лише після прийняття ДПС). Звідки подано чек, каже source: api чи cabinet (тоді user_id — обліковий запис кабінету). Поля — у схемі ReceiptRegisteredData (розділ «Схеми даних»). Тож обліку не треба опитувати журнал, щоб бачити продажі, проведені в кабінеті.

• Конверт доставки.

  POST на ваш URL з тілом {delivery_id, event, attempt, sequence, occurred_at, data}; у data — корисне навантаження події, sequence — номер події в межах каси (у подій рівня клієнта його немає).

• Підпис.

  Заголовок X-Signature: sha256=<hex> — HMAC-SHA256 від тіла запиту під секретом endpoint'а. Секрет видається один раз при створенні; перевіряйте підпис перед обробкою.

• Гарантії.

  Доставка at-least-once — дедуплікуйте за delivery_id. Невдалі доставки ретраяться, вичерпані потрапляють у DLQ (status=dead) і можуть бути повторені вручну через replay.

• Історія доставок не вічна.

  Доставлені зберігаються 30 днів, невдалі (dead) — 14 днів від останньої спроби, потім зникають з історії. Replay доступний, поки доставка в ній є: щоб повторити невдалу, у вас два тижні.

• Порядок — за sequence.

  Події однієї каси надсилаються по одній і по порядку, але подія, яку ваш приймач не прийняв, наступних не затримує: після ретраю чи replay вона прийде пізніше за них. Упорядковуйте події каси за sequence — він зростає, пропуски можливі. Актуальний стан каси завжди дає GET /v1/cash-registers/{id}.

• Чому не доставлено.

  У журналі доставок last_error каже, чим скінчилася остання невдала спроба: код і початок відповіді вашого приймача або причина збою зʼєднання — зокрема TLS (прострочений чи чужий сертифікат, звичайний HTTP на https-адресі).

• Скільки вебхуків.

  Не більше, ніж кас у клієнта, плюс один; призупинені теж рахуються, видалені — ні. Понад ліміт POST /v1/webhooks відповідає 409 з кодом webhook_limit_reached і details {limit, used}; ті самі limit і used повертає GET /v1/webhooks, тож інтеграція бачить ліміт заздалегідь.

• Пауза й видалення — різні речі.

  active: false призупиняє доставку, не втрачаючи черги: увімкнете назад — накопичене піде далі. Видалення endpoint'а переводить усе недоставлене в 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.

Схеми даних

Обʼєкти, на які посилаються ендпоінти довідника. Обовʼязкові поля позначено «так».