Частые вопросы о Маркетплейсе Аспро.Cloud
Аутентификация и авторизация
Какие способы аутентификации официально поддерживаются для приложений маркетплейса?
Аутентификация (то есть определение текущего пользователя аккаунта) возможна только через access-токен доступа, полученный в процессе авторизации OAuth 2.0.
От чьего имени выполняется API-запрос от приложения?
API-запрос выполняется с передачей в заголовке access-токена пользователя, от имени которого будет выполнен запрос.
Если приложение встроено в интерфейс платформы и использует для выполнения API-запросов библиотеку JS SDK, то эти запросы всегда выполняются с access-токеном текущего авторизованного пользователя аккаунта.
Тем не менее приложение может отправлять API-запросы с передачей токена любого пользователя, например, с бекенда, согласно своей бизнес-логике.
Когда следует использовать OAuth 2.0 вместо API-ключа?
API-ключ выдается на один аккаунт. Значит, при установке публичного приложения на аккаунт пришлось бы каждый раз выдавать для приложения новый API-ключ. Это неудобно.
Приложению пришлось бы самостоятельно где-то хранить информацию: какой API-ключ нужно использовать от какого аккаунта. Плюс API-ключ не привязан к пользователю, то есть аутентификация пользователя по API-ключу невозможна.
Использование OAuth 2.0 не ограничено одним аккаунтом, поскольку токены доступа выдаются без привязки к аккаунту, но с привязкой к пользователю и приложению.
Можно ли делать прямые запросы к API из frontend-кода, или чувствительные операции должны выполняться через backend?
Приложение может отправлять API-запросы как с бекенда, так и с фронтенда. Настоятельно рекомендуется отправка запросов с фронтенда только с токенами текущего пользователя.
В противном случае, так как данные запроса, в том числе и токен, доступны в браузере к отображению через инструменты разработчика, текущий авторизованный пользователь сможет «украсть» токены другого пользователя и бесконтрольно использовать их в дальнейшем.
При использовании приложением JS SDK для приложений всегда используется access-токен текущего авторизованного пользователя и API-запросы с фронтенда выполняются от его имени.
Как концептуально права из манифеста соответствуют доступу к API?
В манифесте описывается список скоупов. Каждый скоуп — это некоторая область из конкретных моделей (сущностей) модулей и уровень доступа к этим моделям.
Всего есть 2 уровня доступа: «Только чтение» (read) и «Полный доступ» (full). У всех скоупов есть код.
Скоупы влияют на доступный список:
Регистрируемых приложением вебхуков.
Отображаемых настроек приложения с привязкой к моделям (сущностям) модулей (пользователи, контрагенты, счета и прочие).
разрешенных API-запросов к моделям (сущностям) модулей.
Более подробный функционал скоупов и их список:
Скоуп users — приложению доступна модель Пользователей.
Скоуп user.me — приложению доступна модель Пользователей с ограничением по текущему авторизованному пользователю.
Скоуп crm — приложению доступны все модели модуля crm.
Скоуп crm.accounts — приложению доступны модели: crm.account, crm.company, crm.contact, crm.phone, crm.email.
Скоуп crm.deals — приложению доступны модели: crm.leads, crm.leadsitems.
Скоуп products — приложению доступны все модели модуля products.
Скоуп fin — приложению доступны все модели модуля fin.
Скоуп fin.invoices — приложению доступны модели: fin.invoices, fin.items, fin.itemsrelation.
Скоуп st — приложению доступны все модели модуля st.
Скоуп task — приложению доступны все модели модуля task.
Скоуп agile — приложению доступны все модели модуля agile.
Скоуп calendar — приложению доступны все модели модуля calendar.
Скоуп timetracker — приложению доступны все модели модуля timetracker.
Скоуп knowledgebase — приложению доступны все модели модуля knowledgebase.
Скоуп workspace — приложению доступны все модели модуля workspace.
Скоуп orgchart — приложению доступны все модели модуля orgchart.
Скоуп customlists — приложению доступны все модели модуля customlists.
Если у приложения указан несколько раз один и тот же скоуп с разным уровнем доступа (read и full), то учитывается только скоуп с максимальным уровнем доступа (full).
Если у приложения указаны одновременно общий скоуп модуля и более точечный (например, crm и crm.accounts), то учитывается только один общий скоуп (т.е. crm), а второй игнорируется.
Приватные и публичные приложения
Требуется ли проверка или модерация для локальных приложений?
Нет, для локальных приложений модерация не нужна.
Требуется ли повторная проверка при каждом обновлении публичного приложения?
Изменение текстов с описанием приложения, поддержки, баннеров, логотипов и прочее не требует повторной модерации.
Модерацию требует каждая новая версия приложения. Мы проверяем заявленный функционал, работоспособность, безопасность, достаточность и оправданную необходимость запрашиваемых скоупов приложению.
Жизненный цикл приложения
Какие события жизненного цикла поддерживаются?
В личном кабинете разработчика доступно:
создание приложения;
редактирование приложения;
деактивация/активация приложения;
публикация/скрытие приложения в каталоге маркетплейса;
удаление приложения;
создание новой версии;
редактирование версии;
отправка версии на модерацию;
публикация/скрытие версии в каталоге маркетплейс через смену статуса ;
установка версии на другой аккаунт по ссылке;
установка версии на текущий аккаунт.
Что можно сделать с уже установленным приложением на аккаунте:
деинсталлировать с аккаунта;
задать роли для пользователей и групп;
изменить настройки приложения (на уровне приложения);
изменить пользовательские настройки (на уровне пользователя);
приложение встраивается в разные места интерфейса системы;
приложение может использовать JS SDK функционал.
Какие данные доступны приложению при установке, обновлении или удалении?
Поскольку событий нет, то во время этих процессов приложение не получает никаких данных. После того как приложение начинает работать на аккаунте в интерфейсе любого из пользователей, то endpoint приложения в месте встройки получает:
тип протокола (http/https);
доменное имя аккаунта (my_company.aspro.cloud);
код языка интерфейса пользователя (ru/en);
код встройки и его уникальный id (из манифеста приложения);
уникальный код приложения (da58bcec-8e2f-11f0-9f3e-eac2b61c1667);
номер версии (1.0.0 — всегда для локального приложения).
Используя библиотеку JS SDK приложение может дополнительно:
получить access, refresh токены текущего авторизованного пользователя;
получить настройки приложения;
получить пользовательские настройки;
выполнять API-запросы в рамках завяленных в манифесте скоупов и прав к модулям у текущего авторизованного пользователя;
отображать интерфейсные объекты (уведомления, алерты, модальные окна, боковые панели, переходы на другие страницы и прочее).
Что происходит с конфигурацией и данными, связанными с приложением, при его удалении?
При удалении приложения с аккаунта удаляются:
значения настроек приложения и пользовательских настроек,
файлы из настроек приложения,
зарегистрированные приложением вебхуки,
настройки ролей пользователй и групп в приложении,
Приложение перестает встраиваться в интерфейс
При удалении приложения из личного кабинета разработчика все вышеперечисленное произойдет для всех аккаунтов с установленным приложением последовательно (итерационно). Также удаляются access и refresh токены приложения для всех пользователей.
При обновлении приложения:
сравниваются манифесты ранее установленной версии и новой версии;
обновляется список вебхуков приложения согласно новому манифесту, т.е. удаляются ранее зарегистрированные, если они были в предыдущем манифесте и регистрируются новые вебхуки, если такие указаны.
Настройки приложения, роли и файлы при обновлении приложения не меняются. Приложение перестает встраиваться в тех местах, которые не указаны в новом манифесте, и наоборот — встраивается в новые места, указанные в новом манифесте.
