Контекст подключения
Все операции. Авторизация. Запросы и повторы.
Все пути в этом файле дополняют /api/v1 на домене организации.
Описание и ограничения
Назначение
Позволяет интегратору узнать организацию, сотрудника и доступные операции без чтения секретов или внутренних настроек.
Поля и назначение
| Публичное поле | Формат и смысл | Доступ |
|---|---|---|
organization_id |
строка, организация | только чтение |
user_id |
id, сотрудник |
только чтение |
client_id |
opaque id, подключение |
только чтение |
scopes |
массив строк | только чтение |
workshop_ids |
массив of id |
только чтение |
features |
объект of логическое значение | только чтение |
api_version |
строка | только чтение |
timezone, currency, locale |
IANA timezone, ISO 4217 currency, код языка |
только чтение |
access |
status: active/trial/subscription_inactive/api_disabled/plan_unavailable; trial_ends_at и subscription_ends_at — дата и время/null |
только чтение |
Обязательность и null указаны в схемах каждой операции ниже.
Доступ и выборка
Любой действующий персональный API-токен. Список прав отражает фактические ограничения сотрудника и тарифа, а не все abilities, когда-либо записанные в токен.
GET /context остаётся доступен действующему токену при завершении подписки или отключении API, чтобы интеграция могла определить причину остановки. Секрет отозван/истёк или сотрудник отключён — 401, включая context. timezone применяется к HH:mm и сохранённым datetime дополнительных полей без собственного смещения, currency — к денежным объектам; страна или домен не используются для угадывания этих значений. Правило неоднозначных и несуществующих локальных дат описано в custom-fields.md.
На платном тарифе ниже «Энтерпрайз» context возвращает status=plan_unavailable, features.public_api=false и разрешения подключения=[]. Бизнес-маршруты и записи об операции при этом закрыты. На «Энтерпрайз», «Энтерпрайз Про» и действующем пробном периоде features.public_api=true только при включённом API. Диагностика не выдаёт доступ к данным модулей.
Правила и связи
- GET не обновляет настройки, тариф или данные организации.
- Ключ, хеш токена, пароли и конфигурации провайдеров не входят в ответ.
Операции
| Метод | Путь | Назначение |
|---|---|---|
| GET | /context |
Организация, сотрудник и возможности текущего подключения |
GET /context
Организация, сотрудник и возможности текущего подключения.
Доступ. Действующий персональный Bearer; диагностический контекст доступен и при закрытом доступе к данным. Дополнительно действуют доступ к записям, мастерским, модулям и условия полей из описания ресурса выше.
Параметры
| Имя | Где | Тип | Обязательно | null | Ограничения |
|---|---|---|---|---|---|
Authorization |
заголовок | строка | да | нет | Bearer <SERVICEAPP_TOKEN> |
Ответы
| HTTP | Назначение и схема |
|---|---|
| 200 | Успех. Полная схема и пример |
| 401 | Требуется действующий Bearer. Коды и формат ошибки |
| 429 | Лимит запросов, Retry-After. Коды и формат ошибки |
| 503 | Временно недоступно. Коды и формат ошибки |
Каждый ответ содержит новый X-Request-Id в заголовке. Общие транспортные отказы и правила повтора действуют также при отказе до контроллера; см. ошибки.
Пример запроса
Запускается из каталога комплекта после настройки переменных в быстром старте. Замените демонстрационные идентификаторы 101 и UUID идентификаторами доступных записей. $RESOURCE_VERSION берётся из GET владельца версии, описанного выше. Для нового действия сохраните новый ключ; для повтора используйте прежний.
curl --silent --show-error --globoff \
"$API/context" \
--header "Authorization: Bearer $SERVICEAPP_TOKEN" \
--header "Accept: application/json"