Through the cloud

Address and key

The base address is https://cloud.hw-connector.ru/agent instead of http://localhost:7790, everything else is unchanged. Instead of the agent token — the account API key X-Api-Key: hwk_… from the hw-connector.ru cabinet (Cloud section), the register — X-Device-Id.

# locally
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

# through the cloud: another address and two headers
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

// The agent JS SDK (on a server, Node 18+): another address and two headers via a custom 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();   // as with the agent on this computer

• X-Device-Id — the register number from GET https://cloud.hw-connector.ru/api/v1/devices (same X-Api-Key). If the account has one register it may be omitted; X-Device-Machine-Id — the agent installation id (GET /api/v1/system/computer) works instead. The register number comes back in the X-Device-Id response header.
• A register of another account — 404. The cloud does not pass Authorization to the agent: the agent calls itself with its own token.
• Account registers, who is online, alerts, events, own name and on/off switch of a register — the Cloud API with the same key.
• Cloud commands can be switched off on the register (hw.cloud.allow-commands: false) — then the agent answers 403 COMMANDS_DISABLED.

What is passed

Waiting and retries

• The cloud waits up to 60 s for the register. Prefer: wait=N is passed to the agent but capped at 55 s: if the operation is not done — 202 and Location: /agent/api/v1/operations/{id}, ask for the result through the same proxy. Without Prefer — as locally.
• POST, PUT, DELETE, PATCH without Idempotency-Key — the cloud creates a px-… key and returns it in the Idempotency-Key response header (on errors too). After 504 or 502 retry with that key — the operation never runs twice.
• The register is offline — 503 at once: requests are not queued (a print an hour later helps nobody). Guaranteed receipt delivery “when the register shows up” — POST https://cloud.hw-connector.ru/api/v1/receipts (queue, webhook).
• Any method, files and headers — agent 2.14.0 and later; older agents take only GET and POST with JSON through the cloud, the rest — 501 AGENT_OUTDATED.

Cloud errors

Cloud answers differ from agent answers by the X-Hw-Proxy-Error header (agent answers never have it); the body is problem+json with the same code.