Інтеграція РРО в Python через загальну бібліотеку для різних РРО

class ArtSoftOleFiscalDriver(FiscalDriver):

pass

27.5.; Зміни та звіти

 self.ensure_connected()

== 2.; Область сфера застосування ==
<pre>
== 3.; Чому застосовується ArtSoft-драйвер ==

8.; | style="background:#f3e5f5;" | Контроль
|-
| Помилки драйвера
| Кількість помилок ArtSoft.; характеристика

{| class="wikitable"
class ArtSoftRROClient:

 def close_shift(self, device_id: str) -> "ZReportResponse":
 pass

7.; ],
 ole_progid: str | None = None
{| class="wikitable"
Як адміністратор, 
POST /api/v1/rro/artsoft/shifts/open
== 22. API Python Agent ==
!; | style="background:#ef9a9a;" | Червоний
|-
| Помилка РРО
| RRO_ERROR
| РРО повернув помилку.; {| class="wikitable"

Перед відправкою на ArtSoft-драйвер платформа повинна перевірити:

{| class="wikitable"
 for item in receipt ["items"]:
 float(item ["quantity"]),
|-
| Перевірка драйвера
| Статус, реліз, помилки, час.; |-
| Різні моделі РРО
| Моделі можуть мати різні обмеження.; |}

8.; Колір
3.; | платформа переводить чек у MANUAL_REVIEW.; |-
| RRO Error
| Помилка пристрою, драйвера або з'єднання.; 1.; |-
| AC-6
| РРО не підключений.; Дія системи
== 9.; Функціональні вимоги ==
 def x_report(self, device_id: str) -> dict:

[[index.php?title=Категорія:ArtSoft]]
рішення для бізнесу повинно забезпечити:
 def close_shift(self, device_id: str) -> dict:

!; |-
| raw_open_response
| jsonb/text
| Відповідь відкриття.; |-
| UnknownResultError
| Невідомо, чи чек було надруковано.; Передати результат у K2 ERP.; |-
| connection_port
| string
| Ні
| COM/USB/мережевий порт, якщо потрібен.; |}

'''істотно:''' значення OLE ProgID, назви DLL, назви функцій і параметри команд потрібно брати з офіційної документації ArtSoft до конкретної версії драйвера.; |-
| quantity
| numeric
| Кількість.; "quantity": 1,
</div>

 "tax_group": "NO_VAT",
6.; характеристика
 pass

 def print_x_report(self, device_id: str) -> "XReportResponse":

<pre>
POST /api/v1/rro/artsoft/reports/z
=== 22.8.; Чек повернення ===
 )
!; характеристика
=== 24.1.; Основні KPI ===
[[index.php?title=Категорія:Інтеграції]]

 service_url: str | None = None

Python-сервіс повинен працювати з драйвером ArtSoft, а не напряму з ДПС.; |-
| FiscalMemoryError
| Помилка фіскальної пам'яті.; |-
| items
| array
| Позиції чека.; |-
| Службова операційна дія
| Тип, сума, касир.; |-
| fiscal_number
| varchar
| Фіскальний номер або номер чека, якщо доступний.; характеристика
!; # Нижче наведено тільки архітектурний приклад.; |}

'''істотно:''' назви методів у прикладі є собою умовними.; |}

!; Замовлення
!; №

</syntaxhighlight>
!; !; * Інструкції до конкретних моделей РРО.; Очікуваний результат

Endpoint: !; Стан

5.; Варіанти інтеграції Python з ArtSoft

Мінімальні інформаційні дані:
'''Критично істотно:''' Z-звіт є собою операцією закриття зміни.; характеристика
=== 13.3.; Методи Python RRO Client ===
'''Критично істотно:''' перед друком фіскального чека агент повинен перевірити готовність РРО.; |-
| current_shift_id
| uuid
| Поточна зміна.; | Dashboard показує помаранчеве попередження.; характеристика

</div>

Central Fiscal API
{| class="wikitable"
 v
|-
| Тип рішення для бізнесу
| Програмне забезпечення для керування фіскальними реєстраторами.; |-
| AC-9
| Немає паперу.; |-
| переважні аспекти
| Менше залежності від прямого COM/DLL-коду в бізнес-сервісі.; def get_status(self, device_id: str) -> "RROStatus":

 "payment_id": "PAY-123456"

 self.connect()

GET /api/v1/rro/artsoft/driver/status Логіка: |- | Підходить для | Windows POS, касових робочих місць.; | style="background:#fff9c4;" | Жовтий |- | Відправляється в драйвер | SENDING_TO_DRIVER | Команда передається в ArtSoft-драйвер.; # Чи потрібно друкувати QR-код у чеку?; | style="background:#eeeeee;" | Сірий |- | Заблоковано | BLOCKED | Робота неможлива.; |- | external_payment_id | varchar | ID оплати.; | style="background:#b71c1c; color:#ffffff;" | Високий ризик |- | Незакриті зміни | Відкриті зміни без Z-звіту.; Критично істотно: DLL-інтеграція без точних сигнатур функцій небезпечна.; | style="background:#c8e6c9;" | Норма |- | Повернення | Кількість чеків повернення.; |- | is_active | boolean | Активність.; Головна ідея: розробити Python-сервіс або Python-адаптер, який надає можливість K2 ERP / POS / CRM / обліковій системі працювати з різними фізичними РРО через ArtSoft Універсальний драйвер реєстраторів, не реалізовуючи окремий низькорівневий протокол для кожної моделі РРО.; |}

K2 ERP / POS / CRM / Website

self.dll = ctypes.WinDLL(self.dll_path)

Рекомендована технічна архітектура: локальний Python RRO Agent встановлюється на касовому ПК або POS-вузлі, функціонує з ArtSoft-драйвером і приймає команди від K2 ERP через HTTP API або локальну чергу.; |- | artsoft_device_id | string | Так | Ідентифікатор або номер пристрою в ArtSoft-драйвері.; характеристика !; if self.driver is None: 5.; |- | AC-13 | Повернення часткове.; |- | device_id | uuid | РРО.; Реальні назви методів, параметри та коди відповідей потрібно взяти з актуальної документації ArtSoft.; Значення index.php?title=Категорія:Python !; | Повернути існуючий результат.; |- | X Report | Проміжний звіт без закриття зміни.; Статус

!; |- | Driver Response | Відповідь драйвера.; * уже фіскалізованого чека;

• повернення понад доступну суму;
• некоректної суми;
• помилки фіскальної пам'яті;
• невідомого стану, коли неможливо визначити, чи чек уже надруковано.; !; |-

| new_status | varchar | Новий статус.; Обов'язковість

!;

POST /api/v1/rro/artsoft/reports/x
Мінімальні інформаційні дані:
from abc import ABC, abstractmethod
Призначення:
ARTSOFT_OLE_PROGID=ArtSoft.Driver.Placeholder
 "device_id": "rro-store-001",
!; | Чек переходить у NEEDS_RETRY або RRO_ERROR.;

!; |- | closed_at | timestamp | Дата закриття.; |- | z_report_number | varchar | Номер Z-звіту.; Код ArtSoft Універсальний драйвер реєстраторів |- | ValidationError | Некоректні інформаційні дані чека.; |- | Перевірка РРО | Статус, помилки, час.; |}

return {"raw": result}

)

!; |- | Драйвер функціонує тільки на Windows | Обмеження для Linux-серверів.; |- | tax_profile_id | string | Ні | Профіль податкових ставок.; |- | created_at | timestamp | Дата події.; | Отримати документацію ArtSoft до початку розробки.; |- | device_serial_number | string | Так | Серійний номер пристрою.; |- | cashier_id | string | Ні | Касир за замовчуванням.; # Назва методу залежить від документації ArtSoft.; Параметр

{

виконати команду відкриття зміни через драйвер виступає ключовою рисою 6.; |- | переважні аспекти | Зручний сценарій для Windows, якщо ArtSoft надає OLE-сервер.; dll_path: str | None = None !; |- | error_message | text | Повідомлення помилки.; Як касир,

def open_shift(self, device_id: str, cashier_id: str) -> dict:

• придбати або отримати демо-версію ArtSoft Універсального драйвера;
• отримати документацію розробника;
• визначити сценарій інтеграції: OLE, DLL, service;
• перевірити підтримувані моделі РРО;
• перевірити версію драйвера;
• перевірити тестовий РРО або емулятор.; |-

| entity_id | uuid | ID сутності.; Черга, журнал, дедублікація

[[index.php?title=Категорія:K2 ERP]]
 |
 | 3.; | платформа повертає READY або конкретну помилку.; }
=== 5.4.; Варіант 4.; Локальний Python RRO Agent + K2 ERP API ===
|-
| integration_name
| string
| Так
| Назва інтеграції.;=== 5.2.; Варіант 2.; Через DLL ===

* створити FastAPI-сервіс;
* реалізувати healthcheck;
* реалізувати локальну БД;
* реалізувати модель драйвера;
* реалізувати модель РРО;
* реалізувати логування.;== 15.; Валідація чека ==

{| class="wikitable"

На касовому ПК запускається Python RRO Agent.; | Refund, manual review, службові операції.; Очікуваний результат
!; |-
| style="background:#bbdefb;" | Блакитний
| #bbdefb
| операційна дія виконується.; |-
| print_qr
| boolean
| Чи друкувати QR-код.; | style="background:#eeeeee;" | Сірий
|-
| Повернення
| REFUNDED
| По чеку створено повне або часткове повернення.; |-
| opened_at
| timestamp
| Дата відкриття.; |-
| супровід моделей
| Залежить від актуального списку підтримуваних моделей ArtSoft.; |-
| Обмеження
| Потрібні точні сигнатури функцій, типи параметрів, коди відповідей і правила 32/64-bit сумісності.; |-
| DeviceConnectionError
| Немає зв'язку з РРО.; |-
| Повторна операційна дія
| Хто запустив, причина, результат.; | style="background:#bbdefb;" | Блакитний
|-
| Фіскалізовано
| FISCALIZED
| Чек успішно надруковано і зареєстровано РРО.; | Черга, друк, передача команди.; |-
| reason
| string
| Причина повернення.; Статус
 v
10.; sha256(external_order_id + total_amount + payment_id + device_serial_number)
POST /api/v1/rro/artsoft/receipts/refund
 v

=== Етап 7.; Production hardening ===
 self.dll.OpenShift.argtypes = [c_char_p, c_char_p]

Кожен фізичний РРО повинен мати окрему картку.; |}

Retry заборонений для:

8.6.; Контроль помилок

"items": [

інтеграційні функціональні можливості призначена для:

"amount": 570.00,

|- | Підходить для | POS-вузлів, де драйвер функціонує як окремий сервіс.; |- | Z-звіт | Критичний | Закриття зміни.; |- | tax_group | varchar | Податкова група.; | Статус оновлюється з коментарем і записом в аудит.; |- | Чек повернення | Високий | Фінансова операційна дія.; |- | актуалізація | Потрібно контролювати версію драйвера та актуалізація підтримки нових РРО і форм чеків.; |- | Fiscal Receipt | Фіскальний чек продажу.; Сума

!; |- | style="background:#ef9a9a;" | Червоний | #ef9a9a | Критична помилка.; |- | Доступ до DLL | ctypes або cffi.; "cashier_id": "cashier-001",

)

|- | AC-11 | Касир створює повернення.; Він функціонує з ArtSoft-драйвером і приймає команди від K2 ERP.; # Чи потрібно відкривати грошову скриньку?; Дія

|
| 2.; | Чернетка, зміна закрита.; self.ensure_connected()

• локальний Python RRO Agent;
• конфігурація ArtSoft-драйвера;
• конфігурація декількох РРО;
• перевірка стану драйвера;
• перевірка стану РРО;
• відкриття зміни;
• друк чека продажу;
• друк чека повернення;
• службове внесення / винесення;
• X-звіт;
• Z-звіт;
• локальна БД чеків;
• дедублікація;
• журнал команд і відповідей;
• базовий dashboard API;
• обробка помилок драйвера, РРО, паперу, зміни;
• retry для безпечних ситуацій;
• MANUAL_REVIEW для невідомого результату.; |-

| Python-бібліотеки | pywin32 або comtypes.; |- | receipt_type | varchar | sale, refund, service.; Зберегти локальний статус.; |- | Service Operation | Службове внесення або винесення.; * приймати HTTP-запити від K2 ERP / POS;

• керувати ArtSoft-драйвером;
• виконувати друк чеків;
• повертати статуси;
• зберігати локальний журнал;
• працювати навіть при тимчасовій недоступності центральної системи, якщо це дозволено сценарієм;
• синхронізувати результати з центральною БД.; * Тестовий емулятор фіскального реєстратора, якщо доступний.;=== 8.1.; Продаж ===

Як POS або K2 ERP,

# Сигнатури функцій потрібно задати згідно з документацією ArtSoft.; |-

| Інтеграційний шар | DLL / OLE / інший програмний інтерфейс згідно з документацією ArtSoft.; | style="background:#ffcc80;" | Потрібна дія |- | РРО не підключені | Пристрої без зв'язку.; Виконати команду формування Z-звіту через ArtSoft.; |}

!; COM/OLE/DLL або інший API ArtSoft

def print_sale_receipt(self, device_id: str, payload: "SaleReceiptPayload") -> "ReceiptResponse":

щоб оперативно реагувати на проблеми з папером, зв'язком, портом, драйвером або фіскалізацією.; Компонент

self.driver = win32com.client.Dispatch(self.ole_progid)

17.1.; Логіка черги

Логіка:

POST /api/v1/rro/artsoft/reports/x
!; |-
| style="background:#ffcc80;" | Помаранчевий
| #ffcc80
| Потрібна дія користувача.;== 1.; Мета ==

* https://artsoft.ua/ua/programne-zabezpechennja/artsoft-universalnij-drajver-restratoriv-pz/
* https://artsoft.ua/ua/programne-zabezpechennja/onovlennja-artsoft-universalnij-drajver-restratoriv-pz5/
* Документація ArtSoft Універсальний драйвер реєстраторів.; | Idempotency key, локальна БД, журнал статусів.; Для часткових повернень платформа повинна вести залишок доступної до повернення суми та кількості.; Критерій

!; Пріоритет
</div>
 item.get("department", 1),
|-
| Чернетка
| DRAFT
| Чек створено в Python-сервісі, але не відправлено на драйвер.; |-
| idempotency_key
| ключовий ключ повторного запиту.; |-
| printed_at
| timestamp
| Дата друку.; | style="background:#e3f2fd;" | відомості
|-
| Фіскалізовано
| Кількість успішних чеків.; pass

== 24.; Dashboard керівника ==
{{SEO
|title=Технічне завдання: Інтеграція РРО в Python через ArtSoft Універсальний драйвер реєстраторів
|description=Технічне завдання на реалізацію Python-сервісу для інтеграції з різними фізичними РРО через ArtSoft Універсальний драйвер реєстраторів: чеки продажу, повернення, службові операції, X/Z-звіти, зміни, статуси, помилки, драйверний адаптер, черги та журналювання.
|keywords=Python, РРО, ArtSoft, універсальний драйвер реєстраторів, фіскальний реєстратор, каса, POS, FastAPI, K2 ERP, фіскальний чек, Z-звіт, X-звіт, OLE, DLL, Linux, Windows
}}
!;<pre>
<pre>

{| class="wikitable"

=== 9.4.; Відкриття зміни ===
 pass
!; !; Коментар

=== 22.4.; Відкриття зміни ===
щоб мати можливість друкувати фіскальні чеки.; | Чек друкується і переходить у FISCALIZED.; |-
| Ризик помилок у фіскальному протоколі.; Це потрібно врахувати в експлуатації та оновленнях production-середовища.; |-
| style="background:#eeeeee;" | Сірий
| #eeeeee
| Неактивно або скасовано.; Час

{

{

Python викликає функції DLL через `ctypes` або `cffi`.; Тип !; | style="background:#c8e6c9;" | Зелений |- | Драйвер недоступний | DRIVER_UNAVAILABLE | Python не має змогу підключитися до ArtSoft-драйвера.; Якщо РРО або ArtSoft-драйвер має критичну помилку, чек не повинен переходити в статус «Фіскалізовано».; |}

self.ensure_connected()

1. Який саме API надає ArtSoft у вашій ліцензії: OLE, DLL, локальний сервіс чи інший механізм?; Показник

MVP: реалізувати інтеграцію Python не з конкретним РРО забезпечується через Рекомендовано; додатково реалізовано а з ArtSoft-драйвером як із єдиним абстрактним шаром для всіх підтримуваних реєстраторів.; !; |- | Driver Command | Команда, що відправляється в ArtSoft-драйвер.; | Не відправляти в драйвер.; характеристика

22.7.; Чек продажу

def service_cash_out(self, device_id: str, amount: float, comment: str | None = None) -> "ServiceOperationResponse":

"sku": "DELIVERY",

AC-1	} платформа повинна не допускати дублювання чеків.; |-	device_id	string	ID РРО.;=== 22.3.; Перевірка стану РРО === 22.10.; Повторити чек
external_order_id	-	AC-5	Другий чек не друкується.; |-	error_message	text	Помилка.; self.ensure_connected()
10:42	РРО #001	ORDER-123	570.00	Помилка драйвера	ArtSoft недоступний	Перевірити драйвер
11:05	РРО #001	ORDER-124	1200.00	Потребує повтору	Немає паперу	Замінити папір і повторити
12:10	РРО #002	SHIFT-55	-	Зміна відкрита	Не закрито Z-звіт	Закрити зміну
12:30	РРО #003	ORDER-125	700.00	Ручна перевірка	Невідомо, чи чек надруковано	Перевірити на РРО

device_id.encode("utf-8"),

• доступ до локального агента тільки з дозволених IP або через токен;
• HTTPS або локальну захищену мережу;
• авторизацію запитів від K2 ERP / POS;
• розмежування прав: продаж, повернення, X-звіт, Z-звіт, службові операції;
• журнал дій користувачів;
• захист від дублювання чеків;
• заборону прямого доступу до драйвера з кількох процесів;
• шифрування конфігурацій, якщо містять чутливі інформаційні дані;
• маскування персональних даних покупців у логах;
• блокування небезпечних повторів для статусу UNKNOWN_RESULT.; |-

| unit | varchar | Одиниця.; pass

8.; |-

Фізичний РРО	style="background:#bbdefb;" | Блакитний
Друкується	PRINTING	}	; Високорівневі команди до РРО } платформа показує DEVICE_DISCONNECTED червоним кольором.; |- is_active boolean - Dashboard Центральний контроль чеків, змін і помилок.; :contentReference [oaicite:1]{index=1} POST /api/v1/rro/artsoft/receipts/refund - log_raw_commands boolean Так Критична помилка, заборонити друк.; ; характеристика підключення Python-сервісу до ArtSoft-драйвера; роботу з різними моделями РРО через єдиний програмний інтерфейс; перевірку стану РРО; відкриття касової зміни; друк і фіскалізацію чека продажу; друк і фіскалізацію чека повернення; службове внесення готівки; службове винесення готівки; формування X-звіту; формування Z-звіту; друк нефіскального тексту, якщо підтримується; контроль помилок РРО; журналювання команд і відповідей; захист від дублювання чеків; повторну обробку технічних помилок; інтеграцію з K2 ERP / POS / CRM / сайтом.; 5.; Перевірити підключення до РРО.; Очікуваний результат - AC-17 Зміна не закрита наприкінці дня.;=== 18.1.; Навіщо потрібна абстракція === реалізувати cash_in; реалізувати cash_out; реалізувати права доступу; реалізувати аудит.; |- Мова Python 3.11+ API FastAPI Доступ до COM/OLE - idempotency_key varchar - Python-бібліотеки ctypes або cffi.; # Чи є собою доступ до емулятора фіскального реєстратора?;=== 27.3.; Продаж === "unit": "шт" return {"raw": result} } Метою задачі є собою створення універсального Python-рішення для роботи з різними фізичними РРО через ArtSoft Універсальний драйвер реєстраторів.; | Виносити інтеграцію в локальний Windows Agent.; } Python функціонує з єдиним високорівневим драйвером.; | Помилка РРО, драйвер недоступний, фіскальна помилка.; |- cashier_id varchar - - ole_progid string Ні style="background:#ef9a9a;" | Критично Потребують повтору - Дублювання чеків - AC-20 - AC-12 - raw_command text/jsonb Немає паперу, кришка, повтор.; Чек потрапляє в чергу друку.; | 4.; Характеристика @abstractmethod Endpoint: - Refund Receipt Python Agent створює чек у статусі PENDING.; |- external_order_id varchar ID замовлення.; Як зменшити Він повинен: 9.2.; конфігурація РРО "department": 2, result = self.driver.OpenShift(device_id, cashier_id) - Помилка драйвера Код, текст, raw-відповідь.; Поле ARTSOFT_TIMEOUT_SECONDS=30 return {"raw": result} driver_connection_type: str = "OLE_COM" result = self.driver.CloseReceipt(device_id) CASH_IN Службове внесення готівки.; v auto_open_shift: bool = True 27.6.; Ручна перевірка self.ole_progid = ole_progid "cashier_id": "cashier-001", result = self.driver.ZReport(device_id) 19.; Приклад ArtSoft OLE Adapter style="background:#ef9a9a;" | Червоний Немає паперу PAPER_OUT - model varchar - Черга - - Обмеження style="background:#eeeeee;" | Сірий Очікує друку PENDING Чек у черзі на друк.; self.dll.OpenShift.restype = c_char_p ;== 12.; Єдина логіка кольорів == "device_id": "rro-store-001", ; Статус self.ensure_connected() return {"raw": result} POST /api/v1/rro/artsoft/shifts/open ArtSoft Універсальний драйвер реєстраторів потрібен для того, щоб не писати окрему інтеграцію під кожну модель РРО.; |- Основне призначення Надати високорівневі команди для роботи з РРО без реалізації протоколу кожної моделі.; Сутність ; Де застосовується 21.5. rro_receipt_items pass device_id, Етап 3.; Драйверний шар ; Тип </syntaxhighlight> я хочу сформувати Z-звіт, "tax_group": "VAT_20", "amount": 70.00, - external_refund_id string - error_code varchar style="background:#ffcc80;" | Помаранчевий Помилка фіскальної пам'яті FISCAL_MEMORY_ERROR - sku varchar - device_model string Так - AC-18 - receipt_hash - status varchar - idempotency_key string - artsoft_device_id varchar - Нефіскальний друк Низький Не блокує продажі та реалізація.; Очікуваний результат GET /api/v1/rro/artsoft/events?date_from=2026-05-01&date_to=2026-05-07 ДПС 14.; Приклад конфігурації external_order_id string ID замовлення у K2 ERP / POS.; Очікуваний результат float(item ["price"]), 9.7.; Чек повернення ; Endpoint: === 9.6.; Приклад запиту на чек продажу === <div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;"> !; | style="background:#ffcc80;" | Потрібна дія |- | Ручна перевірка | Операції MANUAL_REVIEW.; 7.; |- | Упаковка | Windows Service; Linux-сценарій — тільки якщо підтримується драйвером і конкретним способом інтеграції.; | РРО доступний у списку пристроїв.; Тип |- | id | uuid | ID пристрою.; Тип Приклад: На сторінці ArtSoft окремо вказано, що організація випускає актуалізація універсального драйвера для підтримки нових версій реєстраторів і нової друкованої форми чека.; | style="background:#ef9a9a;" | Критично |- | Помилки РРО | Кількість помилкових операцій РРО.; | Тестове середовище і regression-тести.; |} {| class="wikitable" return {"raw": result} === 22.9.; Службова операційна дія === "idempotency_key": "CASH-IN-2026-05-07-001" <pre> |- | AC-7 | POS передає продаж.; Зберегти номер і результат Z-звіту.; | Healthcheck, monitoring, auto-restart.; характеристика Якщо ArtSoft надає сервісний режим або локальний серверний компонент, Python має змогу працювати з ним через локальний API або файловий/черговий обмін.; |} def ensure_connected(self) -> None: !; |- | serial_number | varchar | Серійний номер.; РРО !; |- | original_fiscal_number | string | Фіскальний номер первинного чека, якщо доступний.; |} == 7.; Основні сутності == def open_shift(self, device_id: str, cashier_id: str) -> "ShiftResponse": * тимчасової втрати зв'язку; * тимчасової недоступності драйвера; * timeout; * очікування готовності РРО; * відновлення після відсутності паперу, якщо чек не був завершений.; __TOC__ щоб не розробляти окрему Python-інтеграцію для кожної моделі.;<syntaxhighlight lang="python"> * реалізувати sale receipt; * реалізувати refund receipt; * реалізувати валідацію; * реалізувати дедублікацію; * реалізувати чергу друку.;</pre> Python RRO Agent — це локальний сервіс, який встановлюється на касовий ПК і має доступ до ArtSoft-драйвера та фізичного РРО.; характеристика pass === 18.2.; Інтерфейс FiscalDriver === def service_cash_out(self, device_id: str, amount: float, comment: str | None = None) -> dict: == 26.; Логування та аудит == !; | платформа зменшує доступний залишок до повернення.; |- | X-звіт | Час, РРО, відповідь.; |- | raw_close_response | jsonb/text | Відповідь закриття.; | style="background:#ef9a9a;" | Червоний |- | РРО не підключений | DEVICE_DISCONNECTED | Немає зв'язку з пристроєм.; v result = self.driver.XReport(device_id) === 24.2.; Приклад dashboard === 4.; |- | is_active | boolean | Так | Чи активний пристрій.; |- | device_id | uuid | ID РРО.; |- | price | numeric | Ціна.; Код !; | Друкується чек повернення.; |- | ShiftClosedError | Зміна закрита.; |} cashier_id.encode("utf-8"), <syntaxhighlight lang="python"> def check_connection(self, device_id: str) -> "RROStatus": </div> </pre> |- | AC-14 | Касир відкриває зміну.; {| class="wikitable" def __init__(self, ole_progid: str): !; Поле ARTSOFT_DRIVER_CONNECTION_TYPE=OLE_COM import win32com.client !; |} !; характеристика === Варіант 3.; 5.3.; Через локальний ArtSoft-сервіс / агент === !; |- | Відкриття зміни | Касир, час, відповідь драйвера.; |} {| class="wikitable" def connect(self) -> None: Як керівник або адміністратор, "operation_type": "CASH_IN", === 17.2.; Пріоритети === |- | id | uuid | ID позиції.; | UNKNOWN_RESULT.; '''Критично істотно:''' якщо після збою неможливо визначити, чи чек був надрукований, платформа повинна перевести операцію в статус MANUAL_REVIEW, а не автономно друкувати повторно.; № === 22.1.; Перевірка стану агента === </div> !; характеристика <pre> === 8.2.; Повернення === |- | Чек продажу | Високий | Основна операційна дія.; Результат синхронізується з центральною системою.; Обов'язковість "comment": "Службове внесення на початок зміни", "total_amount": 570.00, @abstractmethod === 21.1. fiscal_driver_integrations === "amount": 500.00, === 13.1.; Призначення === pass pass я хочу створити чек повернення, POST /api/v1/rro/artsoft/service-operation return {"raw": result} я хочу відкрити зміну на РРО, @abstractmethod def service_cash_in(self, device_id: str, amount: float, comment: str | None = None) -> "ServiceOperationResponse": "quantity": 2, "department": 1, from ctypes import c_char_p, c_double payment ["type"], платформа повинна логувати: </syntaxhighlight> 22.5.; Закриття зміни / Z-звіт ; def refund_receipt(self, device_id: str, receipt: dict) -> dict: "sku": "SKU-001", from pydantic_settings import BaseSettings def check_driver(self) -> dict: self.driver.OpenReceipt(device_id, "SALE") Етап 1.; Аналіз ArtSoft-драйвера POST /api/v1/rro/artsoft/service-operation self.ensure_connected() - переважні аспекти - driver_version varchar реліз драйвера.; import ctypes 6.; Критерій if self.dll is None: !; "type": "CARD", * повна супровід всіх моделей РРО без тестування; * автоматичне програмування усієї номенклатури; * повний POS UI; * власна фіскальна логіка замість РРО; * складна офлайн-синхронізація; * заміна ArtSoft-драйвера власним протоколом; * супровід Linux, якщо фактичний сценарій інтеграції використовує Windows-only OLE/DLL.; характеристика 18.; Абстрактна модель драйвера id uuid - актуалізація драйвера - Чек продажу class="wikitable" log_raw_commands: bool = True pass result = self.driver.GetDriverStatus() - event_type varchar Перевести чек у DRIVER_ERROR або NEEDS_RETRY.; |- driver_version string Так } 21.; Модель даних pass Перевести в MANUAL_REVIEW.; |- Чеків за день 384 відомості Фіскалізовано 378 Норма Повернення 9 Контроль Помилки драйвера 2 Критично Помилки РРО 4 Критично Потребують повтору 3 Потрібна дія Ручна перевірка 1 Високий ризик Незакриті зміни 1 Потрібна дія Python Agent повинен уміти перевіряти: for payment in receipt ["payments"]: pass return {"raw": result} return {"raw": result} 9.; | РРО закриває зміну.; | style="background:#ef9a9a;" | Червоний |- | Зміна відкрита | SHIFT_OPEN | Можна друкувати фіскальні чеки.; Перевірити підключення до РРО.; :contentReference [oaicite:2]{index=2} платформа повинна забезпечити: |- | device_name | string | Так | Назва РРО.; |- | connection_type | varchar | OLE_COM, DLL, SERVICE.; |- | driver_provider | string | Так | artsoft.; | style="background:#c8e6c9;" | Зелений |- | Зміна закрита | SHIFT_CLOSED | Перед продажем потрібно відкрити зміну.; | style="background:#ffcc80;" | Помаранчевий |- | Відкрита кришка | COVER_OPEN | Кришка принтера відкрита.; Повернути результат у K2 ERP / POS.; Тип "external_order_id": "ORDER-2026-000123", === 21.4. rro_receipts === !; |- | Shift | Касова зміна.; |} def print_refund_receipt(self, device_id: str, payload: "RefundReceiptPayload") -> "ReceiptResponse": def sale_receipt(self, device_id: str, receipt: dict) -> dict: </syntaxhighlight> замінити ArtSoft на інший драйвер у майбутньому; тестувати бізнес-логіку без фізичного РРО; використовувати mock-драйвер; підтримувати декілька реалізацій: ArtSoft OLE, ArtSoft DLL, ArtSoft Service; не прив'язувати K2 ERP до конкретного драйвера.; характеристика - Обмеження Потребує Windows, встановленого драйвера та коректної COM-реєстрації.; Друк і фіскалізація чека @abstractmethod Таблиця можливостей device_capabilities.; |- DriverCallError Зупинити друк, чек лишити в NEEDS_RETRY.; | style="background:#f3e5f5;" | Фіолетовий Скасовано CANCELLED style="background:#f3e5f5;" | Фіолетовий "price": 70.00, Варіант 1.; 5.1.; Через OLE / COM-інтерфейс self.driver = None Це дозволить: Endpoint: Як касир, Готовий READY - Логи - status varchar - ArtSoft Driver Універсальний драйвер для керування РРО.; * Документація OLE/DLL API ArtSoft.; Результат зберігається локально.; self.driver.Sale( self.ensure_connected() щоб коректно повернути кошти покупцю та відобразити операцію в РРО.; |- status varchar OPEN, CLOSED, ERROR.; Якщо зміна не відкрита.; result = self.dll.GetDriverStatus() 7.; |- Заборонити операцію.; рішення для бізнесу через ArtSoft - Невідомий стан після збою - items array - idempotency_key string платформа показує DRIVER_UNAVAILABLE червоним кольором.; Тип def get_device_status(self, device_id: str) -> dict: </syntaxhighlight> def ensure_connected(self) -> None: Рекомендована схема для K2 ERP: K2 ERP не повинна напряму керувати драйвером на касовому ПК.; |- provider varchar artsoft.; # Які моделі РРО потрібно підтримати в MVP?; Подія 27.1.; Підключення драйвера 20.; Приклад ArtSoft DLL Adapter Узгодити bitness Python і драйвера.; Тип задачі } def close_shift(self, device_id: str) -> dict: return {"raw": result} 8. User Story } 2.; Компонент 4.; Технічні особливості ArtSoft-драйвера чи встановлено ArtSoft-драйвер; чи доступний драйверний інтерфейс; чи підключений РРО; чи доступний порт; чи є собою папір; чи відкрита кришка; чи є собою помилки живлення; чи є собою зв'язок із фіскальним модулем; чи відкрита зміна; чи не заблокований РРО; чи не переповнена пам'ять; чи коректно встановлена дата і час; чи готовий РРО до друку чека.; характеристика 27. Acceptance Criteria Python викликає об'єкти драйвера через COM/OLE.; Потрібно мати офіційну документацію ArtSoft щодо DLL API, типів параметрів, кодування рядків, кодів помилок і 32/64-bit сумісності.; KPI pass - Чек повернення Первинний чек, сума, причина.; Колір style="background:#ef9a9a;" | Червоний Помилка з'єднання CONNECTION_ERROR - AC-15 Касир формує X-звіт.; Поле я хочу бачити помилки РРО та драйвера, ; Параметр Етап 2.; Локальний Python Agent def print_non_fiscal_text(self, device_id: str, lines: list [str]) -> "PrintResponse": def check_driver(self) -> dict: Зелений #c8e6c9 Успішна операційна дія або нормальний стан.; == 31.; Відкриті питання == class FiscalDriver(ABC): === Етап 6.; Dashboard і синхронізація === == 30.; Ризики == !; '''Ознайомтесь з документацією від розробника універсального драйвера РРО:''' [[Керівництво програміста "АртСофт - Універсальний драйвер фіскальних реєстраторів для України"]] * [[Python]] * [[FastAPI]] * [[K2 ERP]] * [[РРО]] * [[Фіскальний реєстратор]] * [[ArtSoft]] * [[ArtSoft Універсальний драйвер реєстраторів]] * [[Фіскальний чек]] * [[Касова зміна]] * [[Z-звіт]] * [[X-звіт]] * [[POS]] * [[OLE]] * [[DLL]] * [[COM]] * [[Windows Service]] Local Python RRO Agent === 13.2.; Рекомендований стек агента === !; Колір def check_driver(self) -> "DriverStatus": !; |- | receipt_id | uuid | ID чека.; !; |- | dll_path | string | Ні | Шлях до DLL, якщо застосовується DLL.; |- | Сценарій використання | Підключення облікових програм, POS-систем, касових місць до фізичних РРО.; Критерій pass |- | K2 ERP / POS | Створює продаж або повернення.; Очікуваний результат item ["tax_group"], "provider": "terminal", {{DISPLAYTITLE:Технічне завдання: Інтеграція РРО в Python через ArtSoft Універсальний драйвер реєстраторів}} {| class="wikitable" result = self.dll.GetDeviceStatus(device_id.encode("utf-8")) }, === 23.1.; Типи помилок === Приклад `.env`: До MVP не входить: 1.; | Записати raw-помилку, повідомити адміністратора.; |- | external_payment_id | ID оплати.; |- | Драйвер недоступний | ArtSoft не запущений або неправильно встановлений.; | MANUAL_REVIEW замість автоматичного повтору.; allow_service_operations: bool = True POST /api/v1/rro/artsoft/receipts/{receipt_id}/retry @abstractmethod <syntaxhighlight lang="python"> [[index.php?title=Категорія:Фіскальні реєстратори]] !; Проблема без універсального драйвера !; |- | auto_open_shift | boolean | Так | автономно відкривати зміну перед першим чеком.; |- | shift_id | uuid | Зміна.;== 6.; Загальна технічна архітектура == '''Критично істотно:''' повторний запит із тим самим idempotency_key не повинен друкувати другий фіскальний чек.; | style="background:#ef9a9a;" | Червоний |- | Невідомий результат | UNKNOWN_RESULT | Не вдалося визначити, чи чек надруковано.; Тип </div> !; | ArtSoft випускає актуалізація драйвера.; |} <pre> === 9.3.; Перевірка стану РРО === { === 8.5.; Закриття зміни === <pre> item ["name"], | | 1.; |- | AC-8 | Драйвер і РРО готові.; Передача фіскальних даних каналами РРО щоб закрити касову зміну.; |- | Z-звіт | Час, номер звіту, результат.;<div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;"> === 27.2.; Підключення РРО === |- | AC-4 | Адміністратор додає РРО.; |- | service_url | string | Ні | URL локального сервісу, якщо застосовують, коли потрібно сервісний режим.; Тип <syntaxhighlight lang="json"> def service_cash_in(self, device_id: str, amount: float, comment: str | None = None) -> dict: </div> {| class="wikitable" !; Worker перевіряє стан РРО.; Критерій === 27.4.; Повернення === ARTSOFT_LOG_RAW_COMMANDS=true == 23.; Обробка помилок == !; |- | Несумісність 32/64-bit | Python, DLL і драйвер можуть мати різну архітектуру.; 11.; Статуси РРО та драйвера 9.10.; Z-звіт Покупець / чекова стрічка ; Критерій Як касир або адміністратор, "payments": [ !; Поле POST /api/v1/rro/artsoft/receipts/sale === 9.8.; Службове внесення / винесення === === 9.9.; X-звіт === 3.; | style="background:#ef9a9a;" | Червоний |} Retry дозволений для: !; Перевірити, чи зміна вже відкрита.; |- | status | varchar | Поточний стан.; |- | Службове внесення / винесення | Середній | Касова операційна дія.; * Список підтримуваних моделей ArtSoft.; |- | DriverUnavailableError | ArtSoft-драйвер недоступний.; № [[index.php?title=Категорія:POS]] self.dll_path = dll_path <div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;"> |- | id | uuid | ID події.; Перевірити доступність ArtSoft-драйвера.; !; |- | old_status | varchar | Старий статус.; Технологія === 21.3. rro_shifts === !; |} === 22.2.; Перевірка стану драйвера === self.ensure_connected() @abstractmethod Навіть якщо застосовується ArtSoft як єдина бібліотека, в Python-коді потрібно зробити власний інтерфейс `FiscalDriver`.; | Черга чеків, очікування друку.;== 32.; Джерела == 9.5.; Чек продажу pass 22.11.; Отримати журнал подій "name": "Доставка", '''Критично істотно:''' чек повернення не повинен перевищувати залишок по первинному чеку.; Worker друкує чек через ArtSoft.; |- | Ручна перевірка | Хто перевірив, що встановив, коментар.; | Перевести чек у CONNECTION_ERROR.; | Відкрити зміну, якщо дозволено.; |- | AC-2 | Python Agent перевіряє статус драйвера.; self.connect() * реалізувати FiscalDriver interface; * реалізувати ArtSoftOleFiscalDriver або ArtSoftDllFiscalDriver; * реалізувати check_driver; * реалізувати check_device; * реалізувати open_shift; * реалізувати X/Z-звіти.; |- | integration_id | uuid | ID інтеграції ArtSoft.; Продаж / повернення / службова операційна дія timeout_seconds: int = 30 !; |- | Z Report | Звіт із закриттям зміни.; |- | payments | array | Сума повернення.; { {| class="wikitable" def open_shift(self, device_id: str, cashier_id: str) -> dict: !; Колір |- | RRO Device | Фізичний фіскальний реєстратор.; |- | Немає паперу | Чек не має змогу бути надрукований.; |} GET /api/v1/rro/artsoft/devices/{device_id}/status pass '''істотно:''' ArtSoft-драйвер призначений для спрощення роботи з фіскальними реєстраторами: замість реалізації протоколу кожного РРО Python-інтеграція повинна викликати високорівневі команди драйвера.; Поле == Див.; 33.; додатково == ], |- | id | uuid | ID інтеграції.; |- | total_amount | numeric | Загальна сума.; |- | payload | jsonb/text | інформаційні дані події.; Поле self.driver.Payment( !; |} Локальний endpoint: {| class="wikitable" !; |- | Локальна БД | SQLite або PostgreSQL.; |} === 22.6.; X-звіт === retry_count: int = 2 class ArtSoftDllFiscalDriver(FiscalDriver): ARTSOFT_DLL_PATH=C:\ArtSoft\Driver\driver.dll @abstractmethod def open_shift(self, device_id: str, cashier_id: str) -> dict: - is_active boolean Так - Бордовий #b71c1c style="background:#ef9a9a;" | Критично pass } - total_amount decimal - default_timeout_seconds integer Так Таймаут команди до драйвера.; Ризик - cashier_id string Касир.; № def sale_receipt(self, device_id: str, receipt: dict) -> dict: allow_refunds: bool = True def connect(self) -> None: я хочу передати продаж у Python RRO Agent, ; характеристика @abstractmethod def check_driver(self) -> dict: 8.3.; Робота з різними моделями РРО У K2 ERP або локальному агенті повинна бути картка інтеграції ArtSoft.; | платформа блокує операцію.; | Цю низькорівневу логіку бере на себе драйвер.; |- ArtSoft Driver Зупинити друк, показати помаранчевий статус.; |- ole_progid varchar - name varchar - Фіолетовий #f3e5f5 - allow_service_operations boolean Так - DuplicateReceiptError Статус PAPER_OUT, повтор після заміни паперу.; |- dll_path varchar Шлях до DLL.; № - Cashier - AC-19 - PaperOutError Немає паперу.; # Чи потрібно програмувати податкові ставки з Python?; Тип 10.; Статуси чеків До MVP входить: Ключі дедублікації: Етап 5.; Службові операції 3.; |- Python-підхід HTTP, TCP, файли обміну або інший механізм згідно з документацією.; Критерій float(payment ["amount"]), 5.; | РРО переходить у стан SHIFT_OPEN.; |} Приклад: ; Тип 21.6. rro_events id uuid ID зміни.; pass 9.1.; конфігурація драйвера 2.; Параметр "amount": 1000.00, 2.; Поле self.dll = None 13. Python RRO Agent "unit": "послуга" == 29.; Етапи реалізації == !; | style="background:#c8e6c9;" | Зелений |- | Помилка драйвера | DRIVER_ERROR | ArtSoft-драйвер повернув помилку.; Тип "idempotency_key": "ORDER-2026-000123-PAY-123456", === 23.2.; Retry-логіка === </syntaxhighlight> |- | original_receipt_id | uuid | Внутрішній ID первинного чека.; | Python функціонує через перевірені команди драйвера.; |- | AC-16 | Касир формує Z-звіт.; | РРО друкує X-звіт без закриття зміни.; POST /api/v1/rro/artsoft/receipts/sale * реалізувати Windows Service; * додати моніторинг агента; * додати auto-restart; * додати резервне копіювання локальної БД; * додати alerting; * протестувати типові помилки РРО; * протестувати актуалізація ArtSoft-драйвера.; |- | entity_type | varchar | driver, device, shift, receipt.; |} POST /api/v1/rro/artsoft/reports/z !; характеристика {| class="wikitable" pass |- | Чеків за день | Кількість чеків продажу.; | інтеграційні функціональні можливості зберігається в системі.;=== 8.4.; Відкриття зміни === Деякі сторонні описи ArtSoft-драйвера вказують підтримку Windows 7+ і Linux, а додатково наявність вбудованого емулятора фіскального реєстратора; ці функціональні можливості потрібно підтвердити на конкретній ліцензії та версії драйвера перед проєктуванням production-схеми.; # Скільки РРО буде на одному касовому ПК?; |- | discount_amount | numeric | Знижка.; |- | CoverOpenError | Кришка відкрита.; Що зберігати <syntaxhighlight lang="python"> Типи: <pre> class ArtSoftRROSettings(BaseSettings): !; Тип @abstractmethod "price": 250.00, !; |- | fiscal_number | string | Так | Фіскальний номер РРО.; # Чи потрібно програмувати товари в РРО?; |- | driver_connection_type | enum | Так | OLE_COM, DLL, SERVICE, OTHER.; |- | raw_response | text/jsonb | Відповідь драйвера.; | Dashboard, список чеків, статус РРО.;<pre> |- | Кожен РРО має власний протокол обміну.; |- | X-звіт | Середній | Контрольний звіт.; # Як обробляти ситуацію, коли результат друку невідомий?; |- | AC-10 | Повторний запит має той самий idempotency_key.; |- | service_url | varchar | URL сервісу, якщо застосовується.; |- | style="background:#fff9c4;" | Жовтий | #fff9c4 | Очікування або попередження.; |- | department | integer | Відділ.; характеристика !; Перевірити відкриту зміну.; характеристика !; Перевірити незавершені чеки.; |- | RefundLimitError | Повернення перевищує доступну суму.; |- | AC-3 | Драйвер недоступний.; | Автоматичний retry заблокований.; |- | customer | object | інформаційні дані покупця, якщо потрібні.; Він повинен повернути результат уже виконаної операції.; Значення == 28. MVP == 4.; # Чи буде один РРО на декілька касирів?; |- | payments | array | Оплати.; Worker перевіряє стан ArtSoft-драйвера.;<pre> === 21.2. rro_devices === !; Перевірити доступність драйвера.; |} !; характеристика def x_report(self, device_id: str) -> dict: == 17.; Черга друку == * наявність external_order_id; * наявність idempotency_key; * відсутність уже фіскалізованого чека з таким ключем; * активний РРО; * доступність драйвера; * доступність конкретного пристрою; * наявність відкритої зміни або можливість її відкрити; * готовність РРО; * наявність паперу; * відсутність критичних помилок; * наявність хоча б однієї позиції; * коректність кількості; * коректність ціни; * коректність суми рядка; * відповідність total_amount сумі товарів і оплат; * коректність типу оплати; * коректність податкових груп; * довжину назви товару; * наявність відділу, якщо він обов'язковий; * коректність QR-коду, якщо він друкується.; Ключ !; я хочу підключати різні моделі РРО через один драйвер, v Локальний endpoint: !; Поле отримати проміжний звіт без закриття зміни; перевірити обороти; перевірити стан каси; показати керівнику поточні підсумки.; | style="background:#ffcc80;" | Помаранчевий Ручна перевірка MANUAL_REVIEW Потрібна перевірка касиром або адміністратором.; Поле device_id, - fiscal_number varchar платформа повертає READY або помилку пристрою.; Призначення 4.; |- Python RRO Agent Локальний сервіс на касовому ПК.; № "name": "Товар 1", self.ensure_connected() Немає документації до API драйвера Без документації неможливо коректно викликати OLE/DLL.; Поле 16.; Дедублікація "print_qr": true ARTSOFT_RETRY_COUNT=2 ARTSOFT_AUTO_OPEN_SHIFT=true GET /api/v1/health ;== 25.; Безпека == щоб агент через ArtSoft-драйвер надрукував і фіскалізував чек на підключеному РРО.;=== Етап 4.; Чеки === реалізувати dashboard API; реалізувати список помилок; реалізувати синхронізацію з K2 ERP; реалізувати експорт журналу, якщо потрібно.; характеристика Фізичний РРО def get_device_status(self, device_id: str) -> dict: 24.3.; Проблемні операції 1.; def get_device_status(self, device_id: str) -> dict: result = self.dll.OpenShift( <syntaxhighlight lang="json"> - CASH_OUT } def __init__(self, dll_path: str): ; HTML Підходить для - RRO Agent style="background:#b71c1c; color:#ffffff;" | Бордовий Потребує повтору NEEDS_RETRY супровід моделей централізується на стороні драйвера.; result = self.driver.GetDeviceStatus(device_id) retry_backoff_seconds: int = 3 фізичних магазинів; аптек; кафе, барів, ресторанів; кіосків; торгових точок із декількома РРО; торговельних мереж; POS-вузлів; підприємств, які використовують різні моделі фіскальних реєстраторів; компаній, які хочуть мати один Python-інтерфейс для різних РРО.; |- amount numeric Сума.; Помилка