Universal Tool Calling Protocol · 1.0.1

UTCP облака

Те же инструменты, что у MCP облака, но без промежуточного сервера: агент ИИ читает руководство UTCP и сам вызывает API облака по готовым шаблонам запросов — с вашим ключом, напрямую.

Руководство: https://cloud.hw-connector.ru/utcpКлюч: X-Api-Key ← ${HW_CLOUD_API_KEY}

Подключить Инструменты MCP

UTCP или MCP

MCP	Клиент ходит на сервер MCP облака (`…/mcp`), тот вызывает API за него. Вход OAuth через кабинет — для claude.ai, Claude Desktop/Code, Cursor. См. MCP облака.
UTCP	Клиент один раз читает руководство (`/utcp`, без ключа), дальше сам шлёт обычные HTTP-запросы в API облака с ключом `X-Api-Key`. Посредника нет: те же адреса, ответы, ошибки и журнал, что у API; работает в своих агентах на Python и TypeScript.

Подключение

Нужен ключ API аккаунта hwk_…: кабинет hw-connector.ru → «Облако» → «Ключи». Для ИИ лучше «только чтение» — тогда инструменты с операциями ответят KEY_READ_ONLY. Ключ — в переменную клиента HW_CLOUD_API_KEY (некоторые клиенты добавляют к имени переменной приставку с именем руководства — см. их документацию).

Python

# pip install utcp utcp-http
import asyncio
from utcp.utcp_client import UtcpClient

async def main():
    client = await UtcpClient.create(config={
        "manual_call_templates": [{
            "name": "hw_cloud",
            "call_template_type": "http",
            "url": "https://cloud.hw-connector.ru/utcp",
            "http_method": "GET"
        }],
        "variables": {"HW_CLOUD_API_KEY": "hwk_…"}
    })
    tools = await client.search_tools("тревоги касс")
    print(await client.call_tool("hw_cloud.get_summary", {}))

asyncio.run(main())

TypeScript

shell

npm install @utcp/core @utcp/http
# руководство подключается так же: name hw_cloud, call_template_type http, url ниже, переменная HW_CLOUD_API_KEY

Пример клиента — в документации UTCP: utcp.io.

Само руководство

curl

curl -s https://cloud.hw-connector.ru/utcp            # руководство: без ключа
curl -s 'https://cloud.hw-connector.ru/utcp?lang=en'  # по-английски

Шаблон каждого инструмента — call_template_type: http: адрес с параметрами пути ({id}), метод, тело — вход body_field, остальные входы — строка запроса; ключ — auth типа api_key в заголовке X-Api-Key. Ответы и коды ошибок — как в API облака.

Инструменты

Те же, что у MCP облака (описания одни): помечены «только чтение», «меняет запись в облаке» и «операция на кассе».

`get_summary`#

GEThttps://cloud.hw-connector.ru/api/v1/summary

Только чтение

Сводка аккаунта. Состояние парка одним запросом: сколько касс всего, на связи, не на связи и выключено; версии агента; открытые тревоги по кодам и сколько критичных; запросы к агентам за сутки и сколько неудачных. Начните с него.

Без входов.

`list_devices`#

GEThttps://cloud.hw-connector.ru/api/v1/devices

Только чтение

Кассы аккаунта. Список касс (рабочих мест с HW agent): номер, название от агента и своё (label), версия агента, на связи ли сейчас, когда была на связи, выключена ли, сколько открытых тревог.

Входы

onlineboolean
true — только на связи, false — только не на связи
qstring
Часть названия, своего названия или номера установки
limitinteger
Сколько вернуть (1–1000, по умолчанию 100)
offsetinteger
Сколько пропустить

`get_device`#

GEThttps://cloud.hw-connector.ru/api/v1/devices/{id}

Только чтение

Карточка кассы. Всё о кассе: на связи ли, версия агента, ОС, последние значения метрик за 7 дней (смена, ФН, ОФД, принтеры), открытые тревоги и последние события.

Входы

idintegerобязательный
Номер кассы из list_devices
eventsinteger
Сколько последних событий (1–500, по умолчанию 20)

`list_device_statuses`#

GEThttps://cloud.hw-connector.ru/api/v1/devices/status

Только чтение

Устройства на рабочих местах. Последнее известное состояние устройств на рабочих местах: включено ли, у ККТ — смена открыта или просрочена, отвечает ли, дней до конца ФН, не передано в ОФД; принтеры — состояние и причины («нет бумаги»). По данным агента раз в минуту (ККТ — раз в 10 минут), at — когда пришли. Что устройство делает прямо сейчас — call_agent GET /api/v1/operations.

Входы

deviceIdinteger
Только эта касса

`update_device`#

PATCHhttps://cloud.hw-connector.ru/api/v1/devices/{id}

Меняет запись в облаке

Переименовать или выключить кассу. Своё название кассы (агент его не затирает; пустая строка — снова как у агента) и выключатель: выключенной кассе облако не передаёт команды, запросы к агенту и чеки. Меняет только запись в облаке, не кассу.

Тело запроса — вход patch.

Входы

idintegerобязательный
Номер кассы
patchobject
Тело запроса (JSON)
- patch.labelstring
  Своё название
- patch.disabledboolean
  true — выключить, false — включить

`list_alerts`#

GEThttps://cloud.hw-connector.ru/api/v1/alerts

Только чтение

Тревоги касс. Тревоги: FN_EXPIRING (ФН скоро закончится), OFD_BACKLOG (документы не уходят в ОФД), SHIFT_EXPIRED (смена больше 24 ч), REGISTER_UNAVAILABLE (ККТ не отвечает), DEVICE_OFFLINE (касса пропала). Открываются и закрываются сами; по умолчанию — только открытые.

Входы

openboolean
true — только открытые (по умолчанию), false — и закрытые
deviceIdinteger
Только эта касса
codestring
Только этот код
severitystring
WARNING или CRITICAL

`list_events`#

GEThttps://cloud.hw-connector.ru/api/v1/events

Только чтение

События касс. События касс аккаунта, свежие сверху: operation.failed (неудачная операция с кодом ошибки), printer (состояние принтера), power (питание), register.unavailable (ККТ не отвечает).

Входы

deviceIdinteger
Только эта касса
typestring
Тип события
sincestring
Не раньше этого времени, ISO 8601
limitinteger
Сколько вернуть (1–1000, по умолчанию 50)
offsetinteger
Сколько пропустить

`get_latest_metric`#

GEThttps://cloud.hw-connector.ru/api/v1/metrics/latest

Только чтение

Метрика по кассам. Последнее значение одной метрики на каждой кассе за 7 дней: fn.days_left (дней до конца ФН), ofd.not_sent (не передано в ОФД), ofd.oldest_hours, shift.open, shift.expired, register.ok, agent.up, devices.active.

Входы

namestringобязательный
Имя метрики, например fn.days_left
deviceIdinteger
Только эта касса

`list_requests`#

GEThttps://cloud.hw-connector.ru/api/v1/requests

Только чтение

Журнал запросов к агентам. Запросы к API агентов через облако (call_agent, прокси, команды): касса, метод, путь, код ответа, ошибка облака (NOT_CONNECTED, TIMEOUT…), время. Тела не хранятся.

Входы

deviceIdinteger
Только эта касса
failedboolean
Только неудачные
limitinteger
Сколько вернуть (по умолчанию 50)
offsetinteger
Сколько пропустить

`call_agent`#

POSThttps://cloud.hw-connector.ru/api/v1/devices/{id}/commands

Операция на кассе

Запрос к API агента на кассе. Выполнить запрос к API HW agent на кассе (как локально на http://localhost:7790): например GET /api/v1/devices — устройства, GET /api/v1/registers/1/shift — смена, POST /api/v1/registers/1/reports/x — X-отчёт. Операции (POST) реально выполняются на кассе: печать, чеки, оплата — только по прямой просьбе пользователя и с idempotency_key (повтор с тем же ключом не выполнит операцию дважды). Настройка устройств (/api/v1/setup) недоступна. Описание API агента — https://hw-connector.ru/docs/api/agent/

Тело запроса — вход command.

Входы

idintegerобязательный
Номер кассы
commandobjectобязательный
Тело запроса (JSON)
- command.methodstringобязательный
  Метод HTTP
  значения: GET POST PUT DELETE PATCH
- command.pathstringобязательный
  Путь в API агента со строкой запроса, /api/v1/...
- command.bodyobject
  Тело JSON
- command.idempotencyKeystring
  Ключ идемпотентности операции

`create_receipt`#

POSThttps://cloud.hw-connector.ru/api/v1/receipts

Операция на кассе

Пробить чек через облако. Чек на кассе аккаунта с очередью: касса не на связи — чек ждёт и уйдёт, когда она появится. receipt — как в API агента (type, items, payments…). Тот же idempotency_key вернёт тот же чек, второй раз не пробьёт. Настоящий фискальный чек — только по прямой просьбе пользователя.

Тело запроса — вход request.

Входы

requestobjectобязательный
Тело запроса (JSON)
- request.idempotencyKeystringобязательный
  Ключ идемпотентности, например номер заказа
- request.receiptobjectобязательный
  Чек: type, items, payments…
- request.deviceIdinteger
  Касса; нет — любая на связи
- request.registerinteger
  Номер ККТ на кассе (по умолчанию 1)
- request.callbackUrlstring
  Куда прислать итог (вебхук)

`get_receipt`#

GEThttps://cloud.hw-connector.ru/api/v1/receipts/{id}

Только чтение

Чек. Чек, отправленный через облако: статус (QUEUED, SENDING, DONE, FAILED, UNKNOWN, EXPIRED), ФД, ФП, ссылка на чек, ошибка.

Входы

idintegerобязательный
Номер чека

`list_receipts`#

GEThttps://cloud.hw-connector.ru/api/v1/receipts

Только чтение

Последние чеки. Чеки через облако, свежие сверху; idempotency_key — найти чек по своему ключу.

Входы

deviceIdinteger
Только эта касса
idempotencyKeystring
Ключ идемпотентности
limitinteger
Сколько (по умолчанию 20)

`receipts_stats`#

GEThttps://cloud.hw-connector.ru/api/v1/receipts/stats

Только чтение

Учёт чеков за месяц. Сколько чеков и на какую сумму пробила каждая касса за месяц, тариф и пробный лимит.

Входы

monthstring
Месяц ГГГГ-ММ; нет — текущий

Безопасность

call_agent и create_receipt выполняют настоящие операции на кассе: печать, фискальный чек, оплату. Агент ИИ должен спрашивать подтверждение перед ними; для наблюдения за парком хватит ключа «только чтение».
Ключ хранится у клиента (переменная, файл .env) и уходит только в API облака. Отозвать — кабинет → «Облако» → «Ключи». Каждый запрос к агентам — в журнале GET /api/v1/requests; лимит — 600 запросов в минуту на аккаунт.
Настройку устройств (/api/v1/setup) облако не передаёт; выключенной кассе (update_device) ничего не уходит.

UTCP облака

UTCP или MCP

Подключение

Python

TypeScript

Само руководство

Инструменты

get_summary#

list_devices#

get_device#

list_device_statuses#

update_device#

list_alerts#

list_events#

get_latest_metric#

list_requests#

call_agent#

create_receipt#

get_receipt#

list_receipts#

receipts_stats#

Безопасность

`get_summary`#

`list_devices`#

`get_device`#

`list_device_statuses`#

`update_device`#

`list_alerts`#

`list_events`#

`get_latest_metric`#

`list_requests`#

`call_agent`#

`create_receipt`#

`get_receipt`#

`list_receipts`#

`receipts_stats`#