Права и переустановка приложения

Права приложения (scope) определяют, к каким методам REST оно допущено. Изменение прав или обработчика запускает переустановку, которую пользователь должен подтвердить. Понимание этого цикла спасает от «отвалившихся» интеграций после обновлений.

Что такое права доступа (scope)

Scope — это набор областей REST, которые приложение объявляет при регистрации и запрашивает при установке. Каждая область открывает доступ к группе методов: crm — к сделкам и контактам, task — к задачам, im — к мессенджеру, placement — к встройкам.

Права работают по принципу минимальной достаточности: приложение получает только то, что запросило, и не больше. Попытка вызвать метод вне выданного scope вернёт ошибку INVALID_TOKEN или insufficient_scope.

Как приложение устанавливается

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

• access_token — короткоживущий токен доступа к REST;
• refresh_token — токен обновления, по которому получают новый access_token;
• событие ONAPPINSTALL — сигнал завершить настройку: зарегистрировать placement, роботов, значения по умолчанию.

Приложение с интерфейсом получает при установке страницу инсталлятора, где принято выполнять первичную конфигурацию и показать пользователю результат.

Проверка статуса: app.info

Чтобы понять текущее состояние прав и лицензии, приложение вызывает метод app.info. Он возвращает установленные области, статус установки и данные о тарифе.

{
  "result": {
    "CODE": "my.app",
    "VERSION": 3,
    "STATUS": "P",
    "INSTALLED": true,
    "SCOPE": ["crm", "placement"]
  }
}

Поле SCOPE показывает реально выданные права — сверяйте с ними логику. Поле STATUS сообщает тип лицензии (демо, триал, платная), а VERSION помогает отследить, установлена ли актуальная версия приложения.

Когда требуется переустановка

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

• Изменился scope. Добавили новую область прав — пользователь должен подтвердить расширение;
• Сменился обработчик. Поменялся URL страницы приложения;
• Вышла новая версия. Для тиражного приложения публикация версии инициирует обновление на порталах;
• Изменился состав placement. Приложение регистрирует новые точки встройки.

Событие ONAPPUPDATE и обновления

При обновлении приложения платформа вызывает событие ONAPPUPDATE. Это ваша точка для миграций: перерегистрировать placement, обновить роботов, привести данные к новой схеме.

1. Пользователь запускает обновление и подтверждает изменённые права;
2. Битрикс24 вызывает обработчик события ONAPPUPDATE;
3. Приложение сверяет свою версию с app.info и выполняет миграцию;
4. При необходимости заново вызывает placement.bind для новых встроек.

Хорошая практика — делать обработчики установки и обновления идемпотентными: повторный вызов не должен создавать дубли placement или роботов. Перед регистрацией проверяйте, не привязана ли встройка уже, через placement.get.

Отзыв прав и удаление

Права можно не только выдать, но и отозвать. Когда пользователь удаляет приложение, платформа шлёт событие ONAPPUNINSTALL, а токены становятся недействительными.

Минимизация прав и безопасность

Запрашивать «всё на всякий случай» — плохая практика. Избыточный scope снижает доверие при модерации, пугает администраторов при установке и расширяет поверхность атаки, если токены утекут.

• Запрашивайте только нужное. Если приложение работает с задачами, не просите crm;
• Разделяйте чтение и запись логикой. Scope открывает группу методов, но какие из них вызывать — решаете вы;
• Планируйте рост прав. Каждое расширение scope в будущем потребует переустановки у всех пользователей, поэтому продумывайте набор заранее;
• Храните refresh_token безопасно. Именно он позволяет бесконечно получать доступ к порталу, пока приложение не удалено.

Чем аккуратнее выстроены права, тем меньше трения при установке и обновлениях и тем проще пройти проверку при публикации в Маркете.

Итог

Права и переустановка — это жизненный цикл приложения на портале. Scope задаёт границы доступа, установка выдаёт токены и запускает ONAPPINSTALL, изменение прав или версии требует переустановки с подтверждением и вызывает ONAPPUPDATE, а удаление — ONAPPUNINSTALL. Идемпотентные обработчики и сверка с app.info делают обновления безболезненными.

Мы выстраиваем этот цикл так, чтобы обновления приложения не роняли интеграции у пользователей: аккуратные миграции, минимально необходимый scope и чистая деинсталляция. Если ваше приложение растёт и меняет права, поможем спроектировать безопасный процесс обновления.