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

REST API Битрикс24 - это API, к которому можно обратиться, выполняя HTTP-запросы по специальным адресам конкретного Битрикс24. Фактически, такие запросы можно выполнять из любого программного обеспечения, поддерживающего протокол HTTP.

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

При этом, помимо параметров конкретного метода, при выполнении запроса необходимо передавать некоторые авторизационные данные, без которых запрос будет считаться неразрешенным и будет заблокирован со стороны Битрикс24.

Более того, методы REST API всегда вызываюся "от имени" конкретного пользователя портала Битрикс24. Фактически, весь REST API - это другой способ использования существующего функционала Битрикс24, когда пользователь вместо использования пользовательского интерфейса обращается напрямую к функционалу продукта, вызывая те или иные методы REST API.

Существует два варианта передачи авторизационных данных в запросах к REST API:

  • Указание постоянного кода входящего локального вебхука;
  • Указание временного токена авторизации OAuth 2.0, которые используются в локальных и тиражных приложениях.

Локальные входящие вебхуки

Пример обращения к REST API с помощью входящего локального вебхука:

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

В данном примере указывается:

  • адрес конкретного Битрикс24 (your-domain.bitrix24.com);
  • идентификатор пользователя, создавшего вебхук (1);
  • секретный код вебхука (8g9l071eismy9q2l);
  • метод REST API, добавляющий сделку в CRM (crm.deal.add)

Значения параметров метода (fields) были переданы в виде POST-запроса.

Фактически, "авторизацией" при таком способе обращения к REST API, является идентификатор пользователя и секретный код вебхука.

Вебхуки идеально подходят:

  • для организации одноразового импорта-экспорта данных;
  • простых интеграций с внешними и внутренними системами компании (ERP, учет рабочего времени, авто-мониторинг программных и аппаратных средств и т.д.);
  • использования в автоматизации обработки лидов и сделок (триггеры и действия в CRM-роботах);

Использование вебхуков проще для технической реализации, поскольку не требует реализации протокола OAuth 2.0. Каждый пользователь может добавлять вебхуки "для себя" и REST API, вызываемый в рамках таких вебхуков, будет ограничиваться правами конкретного пользователя-владельца.

Подробнее про вебхуки вы можете узнать в соответствующе уроке нашего видео-курса для разработчиков.

Локальные и тиражные приложения с использованием OAuth 2.0

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

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

В данном примере указывается:

  • адрес конкретного Битрикс24 (your-domain.bitrix24.com);
  • метод REST API, добавляющий сделку в CRM (crm.deal.add);
  • токен авторизации, указанный в параметре auth (807ca26600631fce00007a4b00000001f0f107255033363e91ab16442bd901b2571ed9).

Значения параметров метода (fields) были переданы в виде POST-запроса.

"Авторизацией" при таком способе обращения к REST API, является тот самый токен, указанный в параметре auth. В нем зашифрован ряд важных системных значений, включая идентификатор конкретного пользователя Битрикс24, от имени которого происходит обращение к REST API.

Как локальные и тиражные приложения получают токены авторизации, вы можете узнать в соответствующем разделе документации.

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

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

Локальные приложения поддерживают все возможности REST API и вызывают REST по протоколу авторизации OAuth 2.0, но устанавливаются только на конкретном Битрикс24, без публикации в каталоге решений. Для добавления локального приложения требуется административный доступ.

Тиражные решения публикуются в нашем каталоге приложений. Они являются доступными для установки неограниченному кругу пользователей и, более того, вы можете делать их платными, продавая их функционал по модели подписки.

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

Предыдущая
Как вызывать методы REST API
Следующая
Как выполняется запрос