REST API · HW agent 2.14.1
API HW agent
Один API для веб-приложения, программы кассы и сервера: ККТ, терминалы и СБП, печать, весы, дисплеи, сканеры, маркировка.
Как начать
- 1Адрес. Агент работает на компьютере с оборудованием и слушает
http://localhost:7790(порт меняется вserver.port). Из браузера на этом компьютере — обычныйfetch, из программы — любой HTTP-клиент; с сервера — через облако. - 2Доступ. Сайт с чужим адресом (заголовок
Origin) должен быть в списке разрешённых: новый сайт получаетSITE_NOT_ALLOWED, а кассир — запрос «разрешить» в трее. Программы на этом компьютере (безOrigin) проходят сразу. Если на агенте задан токен API —Authorization: Bearer …; сайт с ключом подписи подписывает запросы своим сервером. - 3Устройства. Устройства подключают на странице агента; их номера — в
GET /api/v1/devices:/registers/1,/terminals/2,/scales/3. - 4Формат. JSON; суммы — целые копейки; перечисления — строками (
SELL,CARD,VAT20); даты — ISO 8601; ошибки — problem+json с полемcode. Без оборудования — эмуляторы ККТ, терминала, весов и принтера.
Принципы
Операции
Всё, что меняет состояние устройства, — операция: POST возвращает её снимок {id, type, status, stage, result, error, warnings}. status: QUEUED → RUNNING → SUCCEEDED или FAILED; UNKNOWN — агент перезапустился или устройство не ответило, проверьте результат на устройстве. На одном устройстве операции идут по очереди, на разных — параллельно.
Повтор запросов
Каждый POST с операцией несёт Idempotency-Key — например, UUID на одно действие кассира. Повтор с тем же ключом возвращает ту же операцию и не проводит оплату или чек второй раз; тот же ключ для другой операции — IDEMPOTENCY_KEY_REUSED.
Ожидание
Prefer: wait=30 — подождать результат до 30 секунд (не больше 180): 200, если операция закончилась, иначе 202 и Location операции — спросить GET /api/v1/operations/{id} или ждать события.
События
GET /api/v1/events — Server-Sent Events: operation при каждом изменении операции, barcode — код со сканера {deviceId, code, at}, card — карта на считывателе, display — строки на втором мониторе, qr — QR для оплаты по СБП (payload: null — убрать), power — питание {source: AC|BATTERY, batteryPercent, minutesLeft}.
Таймауты
Операция ждёт устройство не дольше предела: ККТ — 120 с, терминал — 300 с, чек с оплатой картой — 420 с, принтеры — 120 с, весы, дисплеи и ящик — 60 с (очередь к устройству не считается). Меняются на странице агента, в hw.operations.timeouts или для одного запроса заголовком X-HW-Timeout: 30.
Настройка
Методы /api/v1/setup/… обслуживают страницу агента и доступны только с неё; в этом описании их нет. Устройства, принтеры, кассира и разрешённые сайты настраивают на странице агента или в его файле настроек — см. справку.
Продажа
- 1Одной операцией
POST /api/v1/checkouts— карта → чек → слип; чек не вышел — оплата отменяется сама
- 2
- 3
Чек
{
"type": "SELL", // SELL, SELL_RETURN, BUY, BUY_RETURN
"taxation": "USN_INCOME", // OSN, USN_INCOME, USN_INCOME_OUTCOME, ESHN, PATENT; нет — из «Рабочего места» или СНО ККТ
"operator": {"name": "Иванова И.И.", "inn": "770123456789"}, // нет — кассир из «Рабочего места»
"customer": {"contact": "+79991234567"}, // для электронного чека
"header": [
{"kind": "TEXT", "text": "Заказ 123", "align": "CENTER"},
{"kind": "PAIR", "text": "Дата:", "right": "01.11.2026 19:00"},
{"kind": "SEPARATOR"}
],
"items": [
{"name": "Услуга", "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 — не печатать, отправить покупателю
"senderEmail": "kassa@example.ru", // тег 1117; нет — из «Рабочего места»
"settlementPlace": "Касса" // тег 1187; нет — из «Рабочего места»
}Сумма оплат должна быть равна сумме позиций, стоимость позиции — цене × количество. Строки текста переносятся по ширине ленты ККТ автоматически. Поля — модель Receipt.
Примеры
Продажа с оплатой картой — оплата, чек и слип одной операцией. Ответ — операция с result.receipt (номер ФД, ФП, смена, QR-код) и result.payment (paymentRef для возврата, карта, RRN, код авторизации, слип).
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}PDF на принтер билетов — принтер по назначению (role), заданному на странице агента:
POST /api/v1/print-jobs
Idempotency-Key: 7b0e…
{"urls": ["https://example.com/tickets/1.pdf"], "role": "tickets", "copies": 1}Команды принтера как есть — ESC/POS, ZPL; например, этикетка ZPL:
POST /api/v1/print-jobs
Idempotency-Key: 9c41…
{"raw": "XlhBXkZPNTAsNTBeQTBOLDUwXkZESGVsbG9eRlNeWFo=", "printer": "Zebra ZD220"}Ход операции и сканер в браузере:
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); // «Приложите карту к терминалу»
});
events.addEventListener('barcode', e => console.log(JSON.parse(e.data).code));Готовые клиенты — SDK для JavaScript/TypeScript, Java и C# в репозитории агента (папка sdk), см. справку.