API облака

Как начать

1. 1
   Ключ. Кабинет hw-connector.ru → «Облако» → ключ API hwk_… (показывается один раз): полный или только чтение — всё GET, а изменения касс, команды, прокси (кроме GET) и чеки — KEY_READ_ONLY. Ключ видит только кассы своего аккаунта: чужая касса — DEVICE_NOT_FOUND. Кассы подключаются к облаку токеном подключения hwe_… из того же раздела.
2. 2
   Кассы. GET /api/v1/devices — номера касс; номер нужен остальным методам и прокси агента (X-Device-Id).
3. 3
   Формат. JSON; даты — ISO 8601; суммы — копейки. Списки — limit и offset, всего — в заголовке X-Total-Count. Ошибки — problem+json с полем code.

curl 'https://cloud.hw-connector.ru/api/v1/summary' -H 'X-Api-Key: hwk_…'

curl 'https://cloud.hw-connector.ru/api/v1/devices?online=false&limit=50' -H 'X-Api-Key: hwk_…'

curl -X PATCH 'https://cloud.hw-connector.ru/api/v1/devices/42' -H 'X-Api-Key: hwk_…' \
  -H 'Content-Type: application/json' --data '{"label": "Касса 2, фойе"}'

Мониторинг парка

• GET /api/v1/summary — сколько касс на связи и выключено, версии агента, открытые тревоги по кодам, запросы к агентам за сутки.
• GET /api/v1/alerts — тревоги: FN_EXPIRING, OFD_BACKLOG, SHIFT_EXPIRED, REGISTER_UNAVAILABLE, DEVICE_OFFLINE; открываются и закрываются сами, их же облако шлёт вебхуком.
• GET /api/v1/metrics/latest — одна метрика по всем кассам: fn.days_left (дней до конца ФН), ofd.not_sent, shift.open, register.ok.
• GET /api/v1/events — неудачные операции, принтеры, питание. GET /api/v1/devices/{id} — всё о кассе одним запросом.

Управление

• PATCH /api/v1/devices/{id} — своё название кассы (агент его не затирает) и выключатель: выключенной кассе команды, прокси и чеки не передаются.
• Любой запрос к API агента на кассе — прокси https://cloud.hw-connector.ru/agent/api/v1/… с X-Device-Id (API агента → Через облако) или POST /api/v1/devices/{id}/commands «конвертом». Журнал — GET /api/v1/requests.
• Чек на кассе аккаунта с очередью и вебхуком — POST /api/v1/receipts.
• Настройку устройств (/api/v1/setup) облако не передаёт: её делают на кассе.

MCP облака

Тот же API для ИИ-помощника: MCP-сервер облака https://cloud.hw-connector.ru/mcp с тем же ключом — Claude, Cursor и другие MCP-клиенты смотрят состояние парка, разбирают тревоги и шлют команды кассам. Подключение и инструменты — MCP облака.

Разделы API