JSON-манифест приложения
Манифест описывает, как приложение встраивается в Аспро.Cloud: в какие места интерфейса оно добавляет свой контент, к каким данным запрашивает доступ, какие настройки требует и на какие события подписывается.
Манифест — это JSON-объект строго с шестью верхнеуровневыми ключами:
Ключ | Назначение |
|---|---|
| Внутренняя версия формата манифеста. Управляется системой (сейчас — |
| Доступы — области API, к которым приложению нужен доступ. |
| Места встройки — точки интеграции в интерфейсе, куда приложение добавляет контент. |
| Настройки приложения (общие для аккаунта): API-ключи, адреса эндпоинтов и т.п. |
| Пользовательские настройки — персональные параметры каждого пользователя. |
| Вебхуки — исходящие уведомления, которые платформа шлёт приложению при событиях в данных. |
Разбор полей манифеста
scopes — доступы
Список областей API, к которым приложению нужен доступ. Каждый элемент — объект с двумя полями:
code— код области доступа;permission— уровень:read(только чтение) илиfull(чтение и запись). По умолчаниюread.
Права запрашиваются у администратора при установке приложения; API-запросы приложения проверяются на соответствие выданным доступам.
Допустимые code: agile, calendar, contactcenter, telephony, crm, crm.accounts, crm.deals, customlists, fin, fin.invoices, finacts, knowledgebase, orgchart, products, st, task, timetracker, users, user.me, workspace.
placements — места встройки
Каждый элемент описывает одну точку интеграции. Общая форма:
{
"code": "<тип места встройки>",
"props": { "target": { "module": "...", "model": "..." } },
"content": { "...": "что показать (заголовок, иконка, iframe)" },
"action": { "code": "<что делать по клику>", "content": { } }
}
code— тип точки интеграции (обязателен);content— что отображается:id,title(строка),icon.src,iframe.srcи др;props.target— для мест, привязанных к сущности (вкладка/виджет в карточке): модуль и модель сущности;action— что произойдет по клику.
Допустимыеcode (типы мест встройки):
Группа | Значения |
|---|---|
Домашняя страница приложения |
|
Верхняя панель | |
Главное меню | |
Список сущностей |
|
Карточка сущности | |
Рабочий стол | |
Отчеты | |
Контакт-центр / телефония |
|
Допустимые action.code: do.nothing, follow.link (открыть ссылку), show.modal--page / show.modal--iframe (модальное окно), show.sidepanel--page / show.sidepanel--iframe (боковая панель), show.tab--page / show.tab--iframe (вкладка). Набор доступных действий зависит от типа места встройки.
settings и user_settings — настройки
Массив групп настроек. Каждая группа:title(название) и options (список полей). Каждое поле-option:
id— идентификатор параметра (до 32 символов);code— тип поля;title— подпись;attrs— атрибуты поля (required,placeholder,checked,valueи др., зависят от типа).
settings — общие настройки приложения (например, API-ключ на весь аккаунт). user_settings — персональные настройки каждого пользователя.
Допустимые code полей: input.text, input.password, input.number, input.checkbox, input.radio, select, textarea, input.time, input.date, input.datetime, input.file, entity.select, custom.
webhooks — исходящие вебхуки
Приложение может подписаться на события в данных аккаунта. Каждый вебхук:
{
"event": {
"target": { "module": "<модуль>", "model": "<сущность>" },
"action": "create"
},
"url": "https://app.example.com/webhooks/...",
"user_id": ""
}
event.target— модуль и модель сущности, изменения которой отслеживаются;event.action— тип события:create,update,delete,any(любое). Для счетов (fin.invoices) дополнительно доступенpaid;url— адрес обработчика на стороне приложения, куда платформа отправит данные;user_id— необязательный пользователь, от имени которого авторизуется вебхук (можно оставить пустым).
