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

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

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

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

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

Разовий виклик, щоб узяти id каси, і три запити фіскального циклу — перший чек зареєстровано. На касі в режимі TEST цей цикл безкоштовний і не потребує реєстрації в податковій.

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

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

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

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

   Якщо каса не в режимі shift_mode: manual, цей крок можна пропустити — перший чек відкриє зміну сам.

   curl -X POST "$BASE_URL/api/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/api/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/api/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 /api/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.

Чек для покупця

Відповідь на фіскалізацію несе не лише фіскальний номер: у 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 є одразу — копія віддається з нашого журналу.

• register_fiscal_number — ФН ПРРО.

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

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

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

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

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

Вебхуки

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

• Події.

  Завдання — task.completed і task.failed. Зміни — shift.opened і shift.closed. Ключ КЕП — key.expiring (раз на добу про сертифікат, що спливає протягом 30 днів). Стан каси — register.offline і register.online, register.offline_limit (наближення до законних меж офлайн-сесії, 36 і 168 годин), register.remediated (сервіс сам усунув розбіжність із ДПС) і register.needs_attention (виправлення не тримаються — на касу має поглянути людина). Баланс — client.balance_low (передплачених коштів лишилося менше ніж на поріг чеків); ця подія стосується клієнта, а не каси, тож cash_register_id у ній немає.

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

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

• Підпис.

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

• Гарантії.

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

POST https://example.com/prro-hook
X-Signature: sha256=2b7e9f…

{
  "delivery_id": "0197a2c4-…",
  "event": "task.completed",
  "attempt": 1,
  "occurred_at": "2026-07-14T10:15:04Z",
  "data": { "task_id": "0197a2c1-…", "status": "succeeded" }
}

Довідник ендпоінтів

Згенеровано зі специфікації OpenAPI. Кабінетні ендпоінти (cookie-сесія панелі) сюди не входять — інтеграції працюють лише з машинним API.

Схеми даних

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