Простое получение токенов

Простейшим сценарием для получения доступа к REST API является работа приложения в интерфейсе Битрикс24. В этом случае все необходимые авторизационные данные выдаются приложению при открытии, а также доступна возможность использования js-библиотеки для совершения вызовов к API.

Приложение получает следующий массив POST-данных:

array (
	'DOMAIN' => 'portal.bitrix24.com', // домен портала
	'PROTOCOL' => '1', // протокол обращения: 0 - http, 1 - https
	'LANG' => 'ru', // текущий язык, на котором пользователь просматривает портал
	'APP_SID' => 'dd8cec11e347088fe87c44870a9f1dba', // служебный параметр для связи js-библиотеки с окружением приложения
	'AUTH_ID' => 'ahodg4h37n89vo17gbkgq0x1l825nnb5', // основной авторизационный токен, требуемый для доступа к REST API
	'AUTH_EXPIRES' => '3600', // время жизни авторизационного токена
	'REFRESH_ID' => '2lg086mxijlpvwh0h7r4nl19udm4try5', // дополнительный авторизационный токен, служащий для продления сохраненной авторизации
	'member_id' => 'a223c6b3710f85df22e9377d6c4f7553', // уникальный идентификатор портала, не зависящий от доменного имени
	'status' => 'P', // статус приложения на портале. значение поля служит чисто для информации, чтобы получить доверенное значение, используйте метод oauth.bitrix.info/rest/app.info
)

При помощи значения параметра AUTH_ID можно сразу совершать запросы к API.

И как написано выше, приложения в интерфейсе могут совершать запросы к API на стороне клиента, то есть браузера пользователя, подключив js-библиотеку и используя методы BX24.callMethod и BX24.callBatch. В этом случае работа с авторизацией будет происходить автоматически.

Таким образом, становится доступным простой сценарий получения авторизационных токенов пользователя при установке приложения. Как вы знаете (это было продемонстрировано в соответствующем примере раздела "Быстрый старт"), у публичного тиражного решения существует возможность задать отдельный скрипт установки, который будет показываться пользователю, устанавливающему ваше решение, во фрейме один раз - в момент установки решения. И в этот фрейм Битрикс24 передает те же самые данные в POST-запросе, что и в обычном случае. Следовательно, вы можете так разработать скрипт установки, чтобы сохранять токены (что самое важное - refresh_token в том числе) на стороне своего приложения, чтобы в дальнейшем реализовать сценарий автоматического возобновления токенов.

Событие установки приложения

Для приложений, не имеющих страницы в интерфейсе Битрикс24 (параметр Использует только API в форме редактирования приложения в партнерском кабинете или на портале), доступен вот такой способ авторизации. В форме редактирования версии (или в форме редактирования локального приложения на портале) можно указать значение параметра Ссылка-callback для события установки. Если указать в этом поле ссылку на обработчик на стороне приложения, то при установке приложения обработчик получит POST-запрос со следующими данными (application/x-www-form-urlencoded):

array(
	'event' => 'ONAPPINSTALL',
	'data' => array(
		'VERSION' => '1',
		'LANGUAGE_ID' => 'ru',
	),
	'ts' => '1466439714',
	'auth' => array(
		'access_token' => 's6p6eclrvim6da22ft9ch94ekreb52lv',
		'expires_in' => '3600',
		'scope' => 'entity,im',
		'domain' => 'portal.bitrix24.com',
		'server_endpoint' => 'https://oauth.bitrix.info/rest/',
		'status' => 'F',
		'client_endpoint' => 'https://portal.bitrix24.ru/rest/',
		'member_id' => 'a223c6b3710f85df22e9377d6c4f7553',
		'refresh_token' => '4s386p3q0tr8dy89xvmt96234v3dljg8',
		'application_token' => '51856fefc120afa4b628cc82d3935cce',
	),
)

Поля запроса содержат информацию о событии (event), данные события (data), а также, авторизационные данные для доступа к REST API (auth) от имени пользователя, установившего приложение.

Значимые параметры:

• access_token - основной авторизационный токен, требуемый для доступа к REST API;
• refresh_token - дополнительный авторизационный токен, служащий для продления сохраненной авторизации;
• client_endpoint - адрес REST-интерфейса портала;
• server_endpoint - адрес REST-интерфейса сервера;
• status - статус приложения на портале.

Смотри События