PRRO.cloud

Контакти

Відповідаємо в робочі дні.

Кабінет

OpenAPI v0.11.0

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

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. Бібліотека сама створює ключі ідемпотентності, повторює запити і перевіряє підпис вебхуків.

  1. Отримайте id каси.

    Відповідь містить каси, на які діє токен. Значення id використовують як cash_register_id у запиті на чек і як {id} у шляхах /cash-registers/{id}. Фіскальний номер каси тут не підходить. Цей запит потрібен лише один раз: збережіть id у налаштуваннях своєї програми.

    curl -H "Authorization: Bearer $PRRO_TOKEN" \
      "$BASE_URL/v1/cash-registers"
  2. Відкрийте зміну.

    Цей крок потрібен лише в режимі змін 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. Зареєструйте чек.

    Суми — десяткові рядки, а не числа. Типовий режим відповіді — 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" }
        ]
      }'
  4. Закрийте зміну.

    Одна операція створює 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:

  • /llms.txt

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

  • /llms-full.txt

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

  • /api/openapi.yaml

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

  • Текст чека — у 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 із QR-кодом: це ширина стрічки 80 мм для термопринтера. qr повертає PNG із QR-кодом адреси сторінки. Сторінка показує лише чек для людини: без 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.submit_paused_at і offline_session.submit_fault. Виправте причину і відновіть надсилання (.../offline-session/retry). Якщо ДПС відхиляє сесію постійно, відмовтеся від сесії (.../offline-session/abandon). Сервіс позначає статусом abandoned документи, яких ДПС не отримала. Фіскальних номерів цих документів у ДПС немає, поля tax_url немає, а receipt_url повертає 404. Перелік цих документів є в результаті завдання і в події register.offline_abandoned. Клієнт вирішує, чи реєструвати ці чеки знову. Якщо ДПС обмежує частоту запитів (HTTP 429), сервіс не призупиняє надсилання, а надсилає пакет пізніше.

  • register_fiscal_number — ФН ПРРО.

    Фіскальний номер каси, у якій сервіс створив документ. У чеку це «ФН ПРРО». Поле є завжди. На відміну від 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 днів.

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

    Сервіс доставляє події однієї каси по одній і за порядком. Якщо приймач не прийняв подію, сервіс доставляє наступні події без затримки. Після повторної спроби або 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.

Сервісні

GET /v1/version

Версія збірки сервісу

Відповіді

  • 200 Версія збірки.
    Поле Тип Обовʼязковий Опис
    versionstringтакТег збірки: dev для локальної збірки, номер версії для релізу.
GET /v1/whoami Bearer

Клієнт і дозволи токена

Відповіді

  • 200 Клієнт, дозволи (scopes) і каси токена.
    Поле Тип Обовʼязковий Опис
    client_idstring (uuid)такКлієнт, від імені якого діє токен.
    scopesarray<string>такДозволи токена.
    all_cash_registersbooleanтакtrue: токен необмежений, він діє на всі каси клієнта, поточні й майбутні. false: токен обмежений, він діє лише на каси з cash_registers.
    cash_registersarray<string (uuid)>—Перелік uuid кас, на які діє обмежений токен. Поля немає, якщо all_cash_registers = true.
    jtistring (uuid)такІдентифікатор токена. За цим ідентифікатором токен відкликають у кабінеті.
    expires_atstring (date-time)—Час, коли строк дії токена закінчується. Поля немає, якщо токен безстроковий.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
GET /v1/system/dps Bearer

Поточний режим роботи з ДПС (онлайн/офлайн)

Режим, у якому сервіс працює з ДПС зараз. Маршрут доступний для будь-якого машинного токена.

Відповіді

  • 200 Режим роботи з ДПС і телеметрія, яка пояснює цей режим. DPSPulse
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error

Фіскальні операції

POST /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 і завдання.

Тіло запиту application/json

ReceiptInput

Відповіді

  • 200 Повторний запит із тим самим Idempotency-Key. Завдання вже завершилося. Task
  • 201 Чек зареєстровано. Завдання завершилося успішно за час очікування режиму sync. Task
  • 202 Завдання ще виконується. Статус завдання: GET /v1/tasks/{id}. Task
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 402 Баланс нижчий за поріг. Сервіс відхиляє нові чеки, доки клієнт не поповнить баланс. Операції зі змінами доступні. Error
  • 404 Конверт помилки. Error
  • 409 Цей Idempotency-Key уже використано для іншої операції. Error
  • 422 Запит не пройшов валідацію, або завдання завершилося помилкою. Приклади: немає відкритої зміни, ДПС відхилила документ. Error
GET /v1/tasks/{id} Bearer

Статус і результат завдання

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор завдання з відповіді на фіскальну операцію.

Відповіді

  • 200 Завдання в поточному стані. Task
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
GET /v1/cash-registers Bearer

Каси, доступні токену

Для необмеженого токена сервіс повертає всі каси клієнта. Для обмеженого токена сервіс повертає лише каси цього токена. Значення id використовують як cash_register_id і як {id} в інших маршрутах. Поточний стан каси: GET /v1/cash-registers/{id}.

Відповіді

  • 200 Каси токена, від найстарішої.
    Поле Тип Обовʼязковий Опис
    cash_registersarray<CashRegisterListItem>такКаси токена, від найстарішої.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
GET /v1/cash-registers/{id} Bearer

Стан каси

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор каси з GET /v1/cash-registers.

Відповіді

  • 200 Поточний стан каси. CashRegisterState
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
POST /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 і завдання.

Тіло запиту application/json · optional

Поле Тип Обовʼязковий Опис
cashierstring—Ім'я касира. Сервіс друкує його в документі відкриття зміни.
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync

Відповіді

  • 201 Зміну відкрито. Task
  • 202 Завдання ще виконується. Статус завдання: GET /v1/tasks/{id}. Task
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
DELETE /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 і завдання.

Відповіді

  • 201 Зміну закрито. Результат містить Z-звіт і документ закриття зміни. Task
  • 202 Завдання ще виконується. Статус завдання: GET /v1/tasks/{id}. Task
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
POST /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 і завдання.

Тіло запиту application/json · optional

Поле Тип Обовʼязковий Опис
cashierstring—Ім'я касира. Сервіс друкує його в документі закриття офлайн-сесії.
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync

Відповіді

  • 201 Офлайн-сесію закрито. Результат містить документ закриття офлайн-сесії. Task
  • 202 Завдання ще виконується. Статус завдання: GET /v1/tasks/{id}. Task
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
POST /v1/cash-registers/{id}/offline-session/retry Bearer

Відновити надсилання офлайн-пакетів

Сервіс призупиняє надсилання, коли ДПС відхиляє пакет офлайн-сесії. Спочатку виправте причину. Потім надішліть запит на цей маршрут. Якщо ДПС відхиляє сесію постійно, відмовтеся від сесії через POST .../offline-session/abandon.

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор каси з GET /v1/cash-registers.

Відповіді

  • 200 Кількість офлайн-сесій, для яких сервіс відновив надсилання.
    Поле Тип Обовʼязковий Опис
    resumed_sessionsintegerтакКількість офлайн-сесій, для яких сервіс відновив надсилання. 0: призупинених сесій не було.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
POST /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 і завдання.

Тіло запиту application/json · optional

Поле Тип Обовʼязковий Опис
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync

Відповіді

  • 201 Від офлайн-сесії відмовилися. Результат містить offline_abandon. Task
  • 202 Завдання ще виконується. Статус завдання: GET /v1/tasks/{id}. Task
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
DELETE /v1/cash-registers/{id}/attention Bearer

Зняти позначку «потребує уваги» з каси

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор каси з GET /v1/cash-registers.

Відповіді

  • 200 Чи зняв сервіс позначку.
    Поле Тип Обовʼязковий Опис
    clearedbooleanтакfalse: позначки не було.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
PUT /v1/cash-registers/{id}/cash-balance Bearer

Заявити фактичний залишок готівки

Операція встановлює залишок готівки, який перерахували в касі. Операцію використовують, коли касу підключили з готівкою в касовому ящику або коли залишок готівки не збігається з фактичним. Операція не фіскальна. Заявлений залишок готівки не потрапляє в документи і не змінює підсумків зміни. Рух готівки реєструють чеками service_in і service_out. Для від'ємної суми сервіс повертає 422.

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор каси з GET /v1/cash-registers.

Тіло запиту application/json

Поле Тип Обовʼязковий Опис
amountCashAmountтакПерерахований залишок готівки. Від'ємне значення не допускається.

Відповіді

  • 200 Залишок готівки після заяви. CashBalanceDeclaration
  • 400 Конверт помилки. Error
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error

Білінг

GET /v1/billing/usage Bearer

Передплачений баланс і підсумок тарифікації за період

Суми — копійки десятковим рядком. Типовий період — поточний календарний місяць за UTC. Дата to не входить у період. Для періоду понад 366 днів сервіс повертає 422. Сервіс тарифікує чеки асинхронно. Тому підсумок може не містити чеків за останні кілька секунд.

Параметри

Параметр Тип Обовʼязковий Опис
from query string (date) — Початок періоду, дата за UTC. Дата входить у період. Типово — перше число поточного місяця.
to query string (date) — Кінець періоду. Дата не входить у період. Типово — перше число наступного місяця. Для періоду понад 366 днів сервіс повертає 422.

Відповіді

  • 200 Баланс і підсумок тарифікації за період. BillingUsage
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 422 Конверт помилки. Error
GET /v1/invoices Bearer

Рахунки клієнта, від найновішого періоду

Один рахунок відповідає одному розрахунковому періоду, а не одному платежу.

Параметри

Параметр Тип Обовʼязковий Опис
limit query integer — Кількість рахунків у відповіді: 1–200, типово 50.
offset query integer — Кількість рахунків, які сервіс пропускає. Параметр використовують для посторінкового читання.

Відповіді

  • 200 Рахунки клієнта.
    Поле Тип Обовʼязковий Опис
    invoicesarray<Invoice>такРахунки, від найновішого періоду.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 422 Конверт помилки. Error

Вебхуки

GET /v1/webhooks Bearer

Вебхуки клієнта без секретів

Відповіді

  • 200 Вебхуки клієнта.
    Поле Тип Обовʼязковий Опис
    webhooksarray<WebhookEndpoint>такВебхуки клієнта. Відповідь не містить секретів.
    limitintegerтакМаксимальна кількість вебхуків: кількість кас клієнта плюс один.
    usedintegerтакКількість зареєстрованих вебхуків, разом із призупиненими.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
POST /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}.

Тіло запиту application/json

Поле Тип Обовʼязковий Опис
urlstringтакАбсолютний http(s)-URL приймача.
eventsarray<WebhookEvent>—Події, на які підписано вебхук. Порожній список означає всі події. Якщо поля немає, вебхук підписано на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered
secretstring—Секрет HMAC. Якщо поля немає, сервіс створює секрет.

Відповіді

  • 201 Вебхук створено. Сервіс повертає секрет лише один раз.
    Поле Тип Обовʼязковий Опис
    idstring (uuid)такІдентифікатор вебхука.
    urlstringтакАбсолютний http(s)-URL приймача.
    eventsarray<WebhookEvent>такПорожній список означає підписку на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered
    activebooleanтакДоставка ввімкнена. false: сервіс призупиняє доставку, черга доставок зберігається.
    created_atstring (date-time)такЧас створення вебхука.
    updated_atstring (date-time)такЧас останньої зміни вебхука.
    secretstringтакСервіс не повертає секрет повторно.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 409 Кількість вебхуків досягла максимуму (код webhook_limit_reached). Максимум — кількість кас клієнта плюс один. Призупинені вебхуки входять у цю кількість. Поле details містить limit і used. Error
  • 422 Конверт помилки. Error
PATCH /v1/webhooks/{id} Bearer

Змінити URL, події або активність вебхука

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор вебхука.

Тіло запиту application/json

Поле Тип Обовʼязковий Опис
urlstring—Новий абсолютний http(s)-URL приймача.
eventsarray<WebhookEvent>—Новий перелік подій. Порожній список означає всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered
activeboolean—false: сервіс призупиняє доставку. Черга доставок зберігається.

Відповіді

  • 200 Вебхук змінено. WebhookEndpoint
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
DELETE /v1/webhooks/{id} Bearer

Видалити вебхук

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор вебхука.

Відповіді

  • 204 Вебхук видалено. Сервіс переводить недоставлені події в статус dead.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
GET /v1/webhooks/{id}/deliveries Bearer

Історія доставок вебхука

Сервіс зберігає доставки зі статусом delivered 30 днів, доставки зі статусом dead — 14 днів від останньої спроби. Потім сервіс видаляє доставки з історії.

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор вебхука.
status query string — Лише доставки з цим статусом.
limit query integer — Кількість доставок у відповіді: 1–200, типово 50.

Відповіді

  • 200 Доставки.
    Поле Тип Обовʼязковий Опис
    deliveriesarray<WebhookDelivery>такДоставки, від найновішої.
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 422 Конверт помилки. Error
POST /v1/webhooks/{id}/deliveries/{deliveryId}/replay Bearer

Повторити доставку

Сервіс повертає доставку в чергу з новою кількістю спроб. Зазвичай це доставка зі статусом dead. Операція доступна, поки доставка є в історії. Доставка зі статусом dead є в історії 14 днів від останньої спроби.

Параметри

Параметр Тип Обовʼязковий Опис
id path string (uuid) так Ідентифікатор вебхука.
deliveryId path string (uuid) так Ідентифікатор доставки з історії.

Відповіді

  • 200 Доставку повернуто в чергу. Сервіс виконує спробу одразу. Сервіс не повторює події, які доставив за цей час. Ця подія надійде після них. WebhookDelivery
  • 401 Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано. Error
  • 404 Конверт помилки. Error
  • 409 Спроба доставки виконується зараз. Error

Схеми даних

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

Error object

Конверт помилки: машинний код, текст для людини і подробиці, якщо вони є.

Поле Тип Обовʼязковий Опис
codestringтакСтабільний машинний код помилки. Програма клієнта обробляє помилку за цим кодом.
messagestringтакТекст для людини. Не використовуйте цей текст у логіці програми.
detailsany—Подробиці помилки, якщо вони є. Приклад: перелік полів, які не пройшли валідацію.

CashRegisterState object

Поточний стан каси: режим, зміна, залишок готівки, офлайн-сесія.

Поле Тип Обовʼязковий Опис
idstring (uuid)такІдентифікатор каси в цьому API. Це те саме значення, що cash_register_id у запиті на чек.
fiscal_numberstringтакФіскальний номер каси, який присвоїла ДПС. У чеку це «ФН ПРРО».
local_numberstringтакCASHDESKNUM: номер каси, який присвоїв клієнт.
modestringтак- production — фіскальний режим - test — тестовий режим, усі документи тестові Документи зміни мають режим, у якому зміну відкрито. Змінити режим можна, лише коли зміну закрито.productiontest
statestringтак- closed — зміну закрито - opened — зміну відкрито - offline — офлайн-сесія відкритаclosedopenedoffline
offline_readyboolean—Чи має каса офлайн-ключі від ДПС. ДПС надсилає офлайн-ключі разом із квитанцією на відкриття зміни.
shift_modeShiftMode—Як сервіс керує змінами каси: - manual — клієнт відкриває і закриває зміни сам. - round_the_clock — сервіс закриває зміну в кожен час із shift_close_times. Наступний чек відкриває нову зміну. - working_hours — денне вікно між двома значеннями shift_close_times. round_the_clock і working_hours — автоматичні режими змін. В автоматичному режимі змін перший чек відкриває зміну.
shift_close_timesShiftCloseTimes—Час щоденного закриття зміни за київським часом. Масив порожній лише тоді, коли shift_mode — manual. Час прив'язано до годинника, а не до часу відкриття зміни. Масив містить щонайменше два значення. Проміжок між сусідніми значеннями — не більше 20 годин, також через північ. Для round_the_clock — два або більше значень у порядку зростання. Для working_hours — рівно два значення: початок і кінець дня, у цьому порядку. Приклад вікна через північ: "08:00", потім "02:00".
cash_balanceCashBalance—Залишок готівки в касі. Це не фіскальне значення. Залишок готівки дорівнює нулю, коли касу створено. Залишок готівки враховує лише документи, які пройшли через цей сервіс. Залишок готівки змінюють: - готівкові оплати: продаж додає суму, повернення віднімає суму, сторно скасовує зміну від скасованого чека - службове внесення і службова видача Безготівкові оплати не змінюють залишок готівки. Сервіс бере sum оплати, решту вже враховано. Залишок готівки належить касі, а не зміні. Z-звіт не скидає залишок готівки. Від'ємне значення означає, що в касі було більше готівки, ніж зареєстрував сервіс. Встановити залишок готівки: PUT /v1/cash-registers/{id}/cash-balance.
current_shiftobject—Поточна зміна каси. Поля немає після закриття зміни.
idstring (uuid)—Ідентифікатор зміни.
numberinteger (int64)—Наскрізний номер зміни в межах каси («Зміна №147»). Номер присвоює сервіс. ДПС не присвоює номерів змін.
statusstring—- opening — відкриття зміни виконується - opened — зміну відкрито - closing — закриття зміни виконується - closed — зміну закритоopeningopenedclosingclosed
testingboolean—Зміну відкрито в тестовому режимі каси. Усі документи зміни тестові.
opened_atstring (date-time)—Час відкриття зміни.
documentsinteger—Кількість документів зміни всіх типів, не лише чеків. Поля немає, якщо сервіс не зміг підрахувати документи.
shift_totalsShiftTotals—Підсумки відкритої зміни на поточний момент. З цих сум сервіс створить Z-звіт під час закриття зміни. realiz — продажі, return — повернення. Скасовані чеки не входять у підсумки. Сервіс віднімає скасований чек із продажів або повернень. Службові внесення і службові видачі входять окремо: у service_in і service_out. Сум за податками тут немає. Суми за податками є в підсумках Z-звіту (ZReportTotals) після закриття зміни.
offline_sessionobject—Поле є лише тоді, коли офлайн-сесія відкрита.
idstring (uuid)—Ідентифікатор офлайн-сесії в сервісі.
dps_session_idinteger (int64)—Номер офлайн-сесії, який присвоїла ДПС. Номер входить у фіскальний номер офлайн-документа.
started_atstring (date-time)—Час відкриття офлайн-сесії. Від цього часу сервіс рахує межу 36 годин.
documentsinteger (int64)—Кількість документів, які сервіс створив у цій офлайн-сесії.
last_significant_atstring (date-time)—Час останнього документа, який продовжує офлайн-сесію. За цим часом сервіс рахує використаний місячний час.
submit_paused_atstring (date-time)—Час, коли сервіс призупинив надсилання офлайн-пакетів, бо ДПС відхилила пакет. Поле є лише тоді, коли надсилання призупинено.
submit_faultFault—Помилка, з якою ДПС відхилила офлайн-пакет. Поле є лише тоді, коли надсилання призупинено.
codestringтакСтабільний ідентифікатор помилки. Приклад: dps.check_local_number_invalid.
classstringтакДія, яка може виправити помилку: - resync — звірити стан каси з ДПС - config — виправити налаштування каси - precursor — виконати пропущений попередній крок - user_action — потрібне рішення людини - transient — тимчасова недоступність, повторіть запит - request — виправити запит - internal — внутрішня помилка сервісуresyncconfigprecursoruser_actiontransientrequestinternal
paramsobject—Значення для підстановки в message.
messagestring—Текст для людини з каталогу помилок, перекладений мовою з Accept-Language.
upstream_messagestring—Текст помилки від ДПС без змін.
remediationarray<string>—Автоматичні виправлення, які сервіс виконав під час завдання.local_number_syncedshift_adoptedshift_abandonedzreport_recoveredzreport_autofiledregister_config_filled
offline_limitsobjectтакЗаконодавчі межі офлайн-режиму в секундах: 36 годин на одну офлайн-сесію і 168 годин на календарний місяць. Використаний час рахують від offline_session.started_at або від restored_at, якщо він пізніший, і за offline_month_used_seconds.
session_secondsinteger (int64)такМежа однієї офлайн-сесії, 36 годин у секундах.
month_secondsinteger (int64)такМежа на календарний місяць, 168 годин у секундах.
enforcedbooleanтакМежі діють. Значення false: межі знято за пунктом 13 розділу «Прикінцеві положення» Закону № 265. Сервіс рахує час в офлайн-режимі, але не відхиляє документи через межі.
restored_atstring (date-time)—Час, коли межі повернули після зняття. Сервіс рахує межі від цього часу, якщо він пізніший за початок офлайн-сесії або місяця. Поля немає, якщо межі не знімали.
offline_month_used_secondsinteger (int64)—Час в офлайн-режимі за поточний календарний місяць, у секундах. Сервіс рахує місяць за київським часом.
attentionobject—Поле є лише тоді, коли каса має позначку «потребує уваги». Зняти позначку: DELETE .../attention. Якщо надсилання офлайн-пакетів призупинено, відновіть його через POST .../offline-session/retry.
reasonstringтак- recurring_remediation — сервіс виправляє розбіжності з ДПС знову і знову - offline_submission_paused — надсилання офлайн-пакетів призупинено - auto_close_failing — автоматичне закриття зміни завершується помилкоюrecurring_remediationoffline_submission_pausedauto_close_failing
sincestring (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

Каса в переліку: ідентифікатор для запитів і реквізити, за якими людина впізнає касу.

Поле Тип Обовʼязковий Опис
idstring (uuid)такІдентифікатор каси в цьому API. Значення використовують як cash_register_id у запиті на чек і як {id} в інших маршрутах.
fiscal_numberstringтакФіскальний номер каси, який присвоїла ДПС.
local_numberstringтакCASHDESKNUM: номер каси, який присвоїв клієнт.
org_namestring—Назва суб'єкта господарювання.
point_namestring—Назва господарської одиниці.
point_addressstring—Адреса господарської одиниці.
modestringтак- production — фіскальний режим - test — тестовий режим, усі документи тестові Документи зміни мають режим, у якому зміну відкрито. Змінити режим можна, лише коли зміну закрито.productiontest
statestringтак- closed — зміну закрито - opened — зміну відкрито - offline — офлайн-сесія відкритаclosedopenedoffline

Task object

Завдання фіскального конвеєра. Кожен запит до ДПС сервіс виконує як завдання.

Поле Тип Обовʼязковий Опис
task_idstring (uuid)такІдентифікатор завдання. Статус завдання: GET /v1/tasks/{id}.
typestringтакОперація завдання: - 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
statusstringтак- pending — завдання в черзі - processing — завдання виконується - succeeded — завдання завершилося успішно, дані в result - failed — завдання завершилося помилкою, дані в faultpendingprocessingsucceededfailed
created_atstring (date-time)такЧас створення завдання.
finished_atstring (date-time)—Час завершення завдання. Поля немає, поки завдання виконується.
errorstring—Текст помилки завдання. Структурований опис цієї помилки — у полі fault.
faultFault—Структурований опис помилки завдання. Мову message визначає заголовок Accept-Language. Типова мова — українська. Простори імен коду: - dps.* — помилка ДПС - fiscal.* — валідація документа - return.* — перевірка повернення за початковим чеком - storno.* — перевірка сторно за чеком, який сторно скасовує - signer.* — помилка КЕП - state.* — стан каси
resultTaskResult—Фіскальні поля (prro_id, shift_id, testing та інші) є в результаті завдань на чек, зміну та офлайн-сесію. Завдання verify_key повертає лише key_verification.

Fault object

Структурований опис помилки завдання. Мову message визначає заголовок Accept-Language. Типова мова — українська. Простори імен коду: - dps.* — помилка ДПС - fiscal.* — валідація документа - return.* — перевірка повернення за початковим чеком - storno.* — перевірка сторно за чеком, який сторно скасовує - signer.* — помилка КЕП - state.* — стан каси

Поле Тип Обовʼязковий Опис
codestringтакСтабільний ідентифікатор помилки. Приклад: dps.check_local_number_invalid.
classstringтакДія, яка може виправити помилку: - resync — звірити стан каси з ДПС - config — виправити налаштування каси - precursor — виконати пропущений попередній крок - user_action — потрібне рішення людини - transient — тимчасова недоступність, повторіть запит - request — виправити запит - internal — внутрішня помилка сервісуresyncconfigprecursoruser_actiontransientrequestinternal
paramsobject—Значення для підстановки в message.
messagestring—Текст для людини з каталогу помилок, перекладений мовою з Accept-Language.
upstream_messagestring—Текст помилки від ДПС без змін.
remediationarray<string>—Автоматичні виправлення, які сервіс виконав під час завдання.local_number_syncedshift_adoptedshift_abandonedzreport_recoveredzreport_autofiledregister_config_filled

TaskResult object

Фіскальні поля (prro_id, shift_id, testing та інші) є в результаті завдань на чек, зміну та офлайн-сесію. Завдання verify_key повертає лише key_verification.

Поле Тип Обовʼязковий Опис
prro_idstring (uuid)—Каса, на якій сервіс виконав завдання.
shift_idstring (uuid)—Зміна, у якій сервіс створив документи завдання.
shift_numberinteger (int64)—Наскрізний номер зміни в межах каси. Номер присвоює сервіс. ДПС не присвоює номерів змін, у квитанції ДПС цього поля немає.
testingboolean—Документи завдання тестові: каса в тестовому режимі.
receiptDocResult—Чек, який створило завдання receipt.
shift_openDocResult—Документ відкриття зміни.
zreportDocResult—Z-звіт, яким сервіс закрив зміну.
shift_closeDocResult—Документ закриття зміни.
offline_endDocResult—Документ закриття офлайн-сесії.
offline_abandonOfflineAbandonResult—Результат відмови від офлайн-сесії (abandon_offline_session).
key_verificationKeyVerificationResult—Результат перевірки ключа КЕП. Це поле повертає завдання verify_key.
key_password_checkKeyPasswordCheckResult—Результат швидкої перевірки пароля контейнера. Сервіс лише розшифровує контейнер і не надсилає запитів у мережу. Завдання завершується успішно і при ok = false, тому що перевірка дала результат. Якщо сталася внутрішня помилка, результату немає, і сервіс повторює завдання.
reconcileReconcileReport—Результат звіряння каси з ДПС (sync_register): дані ДПС і виправлення, які сервіс виконав у своїх даних.
dps_objectsarray<DPSTaxObject>—Господарські одиниці власника ключа. Це поле повертає завдання dps_objects.

OfflineAbandonResult object

Результат відмови від офлайн-сесії (abandon_offline_session).

Поле Тип Обовʼязковий Опис
session_idstring (uuid)такОфлайн-сесія, від якої відмовилися.
dps_session_idinteger (int64)такНомер офлайн-сесії, який присвоїла ДПС.
held_documentsinteger (int64)такКількість документів сесії, які ДПС отримала. Ці документи залишаються зареєстрованими.
abandonedarray<AbandonedDocument>такДокументи сесії, яких ДПС не отримала.
closure_session_idstring (uuid)—Офлайн-сесія, якою сервіс закриває в ДПС сесію, від якої відмовилися. Поля немає, якщо ДПС не отримала жодного документа сесії або ДПС уже закрила сесію сама.
closedbooleanтакtrue: сесію закрито в ДПС, каса знову в онлайн-режимі. false: сервіс ще надсилає документ закриття сесії. Доти нові документи каси чекають у черзі.

AbandonedDocument object

Документ офлайн-сесії, від якої відмовилися. Покупець отримав цей документ. Фіскального номера документа в ДПС немає.

Поле Тип Обовʼязковий Опис
document_idstring (uuid)такІдентифікатор документа в журналі сервісу.
task_idstring (uuid)—Завдання, яке створило документ.
classstringтакТип документа.checkzreportopen_shiftclose_shiftoffline_beginoffline_end
kindstring—Тип чека. Поле є лише для class = check.salereturnstornoservice_inservice_out
local_numberinteger (int64)такЛокальний номер документа.
fiscal_numberstring—Офлайн-фіскальний номер, надрукований у документі.
totalstring—Сума документа в гривнях. Поле є лише для чеків.
pay_formstring—Форма оплати. Поле є лише для чеків.cashcashlessmixed
created_atstring (date-time)такЧас створення документа.

ReconcileReport object

Результат звіряння каси з ДПС (sync_register): дані ДПС і виправлення, які сервіс виконав у своїх даних.

Поле Тип Обовʼязковий Опис
fiscal_numberstringтакФіскальний номер каси, яку звіряли.
dps_shift_openedbooleanтакЧи відкрита зміна каси за даними ДПС.
dps_next_local_numberinteger (int64)такЛокальний номер, який ДПС очікує в наступному документі.
dps_testingboolean—Чи тестова каса за даними ДПС.
counter_oldinteger (int64)—Лічильник локальних номерів сервісу до звіряння.
counter_newinteger (int64)—Лічильник локальних номерів сервісу після звіряння.
shift_adoptedboolean—Сервіс прийняв як свою зміну, відкриту в ДПС.
shift_abandonedboolean—Сервіс закрив у своїх даних зміну, якої в ДПС немає.
offline_credentials_refreshedboolean—Сервіс оновив офлайн-ключі каси з даних ДПС.
cashobject—Рух готівки за поточну зміну: за даними сервісу (ours) і за даними ДПС (dps). Поле є лише тоді, коли зміна відкрита в ДПС. Поле довідкове. Сервіс не виправляє розбіжність.
oursCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
dpsCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
matchbooleanтакЧи збігаються дані сервісу і дані ДПС.
totalsobject—Підсумки поточної зміни за даними сервісу і за даними ДПС. Поле є лише тоді, коли зміна відкрита і в ДПС, і в сервісі. Якщо підсумки не збігаються, сервіс надсилає Z-звіт зміни з підсумками ДПС. ДПС не приймає інших підсумків.
oursShiftTotalsBriefтакСуми й кількості чеків зміни, за якими ДПС перевіряє Z-звіт.
dpsShiftTotalsBrief—Поля немає, якщо ДПС не повернула підсумків.
matchbooleanтакЧи збігаються підсумки сервісу і підсумки ДПС.
z_report_sourcestringтакДжерело підсумків для Z-звіту зміни.localdps
forcedboolean—Це звіряння перевело Z-звіт зміни на підсумки ДПС.
heldstring—Причина, з якої сервіс не звірив підсумки або не виправив розбіжність: - dps_totals_unavailable — ДПС не повернула підсумків. У цьому випадку match = false і поля dps немає. - shift_closing — сервіс уже надіслав Z-звіт зміни. - offline_backlog — сервіс ще не надіслав офлайн-документи до ДПС.dps_totals_unavailableshift_closingoffline_backlog
attention_clearedboolean—Сервіс зняв позначку auto_close_failing. Автоматичне закриття зміни знову працює.
skippedstring—Причина, з якої сервіс не виконав звіряння. offline_session: сервіс не звіряє касу, коли офлайн-сесія відкрита.offline_session

ShiftTotalsBrief object

Суми й кількості чеків зміни, за якими ДПС перевіряє Z-звіт.

Поле Тип Обовʼязковий Опис
salesCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
sales_countintegerтакКількість чеків продажу.
returnsCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
returns_countintegerтакКількість чеків повернення.
service_inputCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
service_outputCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

DPSTaxObject object

Господарська одиниця власника ключа (dps_objects).

Поле Тип Обовʼязковий Опис
namestringтакНазва господарської одиниці.
addressstring—Адреса господарської одиниці.
tinstringтакПодатковий номер власника: ЄДРПОУ або РНОКПП.
ipnstring—Індивідуальний податковий номер платника ПДВ.
org_namestringтакНазва суб'єкта господарювання.
registrarsarray<DPSRegistrar>такКаси, зареєстровані в ДПС за цією господарською одиницею.

DPSRegistrar object

Каса, зареєстрована в ДПС за господарською одиницею.

Поле Тип Обовʼязковий Опис
fiscal_numberstringтакФіскальний номер каси, який присвоїла ДПС.
local_numberstringтакЛокальний номер каси, який присвоїв власник.
namestring—Назва каси з реєстраційних даних ДПС.
closedboolean—Касу скасовано в ДПС.

KeyPasswordCheckResult object

Результат швидкої перевірки пароля контейнера. Сервіс лише розшифровує контейнер і не надсилає запитів у мережу. Завдання завершується успішно і при ok = false, тому що перевірка дала результат. Якщо сталася внутрішня помилка, результату немає, і сервіс повторює завдання.

Поле Тип Обовʼязковий Опис
signing_key_idstring (uuid)такКлюч, пароль якого перевіряли.
okbooleanтакПароль правильний: сервіс розшифрував контейнер.
verify_codestring—Код причини. Поле є завжди при ok = false. Приклад: wrong_password.
verify_errorstring—Текст помилки бібліотеки підпису без змін.

KeyVerificationResult object

Результат повної перевірки ключа КЕП: чи можна підписувати ключем документи каси і хто власник ключа.

Поле Тип Обовʼязковий Опис
signing_key_idstring (uuid)такКлюч, який перевіряли. Якщо deleted = true, ключа в сервісі вже немає.
statusstringтак- active — ключ можна використовувати - invalid — сервіс відхилив ключ, причина в verify_codeactiveinvalid
verify_codestring—Причина відхилення. Ключ із причиною not_prro можна активувати через POST /cabinet/signing-keys/{id}/activate.wrong_passwordcert_not_foundcert_expirednot_prroverify_failedca_unreachable
verify_errorstring—Текст помилки перевірки без змін.
key_typestring—Тип власника ключа за даними сертифіката.individuallegal
prro_capablebooleanтакСертифікат дозволяє підписувати документи каси.
cert_subjectstring—Поле subject сертифіката, як його записав АЦСК.
org_namestring—Назва суб'єкта господарювання або ім'я фізичної особи з сертифіката.
edrpoustring—ЄДРПОУ юридичної особи з сертифіката, лише цифри.
drfostring—РНОКПП (ДРФО) фізичної особи з сертифіката, лише цифри.
deletedboolean—Сервіс видалив ключ. Сервіс видаляє ключ за будь-якої причини відхилення, крім not_prro.

DocResult object

Документ, який створило завдання: номери в сервісі і в ДПС, посилання для покупця.

Поле Тип Обовʼязковий Опис
document_idstring (uuid)такІдентифікатор документа в журналі сервісу.
local_numberintegerтакНаскрізний номер документа в межах каси (ORDERNUM).
fiscal_numberstringтакФіскальний номер документа, який присвоїла ДПС.
register_fiscal_numberstringтакФіскальний номер каси, у якій сервіс створив документ. У чеку це «ФН ПРРО» (CASHREGISTERNUM). Це номер каси, а не документа. На відміну від fiscal_number, цей номер однаковий в онлайн-режимі і в офлайн-сесії. Поле є завжди.
offlineboolean—Сервіс підписав документ в офлайн-сесії. Сервіс обчислив фіскальний номер локально (<sid>.<n>.<crc>). ДПС отримає документ лише разом із пакетом офлайн-сесії.
receipt_urlstring (uri)—Копія чека для покупця на короткому домені сервісу (https://r.prro.cloud/<код>). Посилання надсилають покупцю або перетворюють на QR-код. Сторінка відкривається без авторизації: доступ дає код у посиланні. Формат задає параметр запиту ?format=: - html (типовий) — сторінка чека - png — зображення чека шириною 576 px (стрічка 80 мм для термопринтера) з QR-кодом - qr — PNG із QR-кодом адреси цієї сторінки Поле є лише в чеках. Посилання працює одразу, також в офлайн-сесії. Сторінка — копія чека, а не підтвердження фіскалізації. Підтвердження фіскалізації: fiscal_number і tax_url.
tax_urlstring (uri)—Цей документ в Електронному кабінеті платника податків ДПС. Це незалежне підтвердження фіскалізації. Поля немає, доки ДПС не отримала документ. До надсилання пакета офлайн-сесії офлайн-чек має лише фіскальний номер, який сервіс обчислив локально.
originalReturnOriginal—Початковий чек повернення. Поле є лише в чеку повернення.
totalsZReportTotals—Підсумки Z-звіту: ті самі суми, що в документі, який сервіс надіслав до ДПС. Поле є лише в Z-звіті. realiz — продажі, return — повернення. Якщо в зміні не було повернень, службових внесень або службових видач, відповідні суми дорівнюють нулю. Z-звіт, який сервіс створив в офлайн-сесії (offline: true), ДПС отримує пізніше, разом з іншими документами офлайн-сесії.

ReturnOriginal object

Початковий чек повернення. Поле є лише в чеку повернення.

Поле Тип Обовʼязковий Опис
fiscal_numberstringтакФіскальний номер початкового чека.
document_idstring (uuid)—Початковий чек у журналі сервісу. Поля немає, якщо verified = false.
verifiedbooleanтакtrue: сервіс створив початковий чек і перевірив повернення за залишком цього чека. false: початкового чека в сервісі немає, його створила інша каса. Сервіс прийняв повернення без перевірки.

ReceiptInput oneOf

Три форми запиту на чек. Форму визначає поле type: - продаж і повернення — позиції та оплати - сторно — лише посилання на чек - службове внесення і службова видача — лише сума Сервіс не ігнорує поля іншої форми. Для таких полів сервіс повертає 422.

Одна з форм розрізняє поле: type

SettlementReceiptInput object

Чек продажу або повернення товарів.

Поле Тип Обовʼязковий Опис
cash_register_idstring (uuid)—Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422.
typestringтак- sale — продаж - return — поверненняsalereturn
cashierstring—Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка.
commentstring—Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Приклад: номер замовлення.
sold_atstring (date-time)—Час фактичного продажу, якщо чек надійшов до сервісу пізніше. Це не фіскальний час чека. ДПС приймає ORDERDATE/ORDERTIME лише в межах приблизно однієї хвилини від свого часу. Тому фіскальний час чека — час надсилання. Сервіс друкує в чеку рядок «Продаж від 03.09.2026 18:11» перед приміткою з comment. Для часу в майбутньому або часу, старшого за 31 день, сервіс повертає 422.
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync
originalobject—Посилання на початковий чек. Поле обов'язкове для повернення. Якщо сервіс створив початковий чек, сервіс перевіряє повернення за цим чеком. Початковий чек має відповідати всім умовам: - це чек продажу - режим чека той самий: тестовий або фіскальний - сторно не скасовувало цей чек - сума всіх повернень за чеком не перевищує суми продажу до заокруглення Якщо умову не виконано, завдання завершується помилкою з кодом return.*, і сервіс не реєструє чек. Якщо початкового чека в сервісі немає, сервіс приймає повернення без перевірки. Див. result.receipt.original.verified.
fiscal_numberstringтакФіскальний номер початкового чека.
register_fiscal_numberstring—Фіскальний номер каси, у якій створено початковий чек, якщо це інша каса. Якщо поля немає, сервіс шукає початковий чек на касі повернення.
datestring (date)—Дата початкового чека у форматі РРРР-ММ-ДД.
itemsarray<ReceiptItem>такПозиції чека, щонайменше одна.
paymentsarray<ReceiptPayment>такОплати чека, щонайменше одна.
rounding_stepstring—Крок заокруглення готівки, десятковий рядок ("0.10" за правилами НБУ). Якщо поля немає, сервіс не заокруглює суму.

StornoReceiptInput object

Сторно попереднього чека (DOCSUBTYPE 5). Сторно скасовує чек продажу або повернення, який зареєстрували помилково. Сторно не містить позицій, оплат і суми. ДПС реєструє сторно з нульовою сумою. Сторно може скасувати лише останній документ каси. Цей документ має бути чеком продажу або повернення, який створив сервіс і який сторно ще не скасовувало. Інакше завдання завершується помилкою з кодом storno.*, і сервіс не реєструє сторно. Щоб скасувати чек, після якого є інші документи, зареєструйте повернення. Сервіс змінює підсумки зміни і залишок готівки на суми скасованого чека у зворотному напрямку.

Поле Тип Обовʼязковий Опис
cash_register_idstring (uuid)—Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422.
typestringтакstorno
cashierstring—Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка.
commentstring—Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Приклад: причина сторно.
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync
originalobjectтакЧек, який скасовує сторно.
fiscal_numberstringтакФіскальний номер чека, який скасовує сторно.

ServiceReceiptInput object

Рух готівки без продажу: - service_in — службове внесення (DOCSUBTYPE 2) - service_out — службова видача (DOCSUBTYPE 4) Сервіс обробляє цей чек так само, як інші чеки. В автоматичному режимі змін чек відкриває зміну. Чек працює в офлайн-сесії. Сервіс записує чек у журнал і тарифікує його як чек. У підсумках зміни сума входить окремо в service_input/service_output і в ZREPBODY Z-звіту. Сервіс змінює cash_balance на всю суму. Сервіс не підтримує отримання підкріплення (DOCSUBTYPE 3).

Поле Тип Обовʼязковий Опис
cash_register_idstring (uuid)—Каса, на якій сервіс реєструє чек. Поле обов'язкове для POST /v1/receipts. Якщо URL маршруту вже містить касу, поле має збігатися з цією касою або поля немає. Інакше сервіс повертає 422.
typestringтак- service_in — службове внесення - service_out — службова видачаservice_inservice_out
cashierstring—Ім'я касира, яке сервіс друкує в чеку (CASHIER). Якщо поля немає, чек не містить цього рядка.
commentstring—Довільна примітка, яку сервіс друкує в чеку (CHECKHEAD/COMMENT). Для руху готівки лише примітка вказує призначення суми. Приклади: «Інкасація», «Розмінна монета».
sold_atstring (date-time)—Час фактичного продажу, якщо чек надійшов до сервісу пізніше. Це не фіскальний час чека. ДПС приймає ORDERDATE/ORDERTIME лише в межах приблизно однієї хвилини від свого часу. Тому фіскальний час чека — час надсилання. Сервіс друкує в чеку рядок «Продаж від 03.09.2026 18:11» перед приміткою з comment. Для часу в майбутньому або часу, старшого за 31 день, сервіс повертає 422.
modestring—Режим відповіді. Параметр запиту ?mode= має пріоритет над цим полем.syncasync
sumstringтакСума руху готівки: додатний десятковий рядок, до 2 знаків після коми. Чек не містить позицій.

ReceiptItem object

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

Поле Тип Обовʼязковий Опис
codestring—Внутрішній код товару.
barcodestring—Штрихкод товару.
uktzedstring—Код УКТЗЕД. Не використовуйте разом із dkpp.
dkppstring—Код ДКПП. Не використовуйте разом із uktzed.
namestringтакНазва позиції, яку сервіс друкує в чеку.
unit_codeinteger—Код одиниці виміру (UNITCD).
unit_namestring—Назва одиниці виміру. Приклади: «шт», «кг».
quantitystringтакКількість, десятковий рядок, до 3 знаків після коми.
pricestringтакЦіна за одиницю, десятковий рядок, до 2 знаків після коми.
tax_lettersstring—Податкові літери з tax_rates каси. Приклади: "А", "АГ". Порожнє значення застосовує default_tax_letter каси. Якщо типової літери немає, позиція не має податку. Значення "-" робить позицію неоподатковуваною.
discountobject—Знижка на позицію.
percentstring—Позначає знижку як відсоткову. Суму знижки вказують у sum.
sumstringтакСума знижки, десятковий рядок. Поле обов'язкове також для відсоткової знижки.
excise_labelsarray<string>—Коди акцизних марок.
commentstring—Примітка до позиції.

PaymentType string

Форма оплати. Фіскальний код і назву форми оплати в чеку визначає сервіс: - cash — 0 ГОТІВКА - card — 301 КАРТКА - certificate — 305 СЕРТИФІКАТ - bank_transfer — 306 ПЕРЕКАЗ З ПОТОЧНОГО РАХУНКУ - direct_debit — 100000 ПРЯМИЙ ДЕБЕТ Залишок готівки каси змінює лише cash.

cashcardcertificatebank_transferdirect_debit

ReceiptPayment object

Одна оплата чека: форма оплати, сума і, для картки, реквізити еквайрингу.

Поле Тип Обовʼязковий Опис
typePaymentTypeтакФорма оплати. Фіскальний код і назву форми оплати в чеку визначає сервіс: - cash — 0 ГОТІВКА - card — 301 КАРТКА - certificate — 305 СЕРТИФІКАТ - bank_transfer — 306 ПЕРЕКАЗ З ПОТОЧНОГО РАХУНКУ - direct_debit — 100000 ПРЯМИЙ ДЕБЕТ Залишок готівки каси змінює лише cash.
sumstringтакСума цієї оплати.
providedstring—Сума, яку покупець дав готівкою. Решта = provided − sum.
meansstring—Засіб оплати: чим саме покупець оплатив. Положення № 13 (розд. II п. 2, рядок 19) вимагає вказувати засіб оплати окремо від форми оплати. Значення — ті самі, що в прикладах ДПС: «Картка», «Переказ з поточного рахунку», «Подарунковий сертифікат», «Попередня оплата», «Прямий дебет». Також значення, яких немає в type: «ПЕРЕКАЗ З КАРТКИ», «ТАЛОН», «ЖЕТОН». Поле замінює лише назву форми оплати, яку сервіс друкує (PAYFORMNM). Фіскальний код форми оплати (PAYFORMCD) визначає type. Для cash сервіс не приймає це поле.
cardobject—Реквізити еквайрингу (рядки 12–17). Усі три поля acquirer_* описують еквайра торговця, а не торговця.
system_namestring—Назва платіжної системи (рядок 17).
acquirer_idstring—Ідентифікатор еквайра (рядок 12).
acquirer_tax_idstring—Податковий номер еквайра (рядок 12).
acquirer_namestring—Назва еквайра (рядок 12).
transaction_datestring (date-time)—Дата й час транзакції на платіжному пристрої (POSTRANSDATE).
transaction_numberstring—Номер транзакції на платіжному пристрої (POSTRANSNUM).
device_idstring—Ідентифікатор платіжного пристрою (рядок 13).
epz_detailsstring—Замаскований номер картки.
auth_codestring—Код авторизації (рядок 17).
commissionstring—Сума комісії еквайра за цією оплатою: рядок 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_idstring (uuid)такКаса.
shift_idstring (uuid)такЗміна.
task_idstring (uuid)такЗавдання, яке відкрило або закрило зміну. Зазвичай це завдання open_shift або close_shift. Зміну також може закрити завдання receipt, якщо попереднє закриття не завершилося, або автоматичне виправлення розбіжності з ДПС.
testingbooleanтакТестова зміна: каса в тестовому режимі.
zreportDocResult—Поле є лише в shift.closed. Z-звіт, яким сервіс закрив зміну, разом із підсумками (totals). Якщо зміну закрило завдання close_shift, це той самий об'єкт, що в result.zreport цього завдання. Поля немає, якщо в сервісі немає Z-звіту цієї зміни.

ReceiptRegisteredData object

Дані події receipt.registered: чек у тому вигляді, у якому його отримала ДПС. Суми — десяткові рядки в гривнях, як у запиті на чек.

Поле Тип Обовʼязковий Опис
cash_register_idstring (uuid)такКаса.
register_fiscal_numberstringтакФіскальний номер каси.
document_idstring (uuid)такЧек у журналі сервісу.
task_idstring (uuid)такЗавдання, яке зареєструвало чек.
typestringтакТип чека.salereturnstornoservice_inservice_out
sourcestringтакДжерело запиту на чек — API або кабінет.apicabinet
user_idstring (uuid)—Обліковий запис кабінету, з якого надіслано запит на чек. Поле є лише для source = cabinet. Власник бачить цей обліковий запис у переліку команди.
cashierstring—Ім'я касира, надруковане в чеку.
local_numberinteger (int64)такЛокальний номер чека.
fiscal_numberstringтакФіскальний номер чека. В офлайн-сесії сервіс обчислює номер локально.
offlinebooleanтакСервіс створив чек в офлайн-сесії.
testingbooleanтакТестовий чек.
shift_idstring (uuid)такЗміна.
shift_numberinteger (int64)—Номер зміни в межах каси.
issued_atstring (date-time)такДата й час чека, як їх надруковано.
totalstringтакСума до сплати. Для службового внесення і службової видачі — сума руху готівки. Для сторно — 0.00.
roundingstring—Сума заокруглення готівки. Поля немає, якщо заокруглення не було.
itemsarray<object>—Позиції чека.
codestring—
barcodestring—
uktzedstring—
dkppstring—
namestringтак
unit_namestring—
quantitystringтак
pricestringтак
coststring—Вартість позиції до знижки.
tax_lettersstring—
discountstring—Сума знижки.
paymentsarray<object>—Оплати чека.
typestring—Форма оплати, як у запиті на чек.
namestringтакНазва форми оплати, надрукована в чеку.
sumstringтак
taxesarray<TaxTotal>—Податки чека.
commentstring—Примітка, надрукована в чеку.
originalobject—Початковий чек повернення або чек, який скасовує сторно.
fiscal_numberstringтак
document_idstring (uuid)—Початковий чек у журналі сервісу. Поля немає, якщо чека немає в журналі.
verifiedbooleanтакЛише для повернення: сервіс знайшов початковий чек у журналі і перевірив залишок за ним.
receipt_urlstring—Копія чека для покупця.
tax_urlstring—Чек в Електронному кабінеті платника податків ДПС. Поля немає, доки ДПС не отримала офлайн-чек.

WebhookEndpoint object

Вебхук: URL приймача і події, які сервіс доставляє.

Поле Тип Обовʼязковий Опис
idstring (uuid)такІдентифікатор вебхука.
urlstringтакАбсолютний http(s)-URL приймача.
eventsarray<WebhookEvent>такПорожній список означає підписку на всі події.task.completedtask.failedshift.openedshift.closedkey.expiringregister.offlineregister.onlineregister.offline_limitregister.offline_abandonedregister.remediatedregister.needs_attentionclient.balance_lowreceipt.registered
activebooleanтакДоставка ввімкнена. false: сервіс призупиняє доставку, черга доставок зберігається.
created_atstring (date-time)такЧас створення вебхука.
updated_atstring (date-time)такЧас останньої зміни вебхука.

WebhookDelivery object

Одна доставка події та її статус.

Поле Тип Обовʼязковий Опис
idstring (uuid)такІдентифікатор доставки. Це значення вказують у шляху replay.
eventstringтакТип події. Крім значень WebhookEvent, доставка може мати зарезервовані типи без підписки: webhook.ping (тестова доставка) і system.dps_* (події доступності ДПС).
statusstringтак- pending — доставка в черзі - delivering — спроба виконується - delivered — подію доставлено - failed — спроба невдала, сервіс виконає повторну спробу - dead — спроби закінчилисяpendingdeliveringdeliveredfaileddead
attemptsintegerтакКількість виконаних спроб.
cash_register_idstring (uuid)—Каса події. Поля немає для подій рівня клієнта.
sequenceinteger (int64)—Номер події в межах каси (поле sequence конверта). За цим номером упорядковують події. Поля немає для подій рівня клієнта.
dataanyтакДані події (поле data конверта).
last_errorstring—Результат останньої невдалої спроби: код і початок відповіді приймача або причина помилки з'єднання (наприклад, TLS).
next_attempt_atstring (date-time)—Час наступної спроби. Поля немає, якщо спроб більше не буде.
created_atstring (date-time)такЧас, коли сервіс поставив подію в чергу.
delivered_atstring (date-time)—Час, коли приймач повернув успішну відповідь.

Money string

Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.

CashAmount string

Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

CashBalance object

Залишок готівки в касі. Це не фіскальне значення. Залишок готівки дорівнює нулю, коли касу створено. Залишок готівки враховує лише документи, які пройшли через цей сервіс. Залишок готівки змінюють: - готівкові оплати: продаж додає суму, повернення віднімає суму, сторно скасовує зміну від скасованого чека - службове внесення і службова видача Безготівкові оплати не змінюють залишок готівки. Сервіс бере sum оплати, решту вже враховано. Залишок готівки належить касі, а не зміні. Z-звіт не скидає залишок готівки. Від'ємне значення означає, що в касі було більше готівки, ніж зареєстрував сервіс. Встановити залишок готівки: PUT /v1/cash-registers/{id}/cash-balance.

Поле Тип Обовʼязковий Опис
amountCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
as_ofstring (date-time)—Час останньої зміни залишку готівки. null: змін ще не було. Тоді нуль означає «немає даних», а не «каса порожня».

ShiftTotalsSide object

Продажі або повернення: кількість чеків, сума і суми за формами оплати.

Поле Тип Обовʼязковий Опис
countintegerтакКількість чеків.
sumCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
pay_formsarray<object>—Суми за формами оплати. code і name — код і назва форми оплати, як у Z-звіті (PAYFORMCD і PAYFORMNM). Поля немає, якщо чеків немає.
codeintegerтакPAYFORMCD: фіскальний код форми оплати.
namestringтакPAYFORMNM: назва форми оплати, яку сервіс друкує.
sumCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

ShiftTotals object

Підсумки відкритої зміни на поточний момент. З цих сум сервіс створить Z-звіт під час закриття зміни. realiz — продажі, return — повернення. Скасовані чеки не входять у підсумки. Сервіс віднімає скасований чек із продажів або повернень. Службові внесення і службові видачі входять окремо: у service_in і service_out. Сум за податками тут немає. Суми за податками є в підсумках Z-звіту (ZReportTotals) після закриття зміни.

Поле Тип Обовʼязковий Опис
realizShiftTotalsSideтакПродажі або повернення: кількість чеків, сума і суми за формами оплати.
returnShiftTotalsSideтакПродажі або повернення: кількість чеків, сума і суми за формами оплати.
service_inCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
service_outCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

TaxTotal object

Податок за однією ставкою: оборот і сума податку.

Поле Тип Обовʼязковий Опис
letterstring—Податкова літера. Приклад: «А».
namestringтакНазва податку. Приклад: «ПДВ».
ratestringтакСтавка у відсотках. Приклад: «20.00».
turnoverstringтакОборот: сума продажів за цією ставкою.
sumstringтакСума податку.
excludedboolean—true: сервіс додав податок до ціни, податок не входить у ціну.

ZReportTotalsSide object

Продажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками.

Поле Тип Обовʼязковий Опис
countintegerтакКількість чеків.
sumCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
pay_formsarray<object>—Суми за формами оплати. code і name — код і назва форми оплати, як у Z-звіті (PAYFORMCD і PAYFORMNM). Поля немає, якщо чеків немає.
codeintegerтакPAYFORMCD: фіскальний код форми оплати.
namestringтакPAYFORMNM: назва форми оплати, яку сервіс друкує.
sumCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
taxesarray<TaxTotal>—Податки за ставками. Поля немає, якщо податків не було.

ZReportTotals object

Підсумки Z-звіту: ті самі суми, що в документі, який сервіс надіслав до ДПС. Поле є лише в Z-звіті. realiz — продажі, return — повернення. Якщо в зміні не було повернень, службових внесень або службових видач, відповідні суми дорівнюють нулю. Z-звіт, який сервіс створив в офлайн-сесії (offline: true), ДПС отримує пізніше, разом з іншими документами офлайн-сесії.

Поле Тип Обовʼязковий Опис
realizZReportTotalsSideтакПродажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками.
returnZReportTotalsSideтакПродажі або повернення за зміну: кількість чеків, сума, суми за формами оплати і за податками.
service_inCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
service_outCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

CashBalanceDeclaration object

Залишок готівки до заяви, після заяви і різниця між ними.

Поле Тип Обовʼязковий Опис
amountCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
previousCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.
adjustmentCashAmountтакГривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація.

BillingUsage object

Баланс і підсумок тарифікації за період.

Поле Тип Обовʼязковий Опис
balanceMoneyтакКопійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.
soft_limitMoneyтакПоріг балансу. Поки balance < soft_limit, сервіс відхиляє чеки.
blockedbooleanтакСервіс зараз відхиляє чеки через баланс або за рішенням оператора.
periodobjectтакПеріод підсумку.
fromstring (date)такДата входить у період.
tostring (date)такДата не входить у період.
receiptsinteger (int64)такКількість тарифікованих чеків за період.
chargedMoneyтакКопійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.
tariffobjectтакТариф, за яким сервіс тарифікував чеки.
plan_idstring (uuid)такІдентифікатор тарифного плану.
price_per_receiptMoneyтакЦіна чека до першого порога з price_tiers.
price_tiersarray<PriceTier>такЦіни чека за обсягом, від найменшого порога. Сервіс рахує чеки кожної каси окремо за календарний місяць за київським часом. Порожній масив означає одну ціну для всіх чеків.

PriceTier object

Ціна чека понад порогову кількість чеків каси за місяць.

Поле Тип Обовʼязковий Опис
above_receiptsinteger (int32)такПорог. Ціна діє для чеків каси, номер яких у місяці більший за порог.
priceMoneyтакКопійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.

Invoice object

Рахунок за один розрахунковий період.

Поле Тип Обовʼязковий Опис
idstring (uuid)такІдентифікатор рахунка.
period_startstring (date)такДата входить у період.
period_endstring (date)такДата входить у період.
amountMoneyтакКопійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.
currencystringтакВалюта рахунка за ISO 4217: UAH.
statusstringтак- draft — чернетка - issued — рахунок виставлено - paid — рахунок оплачено - overdue — рахунок простроченоdraftissuedpaidoverdue
created_atstring (date-time)такЧас створення рахунка.

DPSPulse object

Режим роботи з ДПС і телеметрія, яка пояснює цей режим. Сервіс працює з ДПС за значенням effective.

Поле Тип Обовʼязковий Опис
effectivestringтакПоточний режим роботи сервісу з ДПС.onlineoffline
verdictstringтакРезультат детектора. Значення degraded означає «повільно», offline — «недоступно».onlinedegradedoffline
sincestring (date-time)такЧас, з якого діє поточне значення effective.
latency_msinteger (int64)такЗатримка успішних запитів у вікні детектора, у мілісекундах. Значення 0 означає, що у вікні немає успішних запитів.
samplesintegerтакКількість запитів у вікні детектора.
failuresintegerтакКількість невдалих запитів у вікні детектора.
last_ok_atstring (date-time)—Час останньої успішної відповіді ДПС.
last_probe_atstring (date-time)—Час останньої перевірки доступності ДПС.
tunablesobjectтакПороги для значень вище: ширина вікна детектора, поріг degraded і інтервал перевірок.
window_secondsinteger (int64)такШирина вікна детектора, у секундах.
degraded_latency_msinteger (int64)такЗатримка, від якої відповідь вважається повільною, у мілісекундах.
probe_interval_secondsinteger (int64)такІнтервал перевірок, у секундах.