Через облако

Адрес и ключ

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

# локально
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

// 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) облако агенту не передаёт: агент вызывает себя своим токеном.
• На кассе команды из облака можно выключить (hw.cloud.allow-commands: false) — тогда агент отвечает 403 COMMANDS_DISABLED.

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

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

• Облако ждёт ответ кассы до 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.