Авторизация в REST

Методы REST API Битрикс24 вызывают HTTP-запросами к адресу конкретного Битрикс24 — из любой программы, которая умеет работать с протоколом HTTP. Каждый запрос выполняется от имени пользователя и с его правами: если сотрудник не видит сделку в CRM, метод не вернет ее и через API. Дополнительно доступ ограничивают scope, способ авторизации и условия конкретного метода.

Поэтому в каждом запросе, помимо параметров метода, передают данные авторизации. Без них Битрикс24 отклонит запрос с ошибкой NO_AUTH_FOUND.

Данные авторизации передают одним из двух способов:

• входящий вебхук — постоянный секретный код в адресе запроса. Подходит для интеграций с одним Битрикс24
• токен OAuth 2.0 — временный токен в параметре auth. Его получают локальные и тиражные приложения

Как выбрать способ под задачу, описано в обзоре раздела Как вызывать методы REST API.

Входящие вебхукиВходящие вебхуки

Пример обращения к REST API через входящий вебхук:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
	"entityTypeId": 2,
	"fields": {
		"title": "New Deal",
		"typeId": "SALE",
		"stageId": "NEW"
	}
}' \
https://your-domain.bitrix24.com/rest/1/8g9l071eismy9q2l/crm.item.add.json

В адресе запроса указаны:

• адрес Битрикс24 — your-domain.bitrix24.com
• идентификатор пользователя, который создал вебхук, — 1
• секретный код вебхука — 8g9l071eismy9q2l
• метод crm.item.add, который добавляет элемент CRM. Значение entityTypeId: 2 означает сделку

Параметры метода, в примере — entityTypeId и fields, передают в теле POST-запроса.

Авторизацией служат идентификатор пользователя и секретный код в адресе. Метод выполняется с правами пользователя, который создал вебхук, и только в пределах scope, выбранных в настройках вебхука. Код вебхука открывает доступ к данным Битрикс24, поэтому храните его как пароль: не публикуйте и не передавайте в код, который выполняется в браузере.

Вебхуки подходят:

• для разового импорта или экспорта данных
• для простых интеграций с системами компании: ERP, учетом рабочего времени, мониторингом оборудования и программ
• для автоматизации обработки лидов и сделок в роботах и триггерах CRM

Вебхук проще в реализации: для него не нужен протокол OAuth 2.0. По умолчанию вебхук может создать любой сотрудник, а администратор может ограничить это право. Часть методов вебхуку недоступна, потому что им нужен контекст приложения. Например, метод placement.bind через вебхук вернет ошибку WRONG_AUTH_TYPE.

Как создать вебхук, настроить доступ сотрудников и проверить метод, описано на странице Входящие и исходящие вебхуки.

Приложения с авторизацией OAuth 2.0Приложения с авторизацией OAuth 2.0

Пример обращения к REST API с временным токеном авторизации:

curl -X POST \
-H "Content-Type: application/json" \
-d '{
	"entityTypeId": 2,
	"fields": {
		"title": "New Deal",
		"typeId": "SALE",
		"stageId": "NEW"
	},
	"auth": "807ca26600631fce00007a4b00000001f0f107255033363e91ab16442bd901b2571ed9"
}' \
https://your-domain.bitrix24.com/rest/crm.item.add.json

В запросе указаны:

• адрес Битрикс24 — your-domain.bitrix24.com
• метод crm.item.add, который добавляет сделку
• токен авторизации в параметре auth

Авторизацией служит токен доступа access_token, который приложение передает в параметре auth. По нему Битрикс24 определяет приложение и пользователя, от имени которого выполняется запрос. Метод выполняется с правами этого пользователя и в пределах scope приложения: для примера нужен scope crm и право добавлять сделки.

Токен действует ограниченное время, после чего его обновляют. Как приложения получают и продлевают токены, описано в разделе OAuth 2.0. Токены открывают доступ к данным Битрикс24, как код вебхука: не публикуйте их, не пишите в логи и храните на сервере приложения в защищенном хранилище.

Приложения бывают локальные и тиражные.

Локальные приложения устанавливают в один Битрикс24, без публикации в каталоге. В отличие от вебхуков, они подходят для задач, где нужен собственный интерфейс:

• отчеты
• обработчики для особой бизнес-логики
• решения, которые управляют доступом пользователей
• чат-боты и приложения, расширяющие возможности мессенджера
• дополнительные действия для бизнес-процессов

Локальному приложению доступны и методы, которым нужен контекст приложения. По умолчанию добавить локальное приложение может только администратор, он может выдать это право другим сотрудникам.

Тиражные приложения публикуют в каталоге Битрикс24 Маркетплейс. Их устанавливают в разные Битрикс24, а возможности приложения можно продавать по подписке. Публикацию регулируют правила Маркетплейса — с ними стоит ознакомиться до разработки.

Если авторизация не прошлаЕсли авторизация не прошла

Системные ошибки и порядок их обработки описаны в статье Коды ошибок, ошибки конкретного метода — на его странице.

Продолжите изучениеПродолжите изучение

• Как вызывать методы REST API
• Как выполнить свой первый запрос к API
• Входящие и исходящие вебхуки
• Полный протокол авторизации OAuth 2.0