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

Довідник конфігурації Abhard

Налаштування зберігаються у файлі abhard.yaml. Створена самою службою конфігурація не містить жодного пристрою, а whitelist у ній розширено на підмережу /24 тієї мережевої карти, яку вдалося визначити.

Приклад із усіма підтримуваними пристроями встановлюється разом із програмою — /usr/share/doc/abhard/examples/abhard.yaml.example у Linux, C:\Program Files\Abacus\Tools\examples\abhard.yaml.example у Windows.

Блок main

Ключ Типово Опис
port 4601 Порт, на якому служба приймає запити
whitelist 127.0.0.1 Дозволені адреси через крапку з комою. Приймає одиночні адреси (127.0.0.1), діапазони (172.27.0.2-10) і підмережі (192.168.50.0/24)
event_socket true Увімкнути канал подій
event_socket_host визначається автоматично Адреса, яку служба повідомляє касам як точку підключення до каналу подій
event_socket_port 4651 Порт каналу подій
event_socket_ping_idle 4 Через скільки секунд тиші надіслати касі перевірочний пакет
language uk Мова станів і помилок обладнання, які бачать користувачі. Переклад береться з файлу lang/abhard.<мова>.po поруч із програмою; порожнє значення - англійська

Налаштування журналу лежать в окремому блоці log - див. Журнали.

Канал подій

Канал подій — постійне TCP-з'єднання, яким служба сама передає касі сканування штрихкодів та іншу службову інформацію. Програма, що підключилася останньою, отримує інформацію про відскановані коди. Підключення відбувається в момент запуску та в момент активації кожної програми з комплекту "Рахівниця" (Каса, Склад, Сервіс, Барком). Відключення - лише в момент завершення програми. Тобто якщо ви просто згорнули програму або відкрили іншу програму що не входить до "Рахівниці" (браузер, текстовий редактор, тощо) програма продовжує отримувати відскановані коди. Дуже зручно коли потрібно працювати одночасно і в Касі чи Складі і прайсом постачальника.

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

Це зроблено саме таким чином для того, щоб зависла Каса не блокувала канал зв'язку і при тому щоб коди не почали раптом передаватись у запущений і давно забутий Склад.

Служба слухає на всіх мережевих картах, але касі повідомляє саме event_socket_host. Автоматичне визначення бере першу адресу з 192.168.*, далі будь-яку немісцеву, і аж потім 127.0.0.1. На машині з кількома мережевими картами воно може вибрати не ту: тоді каси отримають непридатну адресу і не під'єднаються — вкажіть потрібну явно.

Пристрої

devices — послідовність, кожен запис якої описує один пристрій.

Ключ Обов'язково Опис
name Так Ім'я пристрою; під ним пристрій видно касі й у журналі. Запис без імені пропускається
type Так scaner, printer, scales, prro
subtype Так Див. нижче; для scales не потрібен

Решта ключів залежить від пари type/subtype. Допустимі пари: scaner/serial, scaner/hid, scaner/devfile, printer/escpos, printer/dummy, scales, prro/eusign, а також будь-який тип із subtype: redirect. Невідома пара пропускається із попередженням у журналі — служба стартує, а пристрою в ній просто немає.

Тип сканера пишеться scaner, з однією n. scanner — невідомий тип.

Спільні параметри RS-232

Застосовуються до scaner/serial і до scales.

Ключ Типово Опис
device — Послідовний порт: /dev/ttyS0, COM1
baudrate 9600 Швидкість передачі
bits 8 Біти даних
parity N N · E · O · S · M
stopbits 1 Стоп-біти
softflow false Програмне керування потоком XON/XOFF
hardflow false Апаратне керування потоком RTS/CTS

scaner/serial

Сканер штрихкодів на послідовному порту. Інших параметрів, крім RS-232, не має. Поки файл пристрою відсутній, сканер показує стан «Not found» і служба щосекунди пробує підключитися знову — від'єднаний і повернутий у розетку сканер запрацює сам.

scaner/hid — лише Linux

Сканер USB, підключений напряму через libusb.

Ключ Типово Опис
vendor_id — Код виробника, шістнадцятковий, без префікса 0x: 0536
product_id — Код моделі, там само: 01b3

Обидва коди показує lsusb.

scaner/devfile — лише Linux

Сканер USB, підключений через файл пристрою.

Ключ Типово Опис
device — Шлях до файлу пристрою: /dev/hidraw0

printer/escpos

Чековий принтер ESC/POS.

Ключ Типово Опис
device — Файл пристрою: /dev/usb/lp0, COM2
width 40 Символів у рядку; за цим значенням переносяться довгі рядки й малюються лінії-роздільники
codepage (немає) Номер кодової сторінки принтера. Якщо не задано, принтер лишається зі своїм поточним налаштуванням
softrender false true — QR-код малює служба і надсилає його як зображення; потрібно для принтерів, які не мають власної команди QR
feed_lines 3 Скільки рядків протягнути перед відрізанням чека

printer/dummy

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

Ключ Типово Опис
target_dir (немає) Куди складати файли. Якщо не задано, чек виводиться в журнал
width 40 Символів у рядку

scales

Ваги на послідовному порту. subtype для них не потрібен.

Ключ Типово Опис
model VTA16 VTA16 або DigiDS
timeout 5000 Скільки мілісекунд чекати на відповідь ваг, перш ніж повернути помилку

Плюс параметри RS-232; device для ваг типово /dev/ttyS0.

prro/eusign

Програмний реєстратор розрахункових операцій. Що робить із ним каса — у розділі про ПРРО.

Ключ Типово Опис
key_path — Файл особистого ключа
key_password — Пароль до ключа
certs_path каталог програми Каталог із сертифікатами. Служба створює його, якщо його немає, і сама наповнює — див. нижче
lib_path /opt/abacus/lib/ Каталог бібліотеки підпису. Якщо його немає — підкаталог lib/ у каталозі програми
proxy_address (немає) Проксі-сервер, через який видно ДПС і сервери надавачів
proxy_port 0 Порт проксі
proxy_user (немає) Користувач проксі
proxy_pass (немає) Пароль проксі
timeout_ms 30000 Скільки мілісекунд чекати на відповідь ДПС
http_retries 2 Скільки разів повторити запит, який не дійшов
http_retry_delay_ms 1000 Пауза між повторами

Шлях, який не починається з кореня чи літери диска, відлічується від каталогу програми.

Проксі. Ті самі proxy_address/proxy_port служба передає двом різним клієнтам: власному — для ДПС, і бібліотеці підпису — для серверів надавачів. Перший очікує SOCKS, друга — HTTP. Тобто один запис має вести на проксі, який розуміє обидва протоколи; інакше працюватиме лише один із двох напрямків. Якщо проксі не потрібен — не задавайте його зовсім: порожнє значення служба явно вимикає в налаштуваннях бібліотеки, тож старе значення не залишається діяти.

Які сертифікати класти в certs_path

Жодних. Достатньо файлу ключа та пароля до нього.

Служба сама створює каталог, якщо його немає, і сама завантажує все потрібне з сервера надавача при першому запуску. Перевірено на ключах трьох різних надавачів: порожній каталог, за 7–50 секунд ключ прочитано й пристрій працює.

  - name: 'main_prro'
    type: 'prro'
    subtype: 'eusign'
    key_path: 'keys/pb_0123456789.jks'
    key_password: 'Password1234'
    certs_path: 'cert/'          # каталогу може ще не існувати

Як це працює: якщо ключ не прочитався, служба бере довідник надавачів (CAs.json) і опитує CMP-сервери всіх акредитованих надавачів, доки один із них не віддасть сертифікати саме для цього контейнера. Отримані сертифікати зберігаються в certs_path, і читання ключа повторюється. Якщо й це не допомогло — довантажується спільний пакунок CACertificates.p7b і читання повторюється ще раз.

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

Для цього потрібно, щоб служба бачила сервери надавачів (iit.com.ua та сайт самого надавача) звичайним HTTP. Каталог certs_path має бути доступний службі на запис.

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

Якщо ключ усе одно не читається

Порядок дій — від найдешевшого до найдорожчого.

1. Перевірте пароль. Помилка 24 або 36 — це пароль або пошкоджений файл ключа. Сертифікати тут ні до чого, і служба навіть не намагається щось завантажувати: у журналі буде Not repairing the store ... the key container itself did not open.

2. Перевірте вік бібліотеки підпису. Це найчастіша причина помилки 50 у 2026 році. Надавачі перейшли на новий алгоритм підпису (ДСТУ 7564), а бібліотека 2020 року його не знає — і повідомляє про це не «непідтримуваний алгоритм», а звичайним «сертифікат пошкоджений». Ознака: ключі одних надавачів працюють, а свіжовидані ключі інших — ні.

strings /opt/abacus/lib/euscp.so | grep -c '1\.2\.804\.2\.1\.1\.1\.1\.3\.6\.'

0 — бібліотека стара, її треба оновити; будь-яке інше число — справа не в ній. Як оновлювати, описано в технічній документації (daemons/docs/eusign_library.md, розділ «Updating the library»).

3. Перевірте доступ до мережі. У журналі Could not fetch certificates ... error 5 означає, що до CMP-серверів не достукатися: немає інтернету, або заданий проксі, який бібліотека не розуміє (див. зауваження про проксі вище).

Перевірити сертифікат власника

Власник, видавець і строк дії — коли треба зрозуміти, чий це сертифікат і чи він ще чинний:

$c = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 'C:\Abacus\Tools\cert\ФАЙЛ.crt'
$c.Subject; $c.Issuer; $c.NotBefore; $c.NotAfter

openssl x509 -inform DER -in /opt/abacus/etc/cert/ФАЙЛ.crt \
  -noout -subject -issuer -dates

Переглянути, що лежить усередині пакунка:

openssl pkcs7 -inform DER -in CACertificates.p7b -print_certs -noout

Що показує журнал під час запуску ПРРО

Рядки йдуть саме в такому порядку. Успішний запуск пристрою — це десяток рядків; якщо їх більше, шукайте помилку між ними.

Рядок у журналі Що вже відбулося
Created cert store <шлях> for <ім'я> каталогу сертифікатів не було, служба його створила
PRRO <ім'я> using key <шлях> (<N> bytes), certs <шлях>, lib <шлях> шляхи розібрано; далі видно, який саме файл ключа взято
EUSign proxy set to <адреса>:<порт> ... проксі бібліотеки налаштовано; якщо проксі не задано, рядка немає
EUSign for <ім'я>: offline <on/off>, check CRLs <on/off>, auto download CRLs <on/off>, OCSP <on/off>, CMP <on/off> режим роботи бібліотеки; адреси серверів OCSP та CMP показано лише тоді, коли їх увімкнено
Cert store <шлях>: <N> files, library accepted <M> end-user certificates два різні числа: файлів у каталозі та сертифікатів кінцевих користувачів, які бібліотека прийняла. Вони не збігаються — сертифікати ЦСК та їхніх серверів рахуються окремо, а один пакунок .p7b містить багато сертифікатів
Key container <шлях> opens on its own, <N> bytes of key info контейнер цілий і пароль правильний
Reading the private key for <ім'я> читання ключа разом із сертифікатами. Якщо журнал уривається саме тут — бібліотека зависла на цьому виклику, а не служба впала
Key certificate <N>: serial <номер>, issued by "<видавець>" сертифікати, які бібліотека зіставила з ключем; за видавцем шукайте надавача
Key loaded for <ім'я>: <власник>, expires <дата>, earliest of <N> own certificates ключ прочитано; дата — найближче завершення дії серед його сертифікатів
Device <ім'я> initialized successfully. пристрій готовий

Якщо ключ не прочитався, замість двох останніх рядків буде помилка, а за нею — перелік усіх сертифікатів кінцевих користувачів, які бібліотека бачить:

Рядок у журналі Що це означає
ReadPrivateKeyFile failed for <ім'я>, error <код>: <опис> код помилки від бібліотеки; найважливіші — нижче
Store certificate <N>: subject "<власник>", serial <номер>, issued by "<видавець>" що саме лежить у сховищі; шукайте тут власника ключа
Not repairing the store for <ім'я>: the key container itself did not open пароль неправильний або файл ключа пошкоджений — завантажувати сертифікати немає сенсу
Fetching CAs.json for <ім'я> from <адреса> завантажується довідник надавачів
Skipping <N> unreachable CMP servers for <ім'я> стільки серверів надавачів не відповіли на з'єднання; решту буде опитано
Fetching certificates for <ім'я> from <N> CMP servers опитування серверів надавачів; займає до півхвилини
Installed <N> bytes of certificates for <ім'я> from the issuer сертифікати отримано й збережено в certs_path
Retrying key read for <ім'я> after repair step <N> повторне читання ключа: 1 — після сертифікатів надавача, 2 — після спільного пакунка
Could not fetch certificates for <ім'я> from the issuer, error 5 до серверів надавачів не достукатися — мережа або проксі
Not fetching certificates for <ім'я>: EUSign is offline сертифікати не довантажувалися, бо бібліотека працює автономно
Device <ім'я> is still initialising after 30 s and is not usable бібліотека не повернула керування; пристрій позначено помилковим, служба працює далі

Два коди помилок трапляються найчастіше, і плутати їх не можна:

Код Опис від бібліотеки Що робити
51 Сертифікат не знайдено проблема каталогу, а не ключа: ланцюжок видавців не сходиться. Зазвичай служба виправляє це сама; якщо ні — немає доступу до серверів надавачів
50 Сертифікат пошкоджений або не може бути використаний сертифікат знайдено, але не приймається. Найчастіша причина у 2026 році — стара бібліотека підпису, яка не знає нового алгоритму надавача; див. крок 2 вище. Рідше — строк дії минув або сертифікат виданий не на цей ключ
24, 36 невірний пароль чи ключ пошкоджений пароль або файл ключа. Сертифікати ні до чого

Слово «сертифікат» в обох описах стосується саме сертифіката, а не файлу ключа — повідомлення служби при цьому каже «Failed to read private key», і через це справний контейнер не раз міняли даремно. Два ключі, які довго вважали пошкодженими, виявилися цілком справними: їм бракувало лише свіжої бібліотеки.

subtype: redirect

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

Ключ Типово Опис
redirect_url — Базова адреса віддаленого абхарда
redirect_name — Ім'я пристрою на ньому
redirect_token — Код токена віддаленого абхарда. Без нього запит піде без авторизації

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

Токени доступу

Файл токенів abhard.json не створює ні інсталятор, ні адміністратор. Служба стартує «нічийною», і перший адміністративний клієнт перебирає її на себе: активація служб у редакторі конфігурації "Складу" (або ініціалізація з лаунчера) отримує від служби адміністраторський токен, далі створює по одному токену на кожну роль і записує їх у базу під мнемонічними кодами. Копіювати ключі руками не потрібно.

Перелік виданих токенів разом з їхніми кодами показує "Склад": довідник працівників, вкладка «Токени». Саме звідти беруть код для redirect_token.

Ініціалізувати службу можна лише доки файлу токенів немає. Далі потрібен раніше виданий адміністраторський токен, а повторна ініціалізація відповідає «вже ініціалізовано».

Роль Права
administrator Усе, разом із видачею та відкликанням токенів
worker Усі операції з обладнанням; не може видавати й відкликати токени
probationer Те саме, що worker, але не може формувати Z-звіт

Токен без дати завершення дії безстроковий. Прострочений токен відхиляється й одразу зникає з файлу.

Приклад

main:
  port: 4601
  whitelist: '127.0.0.1;192.168.50.0/24;172.27.0.2-10'
  event_socket: true
  event_socket_host: '192.168.50.10'
  event_socket_port: 4651
  event_socket_ping_idle: 4

log:
  file: 'abhard.log'
  level: 3
  maxsizekb: 10240
  keepfiles: 10

devices:
  - name: 'main_scaner'
    type: 'scaner'
    subtype: 'serial'
    device: '/dev/ttyS0'
    baudrate: 9600

  - name: 'usb_scaner'
    type: 'scaner'
    subtype: 'hid'
    vendor_id: '0536'
    product_id: '01b3'

  - name: 'main_printer'
    type: 'printer'
    subtype: 'escpos'
    device: '/dev/usb/lp0'
    width: 42
    feed_lines: 3

  - name: 'shared_printer'
    type: 'printer'
    subtype: 'redirect'
    redirect_url: 'http://192.168.50.4:4601'
    redirect_name: 'main_printer'
    redirect_token: 'abhard_<профіль сусіда>_worker'

  - name: 'main_scales'
    type: 'scales'
    device: '/dev/ttyS1'
    model: 'DigiDS'
    timeout: 5000

  - name: 'main_prro'
    type: 'prro'
    subtype: 'eusign'
    key_path: 'keys/pb_0123456789.jks'
    key_password: 'Password1234'
    certs_path: 'cert/'

Каталог cert/ може ще не існувати — служба створить його й наповнить сама.

Перевірка

$KEY — будь-який діючий токен служби.

curl -H "X-API-KEY: $KEY" http://192.168.50.10:4601/api/status

По запису на кожен пристрій: ім'я, тип, стан і остання помилка. Пристрій, якого немає у відповіді, не створився — шукайте попередження в журналі. Перелік усіх доступних запитів віддає /api/list.

Для ПРРО є окрема перевірка зв'язку з ДПС:

# перевірити зараз (цифри у відповіді - час кожного етапу)
curl -H "X-API-KEY: $KEY" http://192.168.50.10:4601/api/prro/main_prro/selftest/run

# останні спроби надсилання документів
curl -H "X-API-KEY: $KEY" "http://192.168.50.10:4601/api/prro/main_prro/history?limit=20"

Після трьох невдалих спроб поспіль служба виконує таку перевірку сама; її результат лишається доступним за /api/prro/<ім'я>/selftest.

Відповідь 401 означає відсутній або недіючий токен, 403 — адресу, якої немає у whitelist, або дію, недоступну для ролі цього токена.