Карточка приложения

Карточка приложения — то же, что «Локальное приложение» в настройках боевого портала: она задаёт client_id, client_secret, права и адреса, по которым портал будет обращаться к приложению. Заводится в кабинете: Разработка → Локальные приложения → Создать приложение.

Поля карточки

Адреса принимаются только со схемой http или https — форма проверяет это до отправки, потому что адрес подставляется во фрейм и открывается браузером.

При сохранении портал выдаёт три значения, которые дальше не меняются:

• client_id формата local.<14 hex>.<8 цифр>;
• client_secret — 50 символов;
• APPLICATION_TOKEN — 32 hex, тот же токен приходит в теле каждого события, и им обработчик проверяет отправителя.

Все три видны в панели «Ключи авторизации» карточки и копируются кнопкой.

Вид приложения

Права

Список прав — тот же, что на странице «Доступные скоупы» документации Bitrix24; устаревшие tasks, tasks_extended, tasksmobile и не дающий доступа socialnetwork в форму не включены намеренно.

Право проверяется по префиксу метода — тем же правилом, каким его определяет боевой портал: crm.* требует crm, task.* и tasks.* — task, placement.* — placement. Без нужного права метод отвечает 403:

curl -s -X POST http://localhost:8080/rest/task.item.list -d "auth=$ACCESS_TOKEN"

{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token"
}

Часть методов права не требует вовсе — это базовый уровень: app.info, profile, scope, method.get, methods, server.time, access.name, batch, event.bind, event.unbind, event.get, а также app.option.* и user.option.*.

Проверить доступность метода, не вызывая его, можно method.get:

{ "result": { "method": "task.item.list", "isExisting": true, "isAvailable": false } }

Право нужно и точке встраивания: CRM_DEAL_DETAIL_TAB требует crm, TASK_VIEW_TAB — task, CALL_CARD — telephony. placement.list показывает только те коды, право на которые у приложения есть.

Установка

1. 1

   Откройте приложение

   Кнопка «Открыть приложение» в карточке ведёт в демонстрационный портал и открывает фрейм. Пока приложение не установлено, портал открывает не обработчик, а путь установки — и делает это при каждом входе, ровно как в бою.

2. 2

   Зарегистрируйте виджеты и подписки

   Мастер вызывает placement.bind для точек встраивания и BX24.callBind (то есть event.bind) для событий. Оба метода работают и до завершения установки: регистрации сохраняются и видны в placement.get и event.get, трафика по ним просто нет.

3. 3

   Вызовите BX24.installFinish() последним

   Только после него app.info отвечает INSTALLED: true, портал начинает доставлять события и показывать виджеты. Портал асинхронно шлёт ONAPPINSTALL на обработчик — однократно, после первой успешной установки.

Приложение вида «Только API» устанавливается без браузера — запросом POST /api/b24/apps/<id>/install из кабинета: портал шлёт ONAPPINSTALL на адрес установки, и сам факт доставки и есть завершение установки. installFinish вызвать неоткуда: браузера в этом сценарии нет. Отдельной кнопки для этого в интерфейсе пока нет — запрос делается вручную.

Сброс установки и удаление

Сбросить установку — приложение возвращается в состояние «Не установлено»: отзываются все токены, удаляются зарегистрированные виджеты и подписки на события, портал снова начинает с мастера. Событие ONAPPUNINSTALL при этом не отправляется.

Удалить — то же самое плюс отправка ONAPPUNINSTALL на обработчик и удаление карточки. В теле этого события нет access_token, expires_in и scope: права уже сняты, и приложение обязано понять, что вызывать API от своего имени больше нельзя. Записи журнала доставок остаются — ссылка на приложение обнуляется, а не каскадит.

Подводные камни

Адрес обработчика проверяется на «внутренний». Это та же проверка, что у вебхуков. В локальной разработке она отключена и http://localhost:3210/handler принимается. Если APIStend запущен с NODE_ENV=production или WEBHOOK_ALLOW_PRIVATE_TARGETS=0, форма откажет: «Адрес localhost внутренний».

Правка карточки поднимает VERSION. Смена прав или адресов — это новая версия приложения; номер видно в app.info, и приложение может по нему понять, что настройки изменились.

Код приложения уникален в песочнице. Повторный код — отказ CODE_TAKEN с текстом «Приложение с кодом «…» уже есть».

Доля случайных ошибок бьёт и по методам портала. Настройка на экране «Ключи и токены» действует на весь шлюз, включая app.info, placement.bind и event.bind. Если проверяется не устойчивость мастера, а сам сценарий, поставьте долю ошибок в ноль.