{ "openapi": "3.1.0", "info": { "title": "hw-connector", "description": "Cash desk agent on the cashier's PC: fiscal registers, payment terminals, PDF printing.\n\nEverything that changes a device's state is an **operation**: `POST` with the `Idempotency-Key` header\nreturns `202` and a link `/api/v1/operations/{id}`. With the `Prefer: wait=30` header\nthe agent waits up to 30 seconds for the result and replies `200` if it finished. Operation changes\narrive as events `GET /api/v1/events` (Server-Sent Events). Amounts are in kopecks.", "version": "2.2.0" }, "servers": [ { "url": "http://localhost:7790", "description": "Agent on the cashier PC" } ], "paths": { "/api/v1/setup/workplace": { "get": { "tags": [ "Setup" ], "summary": "Workplace settings", "description": "Default cashier, sender email, place of settlement and tax system", "operationId": "getWorkplace", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Workplace" } } } } } }, "put": { "tags": [ "Setup" ], "summary": "Save workplace settings", "description": "Used in register operations where the client did not pass them. Saved to data/workplace.json", "operationId": "saveWorkplace", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workplace" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Workplace" } } } } } } }, "/api/v1/setup/printers/settings": { "put": { "tags": [ "Setup" ], "summary": "Printer print settings", "description": "Borderless paper of the right size (ticket stock), scale, orientation", "operationId": "setPrinterSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrinterSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/PrinterSettings" } } } } } } }, "/api/v1/setup/printers/roles": { "get": { "tags": [ "Setup" ], "summary": "Printer roles", "operationId": "roles", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrinterRole" } } } } } } }, "put": { "tags": [ "Setup" ], "summary": "Assign printers", "description": "{\"tickets\": \"printer name\", \"documents\": \"\"}; empty — the default printer", "operationId": "setRoles", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrinterRole" } } } } } } } }, "/api/v1/setup/language": { "put": { "tags": [ "Agent" ], "summary": "Change the agent interface language", "description": "ru or en; open pages receive the language event", "operationId": "set", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LanguageRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/api/v1/setup/devices/{number}": { "put": { "tags": [ "Setup" ], "summary": "Add or change a device", "description": "Applied immediately and saved to data/devices.json", "operationId": "save", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceSettings" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/DeviceConfig" } } } } } }, "delete": { "tags": [ "Setup" ], "summary": "Delete a device", "operationId": "delete", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/setup/access": { "get": { "tags": [ "Setup" ], "summary": "Access and printing", "description": "Allowed sites, API token, where PDFs may be printed from and download limits", "operationId": "getAccess", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AccessView" } } } } } }, "put": { "tags": [ "Setup" ], "summary": "Save access and printing", "description": "Applies at once, without a restart. Saved in data/access.json; a null field means the value from config/application.yml", "operationId": "saveAccess", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessSettings" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AccessView" } } } } } } }, "/api/v1/terminals/{id}/settlements": { "post": { "tags": [ "Payment terminal" ], "summary": "Settlement", "description": "End of day on the terminal; the slip is in the result", "operationId": "settlement", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/terminals/{id}/reports": { "post": { "tags": [ "Payment terminal" ], "summary": "Terminal report", "description": "The shift's operations without settlement with the bank; full=true — for each operation. The slip is in the result", "operationId": "report", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/terminals/{id}/refunds": { "post": { "tags": [ "Payment terminal" ], "summary": "Refund to card", "description": "For payments of previous days, after the settlement", "operationId": "refund", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReversalRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/terminals/{id}/payments": { "post": { "tags": [ "Payment terminal" ], "summary": "Card payment", "operationId": "pay", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/terminals/{id}/emergency-reversals": { "post": { "tags": [ "Payment terminal" ], "summary": "Emergency reversal of the last operation", "description": "When the POS did not get the payment result (connection lost, hang): the terminal reverses its last operation", "operationId": "emergencyReversal", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmergencyReversalRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/terminals/{id}/cancellations": { "post": { "tags": [ "Payment terminal" ], "summary": "Cancel a payment", "description": "The same day, before the settlement; the money is not charged", "operationId": "cancel", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReversalRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/setup/printers/test": { "post": { "tags": [ "Setup" ], "summary": "Print a test page", "operationId": "testPrint", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestPrint" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } } } } }, "/api/v1/setup/devices/{number}/check": { "post": { "tags": [ "Setup" ], "summary": "Check the connection", "description": "No money operations: register — shift state, terminal — bank software or terminal login", "operationId": "check", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/CheckResult" } } } } } } }, "/api/v1/registers/{id}/shift/open": { "post": { "tags": [ "Fiscal register" ], "summary": "Open shift", "operationId": "openShift", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/shift/close": { "post": { "tags": [ "Fiscal register" ], "summary": "Close shift (Z report)", "description": "By law the Z report is the shift closing report: it does not exist separately from closing", "operationId": "closeShift", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/reports/x": { "post": { "tags": [ "Fiscal register" ], "summary": "X report", "operationId": "xReport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/reports/calculation-state": { "post": { "tags": [ "Fiscal register" ], "summary": "Current calculation state report", "description": "A fiscal document from the fiscal drive: how many documents have not been sent to the OFD and since when", "operationId": "calculationStateReport", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/receipts": { "post": { "tags": [ "Fiscal register" ], "summary": "Print a receipt", "description": "Receipt on the register only. Together with a card payment — POST /api/v1/checkouts", "operationId": "receipt", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/fn-documents/{number}/print": { "post": { "tags": [ "Fiscal register" ], "summary": "Print a copy of a fiscal drive document", "description": "ATOL, Pirit: a document from the fiscal drive archive by number", "operationId": "printFnDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/documents": { "post": { "tags": [ "Fiscal register" ], "summary": "Print non-fiscal text", "description": "Terminal slip, service documents", "operationId": "document", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TextRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/corrections": { "post": { "tags": [ "Fiscal register" ], "summary": "Print a correction receipt", "description": "Receipt type — the same as the corrected transaction: SELL, SELL_RETURN, BUY, BUY_RETURN", "operationId": "correction", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectionRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/cash/out": { "post": { "tags": [ "Fiscal register" ], "summary": "Cash out", "operationId": "cashOut", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/cash/in": { "post": { "tags": [ "Fiscal register" ], "summary": "Cash in", "operationId": "cashIn", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CashRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/registers/{id}/cash-drawer/open": { "post": { "tags": [ "Fiscal register" ], "summary": "Open the cash drawer", "description": "The drawer is connected to the register; no request body", "operationId": "openCashDrawer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/print-jobs": { "post": { "tags": [ "Printing" ], "summary": "Printing", "description": "PDF по ссылкам, готовый PDF или картинки — с настройками принтера (масштаб, бумага);\nraw — команды ESC/POS, ZPL, EPL напрямую на принтер. Ссылки скачиваются до печати", "operationId": "print", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrintJobRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/displays/{id}": { "get": { "tags": [ "Customer display" ], "summary": "What is shown on the display", "description": "For the second-monitor display: the page takes the lines from here when it opens", "operationId": "shown", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } }, "post": { "tags": [ "Customer display" ], "summary": "Show lines on the customer display", "description": "VFD — usually 2 lines of 20 characters; second monitor — up to 10 large lines. Immediate, not an operation", "operationId": "show", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisplayRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/displays/{id}/qr": { "post": { "tags": [ "Customer display" ], "summary": "Show a QR code on the customer display", "description": "QR code display (Mertech QR-PA, QR-Screen) or second monitor. An empty payload removes the QR. Immediate, not an operation", "operationId": "qr", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QrRequest" } } }, "required": true }, "responses": { "200": { "description": "OK" } } } }, "/api/v1/checkouts": { "post": { "tags": [ "Checkout" ], "summary": "Sale or refund with a receipt", "description": "Order: card operation on the terminal (if there is a CARD payment) → receipt on the register → slip on the register.\nIf the receipt fails after a card payment, the payment is cancelled on the terminal (error PAYMENT_CANCELLED);\nif the cancellation also fails — PAYMENT_NOT_CANCELLED with the payment data in error.details.\nResult: { receipt: fiscal document, payment: card operation }.", "operationId": "checkout", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/channels/{id}/exchange": { "post": { "tags": [ "Device port" ], "summary": "Send bytes to the port and get the reply", "description": "Only for ports added on the setup page (kind “Device port”). Immediate, not an operation", "operationId": "exchange", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeRequest" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ExchangeResult" } } } } } } }, "/api/v1/cash-drawers/{id}/open": { "post": { "tags": [ "Cash drawer" ], "summary": "Open the cash drawer", "description": "id — the device the drawer is connected to: register, ESC/POS printer or a drawer on a COM port. Immediate, not an operation", "operationId": "open", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK" } } } }, "/api/v1/terminals/{id}/last-slip": { "get": { "tags": [ "Payment terminal" ], "summary": "Last terminal slip", "description": "The slip of the last successful operation from the journal (payment, refund, cancellation, settlement, checkout) — to print it again", "operationId": "lastSlip", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/api/v1/setup/types": { "get": { "tags": [ "Setup" ], "summary": "Supported devices and their setup fields", "operationId": "types", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Type" } } } } } } } }, "/api/v1/setup/ports": { "get": { "tags": [ "Setup" ], "summary": "Computer COM ports", "operationId": "ports", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Port" } } } } } } } }, "/api/v1/setup/devices": { "get": { "tags": [ "Setup" ], "summary": "Device settings", "operationId": "list", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceConfig" } } } } } } } }, "/api/v1/registers/{id}/shift": { "get": { "tags": [ "Fiscal register" ], "summary": "Shift state", "description": "Read from the register; if the register is busy with another operation for more than 10 s — 409", "operationId": "shift", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ShiftState" } } } } } } }, "/api/v1/registers/{id}/fn-documents/{number}": { "get": { "tags": [ "Fiscal register" ], "summary": "Fiscal drive document by number", "description": "Document attributes from the fiscal drive archive (ATOL, Shtrih-M): the register's answer as is — for Shtrih-M a list of tags {tag, value}", "operationId": "fnDocument", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/api/v1/registers/{id}/counters": { "get": { "tags": [ "Fiscal register" ], "summary": "Register counters", "description": "Receipt count and sums by calculation sign for the shift and the whole fiscal drive (ATOL — the driver's answer as is); sums in kopecks", "operationId": "counters", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": {} } } } } } } }, "/api/v1/qr": { "get": { "tags": [ "Банковские терминалы" ], "summary": "QR code as a PNG image", "description": "text — what to encode, e.g. the payload from the qr event; size — side in pixels (100–1200)", "operationId": "qr_1", "parameters": [ { "name": "text", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 400 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "string", "format": "byte" } } } } } } }, "/api/v1/printers": { "get": { "tags": [ "Printing" ], "summary": "Windows printers, their roles and print settings", "operationId": "printers", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PrinterInfo" } } } } } } } }, "/api/v1/operations": { "get": { "tags": [ "Operations" ], "summary": "Recent operations", "description": "Newest first; the journal keeps the last 1000, including after a restart", "operationId": "recent", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } } } } } } }, "/api/v1/operations/{id}": { "get": { "tags": [ "Operations" ], "summary": "Operation", "description": "With the Prefer: wait=N header waits up to N seconds for completion", "operationId": "get", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Prefer", "in": "header", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Operation" } } } } } } }, "/api/v1/language": { "get": { "tags": [ "Agent" ], "summary": "Agent interface language", "description": "ru or en", "operationId": "get_1", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } } } }, "/api/v1/health": { "get": { "tags": [ "Agent" ], "summary": "The agent is running", "description": "Version, start time, power; the client checks that the agent is installed", "operationId": "health", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/AgentInfo" } } } } } } }, "/api/v1/events": { "get": { "tags": [ "Operations" ], "summary": "Events (Server-Sent Events)", "description": "event: operation, data: the operation — on every status or stage change. The token can be passed in ?access_token=", "operationId": "events", "responses": { "200": { "description": "OK", "content": { "text/event-stream": { "schema": { "$ref": "#/components/schemas/SseEmitter" } } } } } } }, "/api/v1/devices": { "get": { "tags": [ "Agent" ], "summary": "Workplace devices", "operationId": "devices", "responses": { "200": { "description": "OK", "content": { "*/*": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceInfo" } } } } } } } } }, "components": { "schemas": { "Workplace": { "type": "object", "description": "Настройки рабочего места", "properties": { "cashierName": { "type": "string", "maxLength": 64, "minLength": 0 }, "cashierInn": { "type": "string", "pattern": "\\d{12}" }, "senderEmail": { "type": "string", "format": "email", "maxLength": 64, "minLength": 0 }, "settlementPlace": { "type": "string", "maxLength": 128, "minLength": 0 }, "taxation": { "type": "string", "enum": [ "OSN", "USN_INCOME", "USN_INCOME_OUTCOME", "ESHN", "PATENT" ] } } }, "PrinterSettings": { "type": "object", "properties": { "scaling": { "type": "string", "enum": [ "ACTUAL", "FIT", "SHRINK" ] }, "orientation": { "type": "string", "enum": [ "AUTO", "PORTRAIT", "LANDSCAPE" ] }, "paperWidthMm": { "type": "number", "format": "double", "exclusiveMinimum": 0 }, "paperHeightMm": { "type": "number", "format": "double", "exclusiveMinimum": 0 } } }, "PrinterSettingsRequest": { "type": "object", "properties": { "printer": { "type": "string", "minLength": 1 }, "settings": { "$ref": "#/components/schemas/PrinterSettings" } }, "required": [ "printer" ] }, "PrinterRole": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "printer": { "type": "string" } } }, "LanguageRequest": { "type": "object", "properties": { "language": { "type": "string", "minLength": 1 } }, "required": [ "language" ] }, "DeviceSettings": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "active": { "type": "boolean" }, "params": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "type" ] }, "DeviceConfig": { "type": "object", "properties": { "number": { "type": "integer", "format": "int32" }, "type": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "params": { "type": "object", "additionalProperties": { "type": "string" } } } }, "AccessSettings": { "type": "object", "properties": { "allowedOrigins": { "type": "array", "items": { "type": "string", "pattern": "https?://[^/\\s]+" }, "maxItems": 20, "minItems": 0 }, "apiToken": { "type": "string", "maxLength": 200, "minLength": 0 }, "printUrlPrefixes": { "type": "array", "items": { "type": "string", "pattern": "https?://\\S+" }, "maxItems": 20, "minItems": 0 }, "downloadTimeoutSec": { "type": "integer", "format": "int32", "maximum": 600, "minimum": 1 }, "maxFileSizeMb": { "type": "integer", "format": "int32", "maximum": 500, "minimum": 1 }, "maxUrlsPerRequest": { "type": "integer", "format": "int32", "maximum": 1000, "minimum": 1 } } }, "AccessView": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/AccessSettings" }, "defaults": { "$ref": "#/components/schemas/AccessSettings" } } }, "Operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "idempotencyKey": { "type": "string" }, "resources": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "SUCCEEDED", "FAILED", "UNKNOWN" ] }, "stage": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time" }, "finishedAt": { "type": "string", "format": "date-time" }, "result": {}, "error": { "$ref": "#/components/schemas/OperationError" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "OperationError": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } }, "ReversalRequest": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 }, "paymentRef": { "type": "string", "minLength": 1 } }, "required": [ "paymentRef" ] }, "PaymentRequest": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 } } }, "EmergencyReversalRequest": { "type": "object", "properties": { "amount": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 }, "paymentRef": { "type": "string" } } }, "TestPrint": { "type": "object", "properties": { "printer": { "type": "string" } } }, "CheckResult": { "type": "object", "properties": { "ok": { "type": "boolean" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": {} } } }, "Operator": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "inn": { "type": "string" } }, "required": [ "name" ] }, "OperatorRequest": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/Operator" } } }, "Customer": { "type": "object", "properties": { "contact": { "type": "string" }, "name": { "type": "string" }, "inn": { "type": "string" } } }, "Receipt": { "type": "object", "description": "Кассовый чек", "properties": { "type": { "type": "string", "enum": [ "SELL", "SELL_RETURN", "BUY", "BUY_RETURN" ] }, "taxation": { "type": "string", "enum": [ "OSN", "USN_INCOME", "USN_INCOME_OUTCOME", "ESHN", "PATENT" ] }, "operator": { "$ref": "#/components/schemas/Operator" }, "customer": { "$ref": "#/components/schemas/Customer" }, "header": { "type": "array", "items": { "$ref": "#/components/schemas/TextLine" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptItem" }, "minItems": 1 }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptPayment" }, "minItems": 1 }, "footer": { "type": "array", "items": { "$ref": "#/components/schemas/TextLine" } }, "electronic": { "type": "boolean" }, "senderEmail": { "type": "string" }, "settlementPlace": { "type": "string" } }, "required": [ "items", "payments", "type" ] }, "ReceiptItem": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "price": { "type": "integer", "format": "int64", "minimum": 0 }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "amount": { "type": "integer", "format": "int64", "minimum": 0 }, "vat": { "type": "string", "enum": [ "NONE", "VAT0", "VAT5", "VAT7", "VAT10", "VAT20", "VAT22", "VAT105", "VAT107", "VAT110", "VAT120", "VAT122" ] }, "paymentMethod": { "type": "string", "enum": [ "FULL_PREPAYMENT", "PREPAYMENT", "ADVANCE", "FULL_PAYMENT", "PARTIAL_PAYMENT", "CREDIT", "CREDIT_PAYMENT" ] }, "paymentObject": { "type": "string", "enum": [ "COMMODITY", "EXCISE", "JOB", "SERVICE", "GAMBLING_BET", "GAMBLING_PRIZE", "LOTTERY", "LOTTERY_PRIZE", "INTELLECTUAL_ACTIVITY", "PAYMENT", "AGENT_COMMISSION", "COMPOSITE", "ANOTHER" ] }, "department": { "type": "integer", "format": "int32" } }, "required": [ "name", "paymentMethod", "paymentObject", "quantity", "vat" ] }, "ReceiptPayment": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CASH", "CARD", "PREPAID", "CREDIT", "OTHER" ] }, "amount": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 } }, "required": [ "type" ] }, "TextLine": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TEXT", "PAIR", "SEPARATOR" ] }, "text": { "type": "string" }, "right": { "type": "string" }, "align": { "type": "string", "enum": [ "LEFT", "CENTER", "RIGHT" ] } }, "required": [ "kind" ] }, "TextRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/TextLine" }, "minItems": 1 } }, "required": [ "lines" ] }, "Correction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SELF", "INSTRUCTION" ] }, "baseDate": { "type": "string", "format": "date" }, "baseNumber": { "type": "string" } }, "required": [ "baseDate", "type" ] }, "CorrectionRequest": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/Receipt" }, "correction": { "$ref": "#/components/schemas/Correction" } }, "required": [ "correction", "receipt" ] }, "CashRequest": { "type": "object", "properties": { "operator": { "$ref": "#/components/schemas/Operator" }, "amount": { "type": "integer", "format": "int64", "exclusiveMinimum": 0 } } }, "PrintJobRequest": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "document": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "raw": { "type": "string" }, "text": { "type": "array", "items": { "$ref": "#/components/schemas/TextLine" } }, "printer": { "type": "string" }, "device": { "type": "integer", "format": "int32" }, "role": { "type": "string" }, "copies": { "type": "integer", "format": "int32", "maximum": 20, "minimum": 1 } } }, "DisplayRequest": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "minItems": 0 } }, "required": [ "lines" ] }, "QrRequest": { "type": "object", "properties": { "payload": { "type": "string", "maxLength": 2000, "minLength": 0 }, "top": { "type": "string", "maxLength": 100, "minLength": 0 }, "bottom": { "type": "string", "maxLength": 100, "minLength": 0 } } }, "CheckoutRequest": { "type": "object", "properties": { "registerId": { "type": "integer", "format": "int32", "exclusiveMinimum": 0 }, "terminalId": { "type": "integer", "format": "int32" }, "receipt": { "$ref": "#/components/schemas/Receipt" }, "originalPaymentRef": { "type": "string" }, "printSlip": { "type": "boolean" } }, "required": [ "receipt" ] }, "ExchangeRequest": { "type": "object", "properties": { "hex": { "type": "string" }, "base64": { "type": "string" }, "text": { "type": "string" }, "charset": { "type": "string" }, "readTimeoutMs": { "type": "integer", "format": "int32", "maximum": 60000, "minimum": 0 }, "maxBytes": { "type": "integer", "format": "int32", "maximum": 65536, "minimum": 1 }, "until": { "type": "string" } } }, "ExchangeResult": { "type": "object", "properties": { "bytes": { "type": "integer", "format": "int32" }, "hex": { "type": "string" }, "base64": { "type": "string" }, "text": { "type": "string" } } }, "Field": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "input": { "type": "string" }, "defaultValue": { "type": "string" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Option" } }, "help": { "type": "string" }, "showIf": { "type": "object", "additionalProperties": { "type": "string" } }, "required": { "type": "boolean" } } }, "Option": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } }, "Type": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "FISCAL_REGISTER", "PAYMENT_TERMINAL", "BARCODE_SCANNER", "PRINTER", "CASH_DRAWER", "CUSTOMER_DISPLAY", "CARD_READER", "CHANNEL" ] }, "title": { "type": "string" }, "vendor": { "type": "string" }, "description": { "type": "string" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } }, "developer": { "type": "boolean" } } }, "Port": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "ShiftState": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "OPENED", "CLOSED", "EXPIRED" ] }, "number": { "type": "integer", "format": "int32" } } }, "PrinterInfo": { "type": "object", "properties": { "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "string" } }, "settings": { "$ref": "#/components/schemas/PrinterSettings" } } }, "AgentInfo": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "power": { "$ref": "#/components/schemas/Power" } } }, "Power": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "AC", "BATTERY", "UNKNOWN" ] }, "battery": { "type": "boolean" }, "batteryPercent": { "type": "integer", "format": "int32" }, "minutesLeft": { "type": "integer", "format": "int32" }, "at": { "type": "string", "format": "date-time" } } }, "SseEmitter": { "type": "object", "properties": { "timeout": { "type": "integer", "format": "int64" } } }, "DeviceInfo": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "kind": { "type": "string", "enum": [ "FISCAL_REGISTER", "PAYMENT_TERMINAL", "BARCODE_SCANNER", "PRINTER", "CASH_DRAWER", "CUSTOMER_DISPLAY", "CARD_READER", "CHANNEL" ] }, "type": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "info": { "type": "object", "additionalProperties": {} } } } } } }