Перейти к основному содержимому

Песочница

Песочница — отдельная организация api-sandbox на стенде Shtab с доступом из интернета. В ней можно вызвать интеграционный API раньше, чем у вас появится своя установка, и попробовать запросы прямо со страницы справочника.

Адрес APIhttps://helpdesk.shtab.io
Выдача токенаhttps://helpdesk-sso.shtab.io/realms/helpdesk/protocol/openid-connect/token
Организацияapi-sandbox, только тестовые данные

Доступ​

Сервисный аккаунт песочницы Shtab выдаёт по запросу. В ответ приходят client_id и секрет клиента, роль — «Интеграция» (integration_sa, роли); другую роль можно попросить в том же запросе.

  • Секрет передаётся вне почты и задач, например через менеджер паролей. Не кладите его в репозиторий, код и логи.
  • Аккаунт выдаётся на срок и действует только в организации песочницы: ни одна другая организация стенда по нему не открывается.
  • Узнав об утечке секрета, сразу сообщите Shtab: аккаунт отключат и выдадут новый.

Что в песочнице​

  • Очереди, категории, итоги и метки демо-организации: справочники API отвечают не пустотой.
  • Три обращения вымышленных клиентов token:crm client-1, client-2 и client-3: на них работают примеры из быстрого старта.
  • Операторов нет: обращения остаются в очереди, ответ можно написать ботом или своим сервисным аккаунтом.

Каждую ночь песочница сбрасывается. Все обращения удаляются вместе с сообщениями и файлами, затем тестовые заводятся снова, с новыми id. Сервисные аккаунты, подписки на вебхуки и клиенты остаются. Не храните ссылки на обращения песочницы дольше дня.

Playground в справочнике​

  1. Откройте справочник и выберите операцию.
  2. В блоке авторизации выберите схему sandbox (OAuth2 client credentials) и введите client_id и секрет. Справочник сам получит токен.
  3. Сервер по умолчанию — песочница. Вариант https://{host} — ваша установка, адрес вводится в переменную host.
  4. Отправьте запрос кнопкой «Test Request».

Секрет живёт только в памяти вкладки: после перезагрузки его нужно ввести снова. Запросы уходят из браузера прямо в API, без посредников: справочник не загружает ничего с других сайтов и не шлёт запросы через чужой прокси.

Секрет и токен песочницы отправляйте только на адрес API и адрес выдачи токена из таблицы выше. Не вставляйте их в сторонние инструменты, онлайн-прокси и сервисы отладки запросов.

Playground и своя установка​

Браузер пустит запрос портала к API, только если установка разрешила его origin. По умолчанию это выключено. Администратор установки включает это настройкой INTEGRATION_CORS_ORIGINS (в Helm — config.integrationCorsOrigins):

config:
  integrationCorsOrigins:
    - https://developers.helpdesk.shtab.io
  • Только перечисленные origin, без * (установка с ним не запустится) и без cookie: токен идёт заголовком Authorization.
  • Токен выдаёт Keycloak установки. Чтобы браузер прочитал его ответ, у клиента сервисного аккаунта в Web origins должен быть тот же origin.
  • Секрет клиента из production в браузер лучше не вводить: для Playground заведите отдельный аккаунт с ролью только на чтение.

Ограничения​

  • Только тестовые данные. Никаких реальных клиентов и персональных данных: external_id — тестовые, имена — вымышленные, файлы — тестовые.
  • Стенд, а не production. Он обновляется с каждым изменением продукта и может быть недоступен несколько минут. SLA нет.
  • Лимиты — те же, что в продукте (ограничения частоты). Нагрузочные тесты на песочнице не проводятся.
  • Вебхуки уходят только на адреса, которые установка разрешила для исходящих вызовов. Адрес своего приёмника пришлите вместе с запросом доступа.