Общие сведения об API¶

Назначение¶

LocalHub Robot API — публичный API для автоматизации действий пользователя и подключения внешних интеграций к платформе LocalHub.

Пользователь создаёт программного агента («робота»), назначает ему ограниченный набор разрешений и использует токен для выполнения доступных операций от имени своего аккаунта.

Robot API подходит для:

внешних интеграций;
автоматизации рабочих сценариев;
получения доступных пользователю данных;
сервисных сценариев и скриптов автоматизации;
пользовательских инструментов поверх платформы.

Базовый адрес¶

https://robot.prod.lclhub.ru/v1

Все методы текущей версии API публикуются под префиксом /v1/.

Модель доступа¶

Доступ к API строится вокруг объекта Robot.

Robot¶

Robot — агент, созданный пользователем в своём аккаунте LocalHub. Робот действует от имени аккаунта-владельца, но только в пределах выданных ему разрешений.

У каждого робота есть:

имя;
набор разрешений (scope);
один или несколько токенов доступа;
лимиты на использование API.

Token¶

Токен — секрет, которым клиент авторизуется при каждом запросе. Токен имеет вид lhrk_<секретная-часть> и передаётся в заголовке:

Authorization: Bearer lhrk_XjN4QBuhBiocsSEr4hCQdYUI...

Токен:

связан с конкретным роботом и аккаунтом;
действует строго в пределах прав этого робота;
показывается полностью только один раз при выпуске;
не может быть просмотрен повторно после закрытия окна выпуска.

Если токен утрачен, отзовите его и выпустите новый.

Scope / Permissions¶

Роботу назначаются разрешения (scope), которые определяют доступные методы API. Без нужного scope метод вернёт 403 permission_denied.

Доступные scopes:

Scope	Что разрешает
`account.read`	чтение информации об аккаунте
`chats.read`	чтение списка чатов и обновлений

Новые scopes будут публиковаться в документации по мере появления соответствующих методов в публичном API.

Доступные методы¶

Робот¶

GET /v1/robot — получить информацию о текущем роботе и токене: имя, scopes, состояние, префикс токена и срок действия. Достаточно авторизации токеном.
GET /v1/robot/limits — получить текущее состояние лимитов по всем окнам: минута, час, сутки и месяц.

Аккаунт¶

GET /v1/account — профиль аккаунта, к которому привязан робот: имя пользователя, отображаемое имя, описание, аватар, статус верификации и дата создания. Персональные контактные данные и закрытые сведения аккаунта не возвращаются.

Требуемый scope: account.read.

Чаты¶

Робот может читать список доступных аккаунту групповых чатов и получать новые сообщения и события из тех чатов, на которые подписался. Чат доступен роботу, если владелец-аккаунт либо имеет право добавлять администраторов в этот чат, либо является создателем чата.

GET /v1/chats — список групповых чатов, в которых владелец-аккаунт имеет право добавлять администраторов или является создателем чата.
POST /v1/chats/{chat_id}/subscribe — подписать робота на обновления конкретного чата.
DELETE /v1/chats/{chat_id}/subscribe — отписаться от чата. После отписки неподтверждённые обновления по этому чату больше не возвращаются роботу.
GET /v1/chats/subscriptions — список активных подписок робота.
POST /v1/chats/updates — получение новых сообщений и событий чата: новое сообщение, вход или выход участника. Клиент передаёт offset для подтверждения уже обработанных обновлений и опрашивает endpoint с интервалом.

Все методы группы требуют scope chats.read. Подписка действует с момента создания: сообщения, отправленные в чат до подписки, в обновления не попадают. Если владелец-аккаунт не является создателем чата и не имеет права добавлять администраторов, этот чат недоступен ни в списке, ни для подписки.

На текущей стадии проекта действует ограничение «один чат — один робот»: к одному чату может быть привязан не более одного робота.

Подробное описание контракта, структуры обновлений и шаблонов цикла получения событий приведено в разделе Чаты.

Авторизация¶

Каждый запрос должен содержать заголовок Authorization с токеном робота:

Authorization: Bearer lhrk_XjN4QBuhBiocsSEr4hCQdYUI...

Если заголовок отсутствует, токен невалиден, отозван или истёк, API возвращает 401.

Если у робота нет требуемого scope, API возвращает 403 permission_denied с указанием недостающего scope в details.required_scope.

Ограничения по количеству¶

Для аккаунта и токенов действуют ограничения на количество активных объектов. Эти ограничения относятся к жизненному циклу роботов и токенов и не связаны с rate limits на запросы.

Роботы¶

На одном аккаунте может быть не более 3 активных роботов.

Активным считается робот в состоянии active. Роботы в состоянии disabled не занимают слот. Чтобы создать ещё одного робота, отключите одного из существующих активных роботов.

Токены¶

У одного робота может быть не более 3 активных токенов.

Активным считается токен, который не отозван и не истёк. Истёкшие и отозванные токены не занимают слот; место освобождается сразу после истечения срока действия или отзыва токена.

Лимиты¶

Для каждого робота действуют четыре одновременных бюджета запросов:

в минуту;
в час;
в сутки;
в месяц.

Текущее остающееся значение по каждому окну приходит в заголовках ответа X-RateLimit-Remaining-*. При исчерпании любого из бюджетов API возвращает 429 с заголовком Retry-After. Клиент должен подождать указанное число секунд и повторить запрос.

Дополнительно действует общий лимит на запросы по IP-адресу клиента — независимо от наличия токена. При превышении API возвращает 429 rate_limit_exceeded с заголовком Retry-After.

Ошибки¶

Все ошибки имеют единый JSON-формат:

{
  "error": {
    "code": "permission_denied",
    "message": "Robot is not permitted to perform this action.",
    "request_id": "req_a1b2c3d4...",
    "details": { "required_scope": "chats.read" }
  }
}

code — машинно-читаемый код ошибки.
message — короткое человекочитаемое описание.
request_id — идентификатор запроса для диагностики.
details — дополнительные сведения, если они применимы к ошибке.

request_id также возвращается в заголовке X-Request-ID. Если клиент передал X-Request-ID в запросе, API возвращает это значение обратно.

Для подписки на чат дополнительно используется ошибка 409 chat_already_subscribed: чат уже привязан к другому роботу.

Версионирование¶

В рамках одной major-версии API контракт не ломается:

существующие поля ответа не удаляются и не меняют смысл;
новые поля могут появляться, поэтому клиент должен игнорировать неизвестные поля;
новые опциональные параметры запроса могут добавляться.

Ломающие изменения публикуются под новой версией (/v2/). Для предыдущей major-версии заранее объявляется период поддержки и график вывода из эксплуатации.

Принципы публичного контракта¶

Robot API спроектирован как:

явный — поведение методов, права, ошибки и лимиты задокументированы;
стабильный — контракт не меняется без предупреждения;
версионируемый — ломающие изменения выходят под новой major-версией;
безопасный — робот не получает больше полномочий, чем ему выдал владелец;
предсказуемый — ошибки, лимиты и права работают единообразно.