Cloud API

Getting started

1. 1
   Key. hw-connector.ru cabinet → Cloud → API key hwk_… (shown once): full or read-only — all GET, while register changes, commands, the proxy (except GET) and receipts — KEY_READ_ONLY. A key sees only its account's registers: another account's register — DEVICE_NOT_FOUND. Registers join the cloud with an enrollment token hwe_… from the same section.
2. 2
   Registers. GET /api/v1/devices — register numbers; the other methods and the agent proxy (X-Device-Id) need them.
3. 3
   Format. JSON; dates — ISO 8601; amounts — kopecks. Lists — limit and offset, total — in the X-Total-Count header. Errors — problem+json with a code field.

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": "Till 2, foyer"}'

Fleet monitoring

• GET /api/v1/summary — how many registers are online and disabled, agent versions, open alerts by code, agent requests in the last day.
• GET /api/v1/alerts — alerts: FN_EXPIRING, OFD_BACKLOG, SHIFT_EXPIRED, REGISTER_UNAVAILABLE, DEVICE_OFFLINE; they open and close by themselves, the cloud also sends them by webhook.
• GET /api/v1/metrics/latest — one metric across registers: fn.days_left (days to fiscal drive end), ofd.not_sent, shift.open, register.ok.
• GET /api/v1/events — failed operations, printers, power. GET /api/v1/devices/{id} — everything about a register in one request.

Management

• PATCH /api/v1/devices/{id} — own register name (the agent does not overwrite it) and an on/off switch: a disabled register gets no commands, proxy requests or receipts.
• Any request to the agent API on a register — the https://cloud.hw-connector.ru/agent/api/v1/… proxy with X-Device-Id (Agent API → Through the cloud) or POST /api/v1/devices/{id}/commands in an envelope. The log — GET /api/v1/requests.
• A receipt on an account register with a queue and a webhook — POST /api/v1/receipts.
• The cloud does not pass device setup (/api/v1/setup): it is done on the register.

Cloud MCP

The same API for an AI assistant: the cloud MCP server https://cloud.hw-connector.ru/mcp with the same key — Claude, Cursor and other MCP clients check the fleet state, investigate alerts and send commands to registers. Connecting and tools — Cloud MCP.

API sections