Сервер, CRM, бот

Через облако

Тот же API агента — с вашего сервера, без браузера на месте: облако hw-cloud передаёт запрос кассе по её исходящему соединению (касса за NAT, входящие порты не нужны). Путь, метод, тело и ответ — как у агента, в том числе картинки и PDF.

Адрес и ключ

Базовый адрес — https://cloud.hw-connector.ru/agent вместо http://localhost:7790, остальное без изменений. Вместо токена агента — ключ API аккаунта X-Api-Key: hwk_… из кабинета hw-connector.ru (раздел «Облако»), касса — X-Device-Id.

curl

# локально
curl -X POST 'http://localhost:7790/api/v1/registers/1/receipts' \
  -H 'Idempotency-Key: order-123' -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' --data @receipt.json

# через облако: другой адрес и два заголовка
curl -X POST 'https://cloud.hw-connector.ru/agent/api/v1/registers/1/receipts' \
  -H 'X-Api-Key: hwk_…' -H 'X-Device-Id: 42' \
  -H 'Idempotency-Key: order-123' -H 'Prefer: wait=30' \
  -H 'Content-Type: application/json' --data @receipt.json

JavaScript

// JS SDK агента (на сервере, Node 18+): другой адрес и два заголовка через свой fetch
const hw = new HwConnector({
  baseUrl: 'https://cloud.hw-connector.ru/agent',
  fetch: (url, init = {}) => fetch(url, { ...init, headers: { ...init.headers, 'X-Api-Key': 'hwk_…', 'X-Device-Id': '42' } }),
});
const devices = await hw.devices();   // как с агентом на этом компьютере

X-Device-Id — номер кассы из GET https://cloud.hw-connector.ru/api/v1/devices (тот же X-Api-Key). У аккаунта одна касса — можно не передавать; вместо него можно X-Device-Machine-Id — постоянный номер установки агента (GET /api/v1/system/computer). Номер кассы возвращается в ответном X-Device-Id.
Касса чужого аккаунта — 404. Ключ агента (Authorization) облако агенту не передаёт: агент вызывает себя своим токеном.
Кассы аккаунта, кто на связи, тревоги, события, своё название и выключатель кассы — API облака с тем же ключом.
На кассе команды из облака можно выключить (hw.cloud.allow-commands: false) — тогда агент отвечает 403 COMMANDS_DISABLED.

Что передаётся

Методы	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`; строка запроса — как есть
Тело	JSON или файл, до 10 МБ (больше — `413`)
Заголовки агенту	`Prefer`, `Accept-Language`, `Content-Type`, `Accept`, `Idempotency-Key` (с приставкой `cloud:`)
Ответ	код и тело агента как есть (картинки, PDF тоже); заголовки `Content-Type`, `Location` (`/api/v1/…` → `/agent/api/v1/…`), `Retry-After`, `Preference-Applied`, `Content-Disposition`
Закрыто	`/api/v1/setup/**` — `403`; пути с `..`, `//` — `400`
Лимит	600 запросов в минуту на аккаунт, сверх — `429` и `Retry-After`

Ожидание и повтор

Облако ждёт ответ кассы до 60 с. Prefer: wait=N передаётся агенту, но не больше 55 с: не успела операция — 202 и Location: /agent/api/v1/operations/{id}, итог спросите через тот же прокси. Без Prefer — как локально.
POST, PUT, DELETE, PATCH без Idempotency-Key — облако создаёт ключ px-… и возвращает его в ответном Idempotency-Key (и при ошибке). После 504 или 502 повторите запрос с этим ключом — операция не выполнится дважды.
Касса не на связи — сразу 503: запросы не копятся (печать через час никому не нужна). Гарантированная доставка чека «когда касса появится» — POST https://cloud.hw-connector.ru/api/v1/receipts (очередь, вебхук).
Любой метод, файлы и заголовки — агент 2.14.0 и новее; старые агенты принимают через облако только GET и POST с JSON, остальное — 501 AGENT_OUTDATED.

Ошибки облака

Ответы облака отличаются от ответов агента заголовком X-Hw-Proxy-Error (у ответов агента его нет); тело — problem+json с тем же code.

HTTP	X-Hw-Proxy-Error	Когда и что делать
401	`UNAUTHORIZED`	Нет или неверный X-Api-Key
400	`DEVICE_REQUIRED`	У аккаунта несколько касс, а X-Device-Id не передан
400	`BAD_DEVICE_ID`	X-Device-Id — не число
400	`BAD_PATH`	Путь с «..», «//» или закодированными косыми чертами
404	`DEVICE_NOT_FOUND`	Касса не найдена или принадлежит другому аккаунту
403	`KEY_READ_ONLY`	Ключ «только чтение»: к агенту — только GET
403	`DEVICE_DISABLED`	Касса выключена в аккаунте (`PATCH /api/v1/devices/{id}`)
403	`SETUP_FORBIDDEN`	`/api/v1/setup`/** через облако закрыт — настройка только на кассе
405	`METHOD_NOT_ALLOWED`	Метод кроме GET, POST, PUT, DELETE, PATCH
413	`BODY_TOO_LARGE`	Тело больше 10 МБ
429	`RATE_LIMITED`	Лимит запросов аккаунта — подождите Retry-After
501	`AGENT_OUTDATED`	Агент на кассе старше 2.14.0: через облако ему доступны только GET и POST с JSON
503	`NOT_CONNECTED`	Касса не на связи с облаком; Retry-After — когда повторить
504	`TIMEOUT`	Касса не ответила за 60 с — повторите с тем же Idempotency-Key или спросите /operations/{id}
502	`CONNECTION_LOST`	Связь с кассой оборвалась посреди запроса — как 504
502	`RELAY_ERROR`	Ошибка облака при доставке — как 504