REST API · HW agent 2.15.3

HW agent API

One API for a web application, a POS program and a server: registers, terminals and SBP, printing, scales, displays, scanners, marking.

Address: http://localhost:7790/api/v1/Through the cloud: https://cloud.hw-connector.ru/agent/api/v1/

Getting started Through the cloud OpenAPI

Getting started

1
Address. The agent runs on the computer with the devices and listens on http://localhost:7790 (the port is server.port). From a browser on this computer — a plain fetch, from a program — any HTTP client; from a server — through the cloud.
2
Access. A site with a foreign address (the Origin header) must be on the allowed list: a new site gets SITE_NOT_ALLOWED and the cashier gets an “allow” request in the tray. Programs on this computer (no Origin) pass at once. If the agent has an API token — Authorization: Bearer …; a site with a signing key signs requests on its server.
3
Devices. Devices are added on the agent page; their numbers are in GET /api/v1/devices: /registers/1, /terminals/2, /scales/3.
4
Format. JSON; amounts — integer kopecks; enums — strings (SELL, CARD, VAT20); dates — ISO 8601; errors — problem+json with a code field. No hardware — use the register, terminal, scale and printer emulators.

Principles

Operations

Everything that changes a device state is an operation: POST returns its snapshot {id, type, status, stage, result, error, warnings}. status: QUEUED → RUNNING → SUCCEEDED or FAILED; UNKNOWN — the agent restarted or the device did not answer, check the result on the device. On one device operations run in order, on different devices in parallel.

Retries

Every POST that starts an operation carries Idempotency-Key — e.g. a UUID per cashier action. A retry with the same key returns the same operation and never charges or prints twice; the same key for another operation — IDEMPOTENCY_KEY_REUSED.

Waiting

Prefer: wait=30 — wait for the result up to 30 seconds (at most 180): 200 if the operation finished, otherwise 202 and the operation Location — ask GET /api/v1/operations/{id} or wait for an event.

Events

GET /api/v1/events — Server-Sent Events: operation on every operation change, barcode — a scanner code {deviceId, code, at}, card — a card on the reader, display — lines on the second monitor, qr — an SBP payment QR (payload: null — remove), power — power {source: AC|BATTERY, batteryPercent, minutesLeft}.

Timeouts

An operation waits for its device at most: register 120 s, terminal 300 s, receipt with card payment 420 s, printers 120 s, scales, displays and drawer 60 s (the device queue is not counted). Change them on the agent page, in hw.operations.timeouts or per request with X-HW-Timeout: 30.

Setup

The /api/v1/setup/… methods serve the agent page and work only from it; they are not described here. Devices, printers, the cashier and allowed sites are set up on the agent page or in its settings file — see the help.

A sale

1
In one operation
- POST /api/v1/checkouts — card → receipt → slip; if the receipt fails the payment is cancelled
2
Or step by step
- POST /api/v1/terminals/{id}/payments
- POST /api/v1/registers/{id}/receipts
3
Shift

Receipt

Body of POST /api/v1/registers/{id}/receipts

{
  "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 wrap to the register paper width automatically. Fields — the Receipt model.

Examples

Sale with a card payment — payment, receipt and slip in one operation. The response is an operation with result.receipt (FD number, fiscal sign, shift, QR code) and result.payment (paymentRef for a refund, card, RRN, authorization code, slip).

HTTP

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}

A PDF on the ticket printer — the printer by the role set on the agent page:

HTTP

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

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

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

HTTP

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

{"raw": "XlhBXkZPNTAsNTBeQTBOLDUwXkZESGVsbG9eRlNeWFo=", "printer": "Zebra ZD220"}

Operation progress and the scanner in the browser:

JavaScript

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));

Ready clients — SDKs for JavaScript/TypeScript, Java and C# in the agent repository (the sdk folder), see the help.

API sections

Fiscal registerShift, reports, receipts and correction receipts, cash in and out, fiscal drive documents and status, counters, the register cash drawer.15 methods Payment terminalCard and SBP payment, refund, cancellation, settlement, emergency reversal, reports and slip; a QR code image for SBP payment.8 methods CheckoutA whole sale or refund: payment on the terminal → receipt on the register → slip.1 method PrintingPrinting PDF by URL or as a file, images and printer commands (ESC/POS, ZPL, EPL) on Windows printers and driverless printers; the printer by name, device number or role.9 methods LabelsLabels and price tags from templates: preview as an image and printing on the label printer.4 methods ScalesScale weight and zeroing (zero or tare).2 methods Customer displayText on the customer display and a QR code on a QR display or a second monitor.3 methods Cash drawerCash drawer: on the register, an ESC/POS printer or a COM port.1 method Document scannersWIA and TWAIN document scanners: scan to PDF or a JPEG per page, result files and their deletion.4 methods Product markingMarking module: checking codes in Chestny Znak (TS PIoT, the local module, GIS MT) before the sale and codes in the receipt.5 methods OperationsOperations: status by id (with Prefer: wait — wait for the end), recent operations and Server-Sent Events — operation progress, scanner codes, card reads, power.3 methods Device portRaw byte exchange with a device port from the list (COM, TCP, HID): send and read the answer.1 method Computer and filesComputer details and the agent installation id; files in an allowed folder (when hw.files.enabled is on).5 methods AgentThe agent is running, its version and power state; the device list; language; build branding.5 methods EmulatorsRegister, terminal, scale and printer emulators for debugging without hardware: response modes (out of paper, terminal declines).2 methods