Модель в одном абзаце#
Ключ выдаётся на реального сотрудника, от чьего лица будет работать интеграция. Список доступных торговых центров нигде не хранится: на каждом запросе мы спрашиваем, есть ли у этого сотрудника права. Отобрали роль, и центр пропал из выдачи сам; отдельно отзывать ключ не нужно.
Как получить ключ#
Сейчас ключи выпускаем мы. Чтобы получить ключ, нужно написать менеджеру Rentu и указать:
- сотрудника, от чьего лица будет работать интеграция;
- назначение интеграции: BI-выгрузка, обмен с 1С, внутренний отчёт.
В ответ придут client_id и client_secret.
Секрет показывается один раз и хранится у нас только в виде хэша. Восстановить его мы не можем — при утере придётся выпускать новый. Хранить его стоит там же, где остальные секреты, а не в переписке.
Один ключ на сотрудника. Второй выпустить нельзя, и это намеренно: два ключа у одного человека сделали бы неразличимыми и отзыв, и учёт нагрузки. Если интеграций несколько, они используют один ключ.
Кого выбрать владельцем#
Ключ наследует права сотрудника, поэтому владелец должен иметь доступ ко всем торговым центрам, данные которых нужны интеграции.
Хорошо подходит сотрудник, который и так отвечает за эти центры: аналитик, управляющий, руководитель отдела. Плохо подходит человек, который завтра уйдёт в отпуск и потеряет роли, или технический аккаунт «на всякий случай»: у него не будет прав, и интеграция не увидит ничего.
Если сотрудник увольняется, ключ стоит заранее переоформить на другого. После снятия ролей интеграция начнёт получать 403 forbidden_sc.
Что происходит при запросе#
- Проверяем токен.
- Спрашиваем, есть ли у владельца ключа права на этот метод и этот центр.
- Проверяем, не заблокирован ли центр по оплате.
- Проверяем, хватает ли тарифа центра для этого метода.
Отказ на любом шаге даёт свой машинный код, см. Ошибки.
Изменение прав#
| Что произошло | Когда увидит интеграция |
|---|---|
| Сотруднику дали роль в новом ТЦ | Сразу |
| Сотруднику сняли роль | В течение часа |
Разница объясняется кэшем: положительные ответы мы держим до часа, отрицательные не кэшируем вовсе. Закрыть доступ немедленно позволяет отключение ключа: оно действует мгновенно.
Отзыв и ротация#
| Действие | Что происходит |
|---|---|
| Ротация секрета | client_id остаётся прежним, старый секрет умирает сразу. Перенастраивать идентификатор не нужно |
| Отключение ключа | Все запросы получают 401. Действует мгновенно |
| Снятие ролей | Пропадают конкретные ТЦ, ключ продолжает работать с остальными |
Ротация это правильная реакция на утечку секрета. Отключение ключа отвечает на увольнение владельца или прекращение интеграции.
Тариф и лимиты живут не на ключе#
Две вещи, которые часто ожидают увидеть на ключе, живут на торговом центре:
- тариф задаёт глубину доступных данных;
- лимит частоты задаёт, сколько запросов в минуту можно сделать.
Один ключ может покрывать несколько центров на разных тарифах: по одному доступны год истории и чеки, по другому только месяц и без чеков. Подробнее в разделе Тарифы.