Перейти до змісту

Робота з ПРРО (черга фіскалізації)

Документ описує як Каса фіскалізує чеки, операції з готівкою та зміни на сервері податкової (ДПС) через Абхард, а також дії касира у типових ситуаціях.

Початок роботи

Щоб каса могла працювати з РРО, потрібно у конфігурації профілю вказати ІД з таблиці R_RRO та мати активний абхард з активним же roo як у прикладі нижче: 

---
location:
  rro: 1
abhard:
  enabled: true
  url: http://192.168.12.34:4601/
  rro:
    enabled: true
    type: eusign
    name: default_prro

При запуску каси у такому випадку відпрацьовує ініціалізація ПРРО що складається з наступних кроків:

  1. Отримати інформацію про підприємця на котрого зареєстровано ПРРО і додати її у заголовок.
  2. Перевірити чи є незакрита попередня фіскальна зміна, уточнити у користувача що з нею робити.
  3. Перевірити чи є активна фіскальна зміна, отримати інформацію про неї якщо є.
  4. Запустити фоновий потік для роботи з фіскальними документами.

Вся робота з фоновими документами зараз ведеться виключно через фоновий потік, окремий підпроцес всередині каси що запускається при старті і працює весь час поки запущена програма. Коли користувач створює новий фіскальний документ - чек продажу, повернення, сторно, службова видача/внесення готівки, відкриття/закриття зміни, Z-звіт - цей документ спершу записується у таблицю RRO_DOCS з параметрами DOC_STATUS=0, LAST_ERROR_KIND=0, та LAST_ATTEMPT_AT=NULL після чого фоновому потоку віддається сигнал "до роботи" і каса готова для подальшої взаємодії з користувачем.

Фіскалізація чеку

  1. Касир натискає «Фіскалізувати чек».
  2. Каса вставляє новий рядок у RRO_DOCS (DOC_STATUS = 0) та чекає на відповідь до 2 секунд.
  3. У штатній ситуації за цей час сервер ДПС встигає відповісти, DOC_STATUS стає 1, чек друкується разом з фіскальним номером.
  4. Якщо сервер не відповів за 2 секунди — Каса показує повідомлення «Сервер ДПС не відповів за відведений час. Документ у черзі.» Касир продовжує роботу. Документ залишається в RRO_DOCS зі статусом 0 і буде надісланий автоматично коли сервер відповість. У інтерфейсі каси з'являється кнопка роботи з чергою фіскалізації і повідомлення (документів у черзі: N, причина) де N — кількість документів у черзі, а причина — категорія проблеми верхнього документа (мережа, ВІДХИЛЕНО СЕРВЕРОМ ДПС, внутрішня помилка).

Послідовність взаємодії

Діаграма нижче показує два можливих шляхи фіскалізації чеку — швидкий (сервер ДПС відповідає за відведені 2 секунди) і відкладений (відповідь не встигла надійти, документ залишається у черзі).

sequenceDiagram
    actor Касир
    participant UI as Каса
    participant Worker as Фоновий потік
    participant ДПС as ДПС (через Абхард)

    Касир->>UI: «Фіскалізувати чек»
    Note over UI: Записати документ у чергу<br/>(статус: очікує)
    UI->>Worker: Почати обробку
    activate Worker
    Note over UI: Чекати відповіді ≤ 2 с

    Worker->>ДПС: Надіслати документ

    alt Відповідь встигла за 2 с
        ДПС-->>Worker: Фіскальний номер
        Note over Worker: Оновити статус у черзі
        Worker-->>UI: Готово
        UI-->>Касир: Друк чеку з фіск. номером
    else Відповідь запізнилась
        UI-->>Касир: «Документ у черзі»
        Note over Worker,ДПС: Спроби тривають у фоні
        ДПС-->>Worker: Фіскальний номер (пізніше)
        Note over Worker: Оновити статус у черзі
        Worker->>UI: Оновити лічильник черги
    end
    deactivate Worker

Робота при недоступності серверів ДПС

Якщо сервери податкової недоступні, каса продовжує приймати документи у чергу фіскалізації. Кожна нова фіскалізація додає рядок у RRO_DOCS. Паралельно фоновий потік повторює спроби фіскалізації поки сервер не відповість:

  • при мережевих помилках (LAST_ERROR_KIND = 1) — кожні 5 секунд;
  • при відхиленні сервером або внутрішній помилці (LAST_ERROR_KIND = 2 чи 3) — раз на 10 хвилин, бо без втручання людини повторна спроба нічого не змінить. Після усунення причини можна не чекати паузу: кнопка «Ще раз» у вікні черги фіскалізації запускає спробу негайно.

Як тільки зв'язок відновлюється, черга обробляється підряд від найстарішого документа (з найменшим LOCALNUM); кожен документ реєструється одразу після попереднього.

Обмеження: одночасно в черзі може накопичитися до 10 нефіскалізованих документів на зміну. Це запобіжник від нескінченного росту черги при тривалій недоступності. Після досягнення ліміту нові фіскальні операції відхиляються з повідомленням про перевищення ліміту, доки черга не почне розсмоктуватися.

Робота декількох екземплярів Каси з одним ПРРО

З одним ПРРО можуть одночасно працювати декілька екземплярів Каси, що підключені до однієї бази даних. Це штатний сценарій — наприклад, два робочих місця касирів у магазині, що ділять один реєстратор. Координація між екземплярами повністю автоматична, без додаткових налаштувань.

Гарантії

  • Один лідер на ПРРО в кожний момент часу. Кожна Каса має свій фоновий потік, але реально надсилає документи до Абхард тільки той, що тримає оренду в таблиці RRO_DRAIN_LEASE. Інші просто очікують. Це виключає одночасне надсилання одного й того самого документа двома Касами та потенційні проблеми з подвійними нарахуваннями у ДПС.
  • LOCALNUM зростає глобально. Лічильник RRO_LOCALNUM_SEQ.LAST_NUM спільний для всіх екземплярів та оновлюється під час вставки в RRO_DOCS. Якщо Каса A вставила документ з LOCALNUM = 17, наступна вставка від Каси B отримає LOCALNUM = 18, незалежно від того, чи був документ A надісланий до ДПС.
  • Автоматичне перебирання оренди. Якщо лідер «впав» (програма закрилася, машина перезавантажена, мережа зникла) — оренда автоматично переходить до іншого екземпляра не пізніше ніж за 30 секунд. Перевірка живості йде через службовий функціонал Firebird mon$attachments.

Сценарій недоступності серверів ДПС

Розглянемо типовий сценарій з двома Касами A та B, обидві фіскалізують чеки, ДПС недоступний:

  1. Касир A натискає «Фіскалізувати чек». Каса A вставляє рядок у RRO_DOCS, ловить таймаут на надсиланні, показує повідомлення «Документ у черзі», з'являється кнопка btnFiscalQueue.
  2. Каса A стає лідером оренди (бере її першою) і періодично повторює надсилання у фоні.
  3. Касир B натискає «Фіскалізувати чек» на іншому робочому місці. Каса B вставляє свій рядок у RRO_DOCS (з наступним LOCALNUM), ловить такий самий таймаут, показує повідомлення «Документ у черзі». Тільки в цей момент касир B бачить, що мережа з ДПС зараз не працює.
  4. Каса B спробує надіслати свій документ власним потоком, але оренда зайнята Касою A → потік B нічого не робить, лежить у режимі очікування.
  5. Коли ДПС повертається, Каса A послідовно реєструє свої документи, потім доходить до документа Каси B і так само реєструє його. LOCALNUM-послідовність зберігається.

Чого Каса B не побачить автоматично

За винятком створення нової зміни (котре зараз автоматично "бачиться" всіма касами що працюють з одними і тим же ПРРО), решта індикаторів інтерфейсу оновлюється лише за власними діями кожної Каси. Поки касир B нічого не фіскалізує, інтерфейс Каси B не показує, що в Каси A з'явилась черга. Лічильник (у черзі ДПС: N) оновлюється тільки після власних дій касира B або після успішного кроку власного фонового потоку Каси B (коли B стане лідером оренди).

Особливість відкриття зміни

Якщо при першій фіскалізації дня зміна ще не відкрита, Каса відкриває її автоматично. Рядок у RRO_SHIFTS створюється одразу, тому навіть якщо сервер ДПС не підтвердив відкриття за відведені 2 секунди, зміна локально вважається відкритою і касир може продовжити роботу. Документ відкриття зміни просто додається у чергу і буде надісланий разом з рештою документів коли зв'язок відновиться.

Особливість закриття зміни (Z-звіт)

Закриття зміни — єдина операція, що вимагає порожньої черги і живого зв'язку з ДПС:

  1. Якщо у черзі фіскалізації залишилися ненадіслані документи, Каса відмовляє у закритті з повідомленням «У черзі фіскалізації є ненадіслані документи». Потрібно дочекатися їх реєстрації (або свідомо вилучити їх з черги) і повторити закриття. Інакше касир отримав би хибне відчуття завершеного дня, тоді як частина чеків ще не потрапила до податкової.
  2. Z-звіт неможливий без відповіді сервера ДПС: перед закриттям Каса звіряє стан зміни на сервері (LastShiftTotals).
  3. Якщо надіслане закриття не встигло підтвердитися і зареєструвалося фоновим потоком пізніше, повторна команда закриття просто оновить локальний стан — дубль документа закриття не створюється.

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

Як зрозуміти що пішло не так

Разом з чергою фіскалізації у касі з'являється кнопка для її перегляду та при потребі - очищення. Видалення з черги захищене: документ, який уже зареєстровано або який саме зараз надсилається фоновим потоком, вилучити неможливо. При успішному видаленні нумерація LOCALNUM наступних документів у черзі автоматично зсувається, щоб не залишати дірок, а пов'язаний чек знову стає доступним для фіскалізації. Поля бази даних LAST_ERROR_KIND та LAST_ERROR_MSG верхнього документа черги (найменший LOCALNUM з статусом DOC_STATUS = 0) мають наступні значення:

  • LAST_ERROR_KIND = 0 — запис ще не опрацьовувався (спроб реєстрації не було).
  • LAST_ERROR_KIND = 1 (мережа) — Абхард не може зв'язатися з ДПС. Перевірте інтернет на робочому місці Абхард, статус серверів ДПС.
  • LAST_ERROR_KIND = 2 (відхилено) — ДПС відхилив документ. Текст у LAST_ERROR_MSG — це повідомлення від податкової.
  • LAST_ERROR_KIND = 3 (внутрішня помилка) — проблема у Касі або Абхарді, перевірте журнали обох застосунків. Текст у LAST_ERROR_MSG — це повідомлення від Абхарда.
  • LAST_ERROR_KIND = 10 — документ успішно зареєстровано (відповідає DOC_STATUS = 1).

Проміжок між 3 і 10 залишено для майбутніх категорій помилок.

Поле LAST_ATTEMPT_AT містить момент останньої спроби фіскалізації.

Самодіагностика мережі

LAST_ERROR_KIND = 1 каже лише «немає зв'язку з ДПС», але не каже, де саме він обірвався. Це показує самодіагностика: Абхард перевіряє шлях до податкової по щаблях — мережеве підключення, шлюз, DNS, з'єднання з сервером — і зупиняється на першому, що не пройшов.

Перевірка виконується у Лаунчері: оберіть екземпляр Абхарда, у переліку функцій — «Виконати самодіагностику», вкажіть пристрій пРРО і натисніть «Запуск». Триває щонайбільше близько 10 секунд навіть коли мережа мовчить — кожен щабель має власне обмеження часу.

Окремо Абхард виконує таку перевірку сам, після трьох поспіль невдалих звернень до ДПС. Останній такий звіт доступний функцією «Останній звіт самодіагностики» — його варто подивитися першим, бо він знятий у момент збою, а не після нього.

Підсумок перевірки — поле verdict у звіті. Воно визначає, до кого звертатися:

verdict Що це означає і що робити
ok Мережа не винна. Причину шукайте в тексті помилки від ДПС (LAST_ERROR_MSG).
no-link Кабель від'єднано або Wi-Fi не підключений. Перевірте підключення комп'ютера.
dns-failed Не відповідає сервер імен. Питання до провайдера або до налаштувань мережі.
port-refused Блокує брандмауер чи антивірус на цьому комп'ютері. Дозвольте вихідні з'єднання на порт 8609.
port-blocked Мережа працює, але порт 8609 блокується по дорозі. Питання до провайдера.
black-hole З'єднання є, але дані губляться в дорозі. Спробуйте інший канал: кабель замість Wi-Fi або навпаки.
intercepted У мережі стоїть проксі. Його треба вимкнути для адреси податкової.
partial-addresses Зв'язок нестабільний, але працює — повторна спроба зазвичай успішна.
server-error Збій на боці ДПС. Дочекайтеся відновлення, черга фіскалізації нічого не втратить.
clock-skew Час на комп'ютері збився, підписи документів стають недійсними. Увімкніть синхронізацію часу.
key-problem Мережа справна. Перевірте термін дії ключа та правильність пароля до нього.

Решта полів звіту — подробиці по щаблях: link (інтерфейс, шлюз і чи він відповідає), source_ip, dns_ok та dns_ms, addresses з результатом по кожній адресі податкової. Звіт варто передавати у підтримку цілком.

Коли підключення до мережі відсутнє, звіт до Лаунчера не дійде — Лаунчер теж працює по мережі. У цьому випадку дивіться журнал Абхарда на самому робочому місці.

Після успішної фіскалізації поле LAST_ERROR_MSG очищується.