API фіскального сервера

Pages
- Основні положення
- Порядок взаємодії
- Зауваження щодо реалізації
- Сценарії роботи
- Офлайн сесія
- Команди
- Запит стану сервера
- Запит XSD схем
- Запит доступних господарських одиниць
- Запит переліку операторів (касирів)
- Запит стану ПРРО
- Запит чека
- Запит Z-звіту
- Запит переліку змін за період
- Запит переліку документів зміни
- Запит підсумків останньої зміни
- Запит відомостей про документ за локальним номером
- Запит надсилання документа
- Запит надсилання пакета офлайн документів
- Закріплення ПРРО за пристроєм

API фіскального сервера

Офлайн сесія

Explore

Офлайн сесія

Для обробки чеків в режимі офлайн, використовується поняття «Офлайн сесія».

Офлайн сесія обмежена документами «Початок офлайн сесії» і «Завершення офлайн сесії».

Тривалість однієї офлайн сесії не може перевищувати встановлене законодавством значення (36 годин за сесію, 168 годин за місяць). (В програмних РРО рекомендується реалізувати можливість інформування користувача про сплив одного з термінів, дозволених для роботи ПРРО в режимі офлайн).

Кількість документів у межах одної офлайн сесії не обмежена.

Офлайн сесія має унікальний ідентифікатор (число). Ідентифікатор офлайн сесії надається Сервером у відповідь на документ «Відкриття зміни».

Коли Сервер знову стає доступний, ПРРО надсилає пакет, що містить документи: «Початок офлайн сесії», чеки, Z-звіти, «Завершення офлайн сесії». У відповідь Сервер надсилає номер наступної офлайн сесії.

Офлайн сесія застосовується тільки з ПРРО, для якого виданий ідентифікатор офлайн сесії та фіскальні номери із Діапазону. З іншим ПРРО офлайн сесія не може бути застосована.

В межах офлайн сесії може бути відкрито і закрито необмежену кількість змін (якщо зміни не відкриті одночасно і кожному відкриттю нової зміни передує закриття попередньої). Для закриття зміни формується Z-звіт і повідомлення (технічний документ) із типом «Закриття зміни».

Режими онлайн і офлайн

ПРРО знаходиться в режимі онлайн, якщо на ньому не створений документ «Початок офлайн сесії».

ПРРО знаходиться в режимі офлайн, якщо на ньому створений документ «Початок офлайн сесії», що не надісланий на Сервер, і для якого відсутній документ «Завершення офлайн сесії».

Тривалість офлайн сесії

Розрахунок тривалості офлайн сесії здійснюється як різниця між часом реєстрації:

Останнього фінансово значущого документа (чека, Z-звіту) в офлайн сесії, що передує документу типу «Завершення офлайн сесії»

Документа типу «Початок офлайн сесії»

Примітка. Фінансово значущими є документи, які містять інформацію щодо руху або підсумках грошових коштів і товарів/послуг.

Пакет офлайн документів

Коли Сервер стає доступний, ПРРО надсилає один (або декілька) пакетів, що містить документи: «Початок офлайн сесії», чеки, Z-звіти, «Завершення офлайн сесії».

Структура пакету:

<Розмір документа 1 (4 байта))><Документ 1><Розмір документа 2 (4 байта)><Документ 2>…<Розмір документа N (4 байта)><Документ N>

Кожен документ в пакеті повинен бути засвідчений КЕП.

Весь пакет також засвідчується КЕП відправника.

Максимальна кількість документів в пакеті обмежена (100).

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

Сервер надсилає номер наступної офлайн сесії та нове «секретне число» у відповідь на пакет, який містить документ «Завершення офлайн сесії» та поповнює діапазон використаних номерів.

Формат JSON відповіді:

{

"OfflineSessionId": <Ідентифікатор офлайн сесії>,

"OfflineSeed": <"Секретне число" для обчислення фіскального номера офлайн документа>

}

Якщо пакет не містить документ «Завершення офлайн сесії», Сервер надсилає у відповідь "OK".

Відкликання останнього онлайн чека

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

Для усунення такого дублювання:

ПРРО зберігає чек, який надіслано до Сервера, але фіскальний номер не отриманий внаслідок розірвання зв’язку;

Після відновлення зв’язку, ПРРО одержує з Сервера останній зареєстрований чек;

Якщо останній зареєстрований чек дорівнює збереженому, в документі «Початок офлайн сесії» додається елемент <REVOKELASTONLINEDOC>true</REVOKELASTONLINEDOC>.

Примітка. Зазначений порядок стосується лише фінансово значущих документів.

Сторнування останнього чека

Якщо покупець відмовляється від проведеної операції з торгівлі валютними цінностями і при цьому здійснено реєстрацію чека Фіскальним Сервером, або якщо чек з помилковою сумою зареєстрований Фіскальним Сервером:

ПРРО надсилає на Фіскальний Сервер фіскальний чек типу «Чек сторнування попереднього чека» із присвоєним Сервером фіскальним номером, що підлягає сторнуванню, чек має відповідну ознаку «сторно» (елемент <ORDERSTORNUM > Фіскальний номер чека, для якого здійснюється сторнування </ORDERSTORNUM>).

Фіскальний Сервер перевіряє фіскальний номер проведеної розрахункової операції, реєструє операцію «сторно» із нульовим значенням сторнованої суми, присвоює фіскальний номер чеку з ознакою «сторно» та направляє користувачу.

Структура фіскального номера офлайн документа

Фіскальний номер документа, що виданий офлайн, має таку структуру:

<Ідентифікатор офлайн сесії>.<Локальний номер документа в офлайн сесії>.<Контрольне число>

Локальний номер документа в межах кожної офлайн сесії починається з 1 і збільшується послідовно.

Зауваження: Принцип безперервної локальної нумерації документів залишається незмінним. Тобто, поле «Локальний номер документа» продовжує безперервне збільшення значень, незалежно від режиму (онлайн чи офлайн). Значення поля «Локальний номер документа» не дорівнює значенню «Локальний номер документа в офлайн сесії».

Приклад фіскального номера офлайн документа: "82563.25.6127"

(при цьому «Локальний номер документа» може дорівнювати "9537")

Формування Діапазону та облік фіскальних номерів

Новий Діапазон визначається в межах номера офлайн сесії, який видається ПРРО Фіскальним сервером під час першого відкриття зміни на ПРРО.

Діапазон містить послідовний ряд натуральних чисел, починаючи з 1.

Номери із Діапазону використовуються послідовно (1, 2, 3, …), як зазначено в розділі «Структура фіскального номера офлайн документа».

Розрахунок контрольного числа

Одночасно з передачею номера офлайн сесії, Сервер надає ПРРО «секретне число».

Для розрахунку контрольного числа, ПРРО створює текстовий рядок, що містить об’єднання значень, розділених символом «,»:

«Секретне число»

Дата документа (ДДММРРРР)

Час документа (ГГХХСС)

Локальний номер документа

Фіскальний номер реєстратора

Локальний номер реєстратора

Загальна сума оплати по документу класу «Чек» (формат «0.00») (якщо елемент присутній)

Геш попереднього документа (крім першого документа, створеного в межах офлайн сесії, тобто документа «Початок офлайн сесії») (якщо елемент присутній)

Примітка. Для документа «Початок офлайн сесії» геш попереднього документа не використовується в розрахунку тому, що попередній документ відсутній. Для наступного за ним документа геш попереднього документа не використовується в розрахунку тому, що попередній документ («Початок офлайн сесії») може бути змінений (може бути додано елемент «REVOKELASTONLINEDOC»).

Від текстового рядку розраховується геш за алгоритмом CRC32 (див.

https://github.com/damieng/DamienGKit/blob/master/CSharp/DamienG.Library/Security/Cryptography/Crc32.cs⁠

), як десяткове беззнаковое число. Із розрахованого гешу беруться 4 молодші розряди. Ведучі нулі відкидаються (наприклад, "0123" -> "123").

Контрольне число не може дорівнювати 0. Якщо у результаті розрахунку контрольного числа одержано 0, призначається значення 1.

Приклад розрахунку контрольного числа

Документ:

<ORGNM>ТОВ Тестова організація</ORGNM>

<POINTNM>Кафе "Сонечко"</POINTNM>

<POINTADDR>УКРАЇНА, м. Київ, вул. Сонячна, 27</POINTADDR>

<CASHIER>Восьмий Касир Тест</CASHIER>

</CHECKHEAD>

</CHECK>

Текстовий рядок для розрахунку CRC32:

"179625192271939,20082020,142338,10,4000002411,10,cdd68bb111f8993f3603f0179341571b35b73a07d5acee9b28fbfb714698e1b3"

Розраховане значення CRC32:

в шітнадцятковому форматі: 0xbddbbda6

як беззнакове ціле: 3185294758

Контрольне число: 4758

Розрахунок гешу офлайн документа

Геш офлайн документа розраховується за стандартним алгоритмом геш-функції SHA-256 (згідно з FIPS PUB 180-4 "Secure Hash Standard (SHS)",

http://dx.doi.org/10.6028/NIST.FIPS.180-4⁠

), від попереднього документа поточної офлайн сесії, і зберігається в елементі "PREVDOCHASH" як текстовий рядок в шітнадцятковому форматі. Наприклад,

Вихідними даними для розрахунку геша є блок документа, підготовлений для надсилання на Фіскальний Сервер (тобто XML, засвідчений КЕП і, за наявності, позначкою часу).

У разі неможливості здійснення підписання документу, дозволяється використовувати для розрахунку геша безпосередньо блок XML.

Послідовність гешів розраховується, починаючи з першого розрахункового документа (чека на оплату або Z-звіту). Документи типу «Початок офлайн сесії» і «Завершення офлайн сесії» не приймають участь в розрахунку послідовності гешів.

Для першого розрахункового документа офлайн сесії елемент "PREVDOCHASH" не створюється.

Блокування роботи ПРРО

Фіскальний Сервер блокує роботу ПРРО у разі:

Перевищення допустимого терміну роботи в офлайн режимі «36 годин» або «168 годин» протягом календарного місяця та надсилає повідомлення користувачеві. Розблоковує роботу ПРРО після настання нового часового періоду з якого починається відлік дозволеного часу роботи в режимі офлайн.

Наявності повідомлення за формою 2-ПРРО з позначкою «несправність»

Gallery

Want to print your doc?
This is not the way.

Try clicking the ··· in the right corner or using a keyboard shortcut (

CtrlP

) instead.