Настройка системы
API-ключи
Ключи открывают внешним системам доступ к публичному API предварительной записи. Секрет показывается один раз, хранится в виде хеша и передаётся в заголовке запроса.
Создать ключ
- Откройте Система → API-ключи.
- Нажмите «Создать ключ» и выберите тип: рабочий (live) или тестовый (sandbox).
- Задайте имя — по нему будет понятно, какая интеграция использует ключ.
- Отметьте права (scopes), необходимые интеграции.
- Ограничьте очереди и услуги, если ключ должен видеть не всё.
- Укажите срок действия, если он нужен.
- Скопируйте секрет сразу — после закрытия окна он больше не показывается.
- Сохраните секрет в защищённом хранилище интеграции.
Типы ключей
| Тип | Назначение | Особенности |
|---|---|---|
| Рабочий (live) | Боевая интеграция с сайтом, 1С, колл-центром. | Создаёт реальные записи, видит их в живой очереди и отчётах. |
| Тестовый (sandbox) | Прогон сценариев и проверка интеграции. | Создаёт только тестовые записи, изолированные от живой очереди, экранов и отчётов; удаляются через сутки. |
Права ключа
| Право | Что разрешает |
|---|---|
services.read | Список очередей и услуг, доступных ключу. |
slots.read | Правила записи и свободные слоты. |
booking.read | Чтение одной брони по коду. |
booking.read_all | Чтение броней, созданных другими ключами. |
booking.list | Список броней за период. |
booking.create | Создание брони. |
booking.cancel | Отмена брони. |
booking.reschedule | Перенос брони. |
Нет права — API отвечает 403 scope_denied. По умолчанию ключ
видит только свои брони; booking.read_all выдавайте только
доверенным супервизорским ключам.
Ограничения
- Очереди и услуги: пустой список означает «ничего не разрешено», отсутствие ограничения — «все».
- Срок действия: после истечения ключ получает
401 api_key_expired. - Активность: отозванный ключ получает
401 invalid_api_key. - Тип ключа после создания не меняется.
Перевыпуск и отзыв
- Перевыпустить — создаёт новый секрет, старый сразу перестаёт работать. Используйте при подозрении на утечку.
- Отозвать — мягко отключает ключ; история операций сохраняется.
- Все действия с ключами попадают в Историю действий, секрет в журнале маскируется.
- Просмотреть список активных ключей и их ограничения можно в любой момент.
Безопасность
- Не вставляйте live-ключ в JavaScript браузера или мобильное приложение.
- Не храните секрет в Git и в открытых конфигурациях.
- Используйте только HTTPS.
- Передавайте ключ в
X-API-KeyилиAuthorization: Bearer. - Настройте отдельные ключи под разные интеграции, чтобы отзыв одного не ломал остальные.
- Прогоняйте сценарии на песочнице перед боевым запуском.
Если секрет потерян, восстановить его нельзя — можно только
перевыпустить ключ. Заранее предусмотрите процедуру замены секрета в
интеграции.
Проверка
- Ключ создан с нужным типом и правами.
- Ограничения по очередям и услугам соответствуют задаче.
- Секрет сохранён вне репозитория.
- Запрос со ключом возвращает услуги и слоты.
- Отозванный ключ действительно получает 401.