Как выполнить свой первый запрос к API

Чтобы выполнить первый запрос к REST API, создайте входящий вебхук. Это готовый инструмент для вызова методов API с правами пользователя, который создал вебхук.

Проверить вебхук можно методом profile: он ничего не меняет в Битрикс24 и возвращает ваши данные — имя, фамилию и ID. Если запрос не пройдет, причину подскажет код ошибки. Когда вебхук заработает, выберите способ авторизации для рабочей интеграции: вебхук или приложение.

Как создать входящий вебхукКак создать входящий вебхук

1. В левом меню Битрикс24 откройте раздел Разработчикам
2. Перейдите на вкладку Готовые сценарии > Другое > Входящий вебхук. Появится слайдер с уже сгенерированным кодом вебхука
3. В блоке Настройка прав выберите scope — группы методов, к которым вебхук получит доступ. Для первой проверки методом profile scope не нужен
4. Скопируйте URL из поля Вебхук для вызова rest api
5. Нажмите Создать. Битрикс24 сохранит вебхук и откроет список Интеграции, где его можно найти позже

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

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

Генератор запросовГенератор запросов

Под кодом вебхука находится блок Генератор запросов. С его помощью можно подобрать метод, указать параметры и сразу выполнить запрос. Если слайдер вебхука уже закрыт, откройте вебхук в списке Интеграции.

1. Выберите метод из списка. По умолчанию выбран profile, он не меняет данные. Если нужного метода в списке нет, выберите его scope в блоке Настройка прав, сохраните вебхук и укажите название метода в URL

   На скриншоте для примера выбран метод crm.company.add, он создает компанию.

   

2. При необходимости укажите параметры метода

3. Нажмите Выполнить. Генератор отправит запрос и покажет ответ в формате JSON

   На скриншоте — ответ crm.company.add: в поле result пришел идентификатор созданной компании.

   

Структура URL вебхукаСтруктура URL вебхука

Внешняя система вызывает методы по URL вебхука. Его можно скопировать из поля Вебхук для вызова rest api или из генератора запросов.

Пример URL:

https://your-company.bitrix24.ru/rest/1/8v5m0dmbxs2ky7wq/department.get.json?ID=1

URL состоит из нескольких частей:

• your-company.bitrix24.ru — адрес Битрикс24
• /rest — указание на работу через REST API
• /1 — идентификатор пользователя, создавшего вебхук
• /8v5m0dmbxs2ky7wq — секретный код вебхука
• /department.get — вызываемый метод REST API, здесь department.get
• .json — формат ответа, его можно не указывать
• ?ID=1 — параметры метода

Как проверить вебхукКак проверить вебхук

Для проверки подойдет метод profile: он работает без параметров и без отдельного scope. Добавьте имя метода к URL вебхука и откройте адрес в браузере:

https://your-company.bitrix24.ru/rest/1/8v5m0dmbxs2ky7wq/profile

После проверки удалите этот адрес из истории браузера: в нем есть секретный код вебхука.

Если вебхук работает, Битрикс24 вернет данные пользователя, который его создал. Данные приходят в поле result, служебная информация о запросе — в поле time. Полный ответ с описанием полей приведен на странице метода profile.

Сокращенный ответ:

{
    "result": {
        "ID": "1",
        "ADMIN": true,
        "NAME": "Вадим",
        "LAST_NAME": "Валеев"
    },
    "time": {
        "duration": 0.0401120185852051
    }
}

Если ответ похож на этот, переходите к примерам на страницах методов. Как их запускать, объясняет статья Как использовать примеры в документации.

Ошибки и диагностикаОшибки и диагностика

Если запрос не выполнился, Битрикс24 вернет поля error и error_description вместо result. Так отвечают методы прежней версии API, на которой построены примеры этой страницы. Вот ответ, когда у вебхука нет нужного scope:

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

Частые ошибки первого запроса:

Ошибки метода описаны на его странице в разделе «Обработка ошибок». Общие коды собраны в статье Коды ошибок.

Как настроить доступ к созданию вебхуков для сотрудниковКак настроить доступ к созданию вебхуков для сотрудников

Администратор Битрикс24 разрешает создавать вебхуки всем сотрудникам или отдельным пользователям.

1. Откройте Настройки > Настройки Битрикс24. Раздел доступен только сотрудникам с правами администратора
2. В новом окне перейдите в Безопасность > Интеграции Битрикс24
3. В поле Кому разрешить создавать входящие вебхуки нажмите Добавить и выберите всех сотрудников или отдельных пользователей
4. Нажмите Сохранить внизу окна

Другие способы работы с APIДругие способы работы с API

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

Часть методов, например методы встраивания виджетов, через вебхук недоступна: им нужен контекст приложения. Подробнее — в статье Входящие и исходящие вебхуки.

• Для регистрации локальных приложений перейдите на вкладку Готовые сценарии > Другое > Локальное приложение. Если пункта Локальное приложение нет, попросите администратора настроить доступ к созданию приложений так же, как доступ к созданию вебхуков
• Чтобы размещать приложения в Маркетплейс, станьте участником партнерской программы: заполните анкету на сайте кабинета разработчика

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

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