hw-connector

A local web service through which web applications work with the computer's point-of-sale hardware: fiscal registers, payment terminals, printers, customer displays, scanners and card readers.

The service runs on the computer the hardware is connected to and accepts requests only from that computer: http://localhost:7790. It has two sides:

• Setup page — http://localhost:7790/: adding and checking devices, printers, report templates, the operation journal.
• REST API — http://localhost:7790/api/v1: a web application in the browser or a program on this computer prints receipts, takes card payments, prints documents. The full description with examples is in Swagger UI (in Russian and English), the OpenAPI schema — /v3/api-docs/en and /v3/api-docs/ru.

The service runs in the background, shows an icon in the Windows tray and starts with Windows.

Quick start

1. Install the hardware software if needed (see Hardware): the DTO10 x64 driver for ATOL registers, the bank software for the terminal.
2. Open the setup page: tray icon → “Open interface” or http://localhost:7790/.
3. On the Devices tab click “Add device”, choose the type, fill in the fields and click “Save and check”. The device card shows “online” or what to fix.
4. On the Printers tab assign printers for tickets and documents, set the paper and print a test page.
5. On the Workplace tab enter the cashier and, if needed, the sender email, place of settlement and tax system.
6. Connect the web application to the API (see API).

Menu

The interface language is switched with the RU / EN buttons in the page header, in the help and in the tray icon menu.

Devices

Device cards: fiscal registers, terminals, driverless printers, customer displays, scanners, card readers, cash drawers, ports. The number in the card corner (No. 1, No. 2…) is the device number in the API.

• Switch — enable or disable the device. A disabled device does not accept operations.
• Check — check the connection without money operations: for a register — the shift state, for a terminal — the bank software or the terminal reply, for a scanner — whether the port is open and the last code.
• Operations — manual actions. Register: open shift, X report, close shift (Z report), open the cash drawer, cash in and cash out. Terminal: settlement, the slip is shown on screen. Printer: print text, open the drawer (ESC/POS). Display: show lines, clear, open the second-monitor page. Drawer: open. Port: send bytes and see the reply. Scanners and readers have no operations — codes and cards arrive as events.
• ⚙ Configure — change settings or delete the device.
• Add device — choose the type and fill in the fields. The COM port is picked from a list with device names; the ⟳ button searches for ports again. Changes apply immediately, without restarting the service.

Printers

• Roles — the printer for tickets and the printer for documents. The application prints “by role” (role) without knowing the printer name. Without a role — the default Windows printer. A driverless printer from the device list can be assigned too.
• Print settings — paper (as in the document, ticket stock 148 × 79 mm, 80 or 58 mm roll, A4 or custom size), scale (as in the document, fit to paper, shrink if it does not fit), orientation. Applied to PDFs, images and reports; printer commands (raw) go as is.
• Test page — printer name, date and Cyrillic text: you see right away that printing and fonts work.

Reports

• The list of JasperReports templates (*.jrxml) with parameters $P{…} and fields $F{…}.
• The installation includes the TICKET template — a ticket on 148 × 79 mm stock. Each data row is printed as a separate ticket on its own page; fields: top_line, upper_line, pos_line, addr_line, service_line, date_line, place_line, price_line, sold_line, sale_line, control_line, bottom_line, footer_line.
• Upload template or drop files onto the page. The template is checked by compiling it: a template with errors is not saved. You can also just put files into the template folder — its path is shown on the page.
• Generate — enter parameters and data rows in JSON, open the PDF or send it to a printer.

Workplace

Default values for register operations. The service uses them only when the request does not contain them; what is passed in the request always wins.

• Cashier: full name (tag 1021) and tax ID (tag 1203). If the cashier is set, the operator field can be omitted in requests. If the cashier is set neither in the request nor here, the operation is rejected (422).
• Sender email (tag 1117): the return address of electronic receipts.
• Place of settlement (tag 1187): empty — as registered in the register.
• Tax system: “As in the register” — the register chooses it itself.

Further down the same tab — access to the agent and PDF printing. Changes apply at once, without a restart, and are saved in data\access.json; “As in the settings file” returns the values from config\application.yml.

• Allowed sites: addresses of the POS program (for example https://bigbilet.com) that may call the agent from the browser. Requests from other sites are rejected.
• API token: if set, the POS program sends Authorization: Bearer <token> (for events — ?access_token=). “Create” makes up a random token — copy it into the POS program settings, otherwise it gets 401. Empty — no token needed.
• Where printing is allowed from: the beginning of PDF addresses the agent downloads for printing; download wait, largest file size and number of files in one job.

Journal

All device operations: status, what is happening now, result or error. Updates live (the green dot by the tab means events are connected). Clicking a row shows the whole operation. The last 1000 operations are kept, including after a restart.

Tray icon

The icon shows that the service is running; the tooltip and the top menu lines show the version, the number of enabled devices and the port. Double-click opens the interface. Menu (right click):

• Open interface, Operation journal, Help — pages in the browser.
• Check devices — checks the connection to all enabled devices, the result arrives as a Windows notification.
• Program folder — settings (config\, data\), report templates and logs.
• Start with Windows — a shortcut in Startup; available in the installed program. Autostart turns on by itself at the first start after installation.
• Язык / Language — Russian or English. The language is shared by the icon, the setup page and the help; on the page it is switched with the RU / EN buttons in the header.
• Exit — after confirmation: while the service is stopped, devices and printing are unavailable.

Supported hardware

To test without hardware there are register and terminal emulators (the “For development” group).

Compatible fiscal registers

Many registers of other brands use the Shtrih-M or Pirit protocol inside. They need no separate driver: each has its own item in the “Add a device” window, and the settings are the same as for registers with that protocol.

If there is no connection, check the COM port speed and the exchange protocol version on the register itself: they are usually printed in the self-test when it is switched on with the paper feed button held.

SBP QR payment. “SBP QR payment” is added as a payment terminal and called with the same /terminals/{id}/… methods. On payment the application creates a payment at the bank and shows the QR code: in the application window, on the customer display whose number is set in the settings (a second monitor, a Mertech or QR-Screen QR code display), and as the qr event for your program. The customer scans the QR in their bank app; the application asks the bank for the status every 2 seconds. If it is not paid within the wait time, the payment is cancelled. The bank payment ID is returned in paymentRef.idProcessing and is used for refunds. No settlement is needed for SBP.

• T-Bank: the TerminalKey and terminal password from the T-Business account (Internet acquiring → Shops → Terminals).
• Sberbank: the API login and password (usually …-api) issued by the bank.
• The “Test” environment uses the banks' test servers: no money is charged, handy for trying it out.

API

Principles

• Operations. Everything that changes a device's state is an operation. POST returns its snapshot: {id, type, status, stage, result, error, warnings, createdAt, startedAt, finishedAt}. status: QUEUED → RUNNING → SUCCEEDED or FAILED; UNKNOWN — the service restarted during the operation, check the result on the device.
• Queue. Operations on one device run one at a time, on different devices — in parallel.
• Idempotency. Every operation POST carries an Idempotency-Key header (e.g. a UUID per user action). A repeat with the same key returns the same operation and does not charge the card twice.
• Waiting. Prefer: wait=30 — wait up to 30 seconds for the result (180 at most): 200 if the operation finished, otherwise 202 and Location with the operation URL.
• Events. GET /api/v1/events — Server-Sent Events: operation on every operation change, barcode — a scanner code {deviceId, code, at}, card — a card on a reader {deviceId, uid, atr, reader, at}, display — second-monitor display lines, qr — the QR for an SBP payment {deviceId, display, payload, amount, paymentId, bank, at} (payload: null — remove the QR), power — power change {source: AC|BATTERY, battery, batteryPercent, minutesLeft}, language — interface language change.
• Amounts — integer kopecks. Enumerations — strings (SELL, CARD, VAT20).
• Documentation. Swagger UI — all fields and examples; the description language is chosen in the “Select a definition” list.

Methods

* operator can be omitted if the cashier is set on the Workplace tab. Then the request body is not needed either.

The /api/v1/setup/… methods serve the setup page and are available only from it.

Receipt

{
  "type": "SELL",                       // SELL, SELL_RETURN, BUY, BUY_RETURN
  "taxation": "USN_INCOME",             // OSN, USN_INCOME, USN_INCOME_OUTCOME, ESHN, PATENT; absent — from Workplace or the register default
  "operator": {"name": "Ivanova I.I.", "inn": "770123456789"},   // absent — the cashier from Workplace
  "customer": {"contact": "+79991234567"},   // for an electronic receipt
  "header": [
    {"kind": "TEXT", "text": "Order 123", "align": "CENTER"},
    {"kind": "PAIR", "text": "Date:", "right": "01.11.2026 19:00"},
    {"kind": "SEPARATOR"}
  ],
  "items": [
    {"name": "Service", "price": 150000, "quantity": 1, "amount": 150000,
     "vat": "NONE", "paymentMethod": "FULL_PAYMENT", "paymentObject": "SERVICE"}
  ],
  "payments": [{"type": "CARD", "amount": 150000}],   // CASH, CARD, PREPAID, CREDIT, OTHER
  "footer": [],
  "electronic": false,                  // true — do not print, send to the customer
  "senderEmail": "kassa@example.ru",    // tag 1117; absent — from Workplace
  "settlementPlace": "Cash desk"        // tag 1187; absent — from Workplace
}

The sum of payments must equal the sum of items, an item amount — price × quantity. Text lines are wrapped to the register paper width automatically.

Examples

Sale with a card payment — payment, receipt and slip in one operation:

POST /api/v1/checkouts
Content-Type: application/json
Idempotency-Key: 3f6c1d9e-1b2a-4c55-9e0d-6a1f0c2b7d11
Prefer: wait=170

{"registerId": 1, "terminalId": 2, "receipt": { … }, "printSlip": true}

Response: an operation with result.receipt (FD number, fiscal sign, shift, QR code) and result.payment (paymentRef, card, RRN, authorization code, slip). paymentRef is needed for a refund.

Printing a PDF on the ticket printer:

POST /api/v1/print-jobs
Idempotency-Key: …

{"urls": ["https://example.com/tickets/1.pdf"], "role": "tickets", "copies": 1}

Report by template — a PDF right away or to a printer:

POST /api/v1/reports/ACT/render
{"parameters": {"NUMBER": "15", "DATE": "2026-11-01"},
 "rows": [{"NAME": "Item 1", "PRICE": 1500}]}

POST /api/v1/print-jobs
{"report": {"name": "ACT", "parameters": { … }, "rows": [ … ]}, "role": "documents"}

Tickets by the TICKET template — one ticket per row, on the ticket printer:

POST /api/v1/print-jobs
Idempotency-Key: …

{"report": {"name": "TICKET", "rows": [
  {"top_line": "Concerts LLC", "pos_line": "Grand hall", "addr_line": "1 Tverskaya St.",
   "service_line": "Concert (12+)", "date_line": "Date: 01.11.2026 Start: 19:00",
   "place_line": "Stalls row 5 seat 12", "price_line": "Price: 1500.00",
   "sold_line": "31.10.2026 10:00 Cashier: Ivanova I.I.", "sale_line": "1911-000123"}
 ]}, "role": "tickets"}

Printer commands as is (ESC/POS, ZPL) — e.g. a ZPL label:

POST /api/v1/print-jobs
{"raw": "XlhBXkZPNTAsNTBeQTBOLDUwXkZESGVsbG9eRlNeWFo=", "printer": "Zebra ZD220"}

Waiting for an operation and events in the browser:

const events = new EventSource('http://localhost:7790/api/v1/events');
events.addEventListener('operation', e => {
  const op = JSON.parse(e.data);
  console.log(op.type, op.status, op.stage);    // e.g. "tap the card on the terminal"
});
events.addEventListener('barcode', e => console.log(JSON.parse(e.data).code));

Errors

Request errors — RFC 9457 responses (application/problem+json) with a code field:

Device errors arrive in the operation itself: status: FAILED, error: {code, message, details}. Error texts from devices are in Russian.

Settings and files

Devices, printer roles and settings, the workplace, access, printing limits and the language are changed on the setup page (values from the page win over the file). Everything else is in config\application.yml in the program folder:

Security

• The service listens only on 127.0.0.1: it cannot be reached from other computers.
• Browser requests are accepted only from pages in hw.allowed-origins and from the service's own page; requests from other sites are rejected before execution.
• The host name must be localhost or 127.0.0.1 — protection against DNS rebinding.
• Device setup — only from the service's own page.
• PDFs are downloaded only from allowed addresses, with a timeout and a size limit.
• Report templates contain executable expressions: only someone with access to this computer can upload them.