Как использовать примеры в документации

На страницах методов в справочнике API примеры собраны в блок «Примеры кода». Вкладки показывают вызов метода через cURL и через официальные SDK Битрикс24 — библиотеки для разных языков программирования. Чаще всего код на вкладке — это фрагмент вызова, а не готовый проект. В таком фрагменте нет установки библиотеки, подключения к Битрикс24 и реальных значений параметров.

Чтобы пример заработал, выберите вкладку под свою среду, замените метки вида **put_your_webhook_here** своими значениями, а для SDK создайте объект подключения.

Как устроен сам HTTP-запрос к REST API, объясняет статья Как выполняется запрос.

Какую вкладку выбратьКакую вкладку выбрать

Набор вкладок отличается на разных страницах: на каждой есть только те примеры, которые подготовлены для конкретного метода. Если примера на B24PhpSDK нет, используйте CRest или соберите вызов по описанию параметров метода.

Подписи вкладок оформлены не везде одинаково: вкладка с примером на B24JsSDK может называться JS.

Сверяйте подпись с кодом: вкладку можно узнать по объекту, через который идет вызов. Объекты каждого SDK собраны в таблице раздела Что добавить, чтобы пример заработал.

Вкладки cURL подходят, когда нужно проверить метод, посмотреть сырой ответ или вызвать API там, где нельзя подключить SDK, например из терминала или стороннего сервиса. Для рабочей интеграции берите SDK: он подставляет авторизацию и разбирает ответ.

Дополнительные возможности у SDK разные: например, B24JsSDK сам обновляет токены и учитывает лимиты запросов. B24GoSDK по умолчанию повторяет запрос при превышении лимита, а токены обновляет после настройки клиента. B24PhpSDK, BX24.js и CRest не поддерживают методы REST 3.0. Если подходят несколько SDK, сравните их в обзоре SDK.

Что подставить вместо метокЧто подставить вместо меток

Вместо реальных значений в примерах стоят метки в двойных звездочках, например **put_your_webhook_here**. Заменяйте метку целиком, вместе со звездочками: в значении их быть не должно.

URL входящего вебхука выглядит так: https://your-company.bitrix24.ru/rest/1/8v5m0dmbxs2ky7wq/. Здесь 1 — идентификатор пользователя, 8v5m0dmbxs2ky7wq — секретный код.

Как выполнить пример без библиотекКак выполнить пример без библиотек

Примеры на вкладках cURL (Webhook) и cURL (OAuth) не требуют установки: достаточно заменить метки на свои значения. Команды написаны для Bash. В PowerShell на Windows вызывайте curl.exe вместо curl, а переносы строк \ и кавычки замените по правилам PowerShell.

Пример ниже создает сделку методом crm.item.add. Это упрощенный вариант вкладки cURL (Webhook) со страницы метода. Параметр entityTypeId задает тип объекта CRM: значение 2 означает сделку. Параметр fields содержит только название title. Поля, у которых есть значения по умолчанию, Битрикс24 заполнит сам.

Для вызова нужен scope crm и право добавлять сделки. Если в настройках CRM включена опция Проверять обязательные пользовательские поля в REST, добавьте эти поля в fields. Каждый запуск создает новую сделку, поэтому проверяйте пример на тестовом Битрикс24.

Запрос с метками:

curl -X POST \
-H "Content-Type: application/json" \
-d '{"entityTypeId":2,"fields":{"title":"Новая сделка"}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.item.add

Тот же запрос с подставленными значениями:

curl -X POST \
-H "Content-Type: application/json" \
-d '{"entityTypeId":2,"fields":{"title":"Новая сделка"}}' \
https://your-company.bitrix24.ru/rest/1/8v5m0dmbxs2ky7wq/crm.item.add

На вкладке cURL (OAuth) адрес короче — в нем нет идентификатора пользователя и кода вебхука, а токен передается в теле запроса в параметре auth:

curl -X POST \
-H "Content-Type: application/json" \
-d '{"entityTypeId":2,"fields":{"title":"Новая сделка"},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/crm.item.add

Ответ у обеих вкладок одинаковый. Если запрос прошел успешно, Битрикс24 вернет созданную сделку в поле result.item, а ее идентификатор — в поле result.item.id. Полный ответ приведен на странице метода.

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

{
    "result": {
        "item": {
            "id": 16,
            "title": "Новая сделка",
            "categoryId": 0,
            "stageId": "NEW",
            "assignedById": 1
        }
    },
    "time": {
        "duration": 1.9278500080108643
    }
}

Что добавить, чтобы пример заработалЧто добавить, чтобы пример заработал

Большинство примеров для SDK начинается сразу с вызова метода и обращается к объекту подключения, которого в самом примере нет. Создайте объект подключения по инструкции со страницы нужного SDK, а затем вставьте фрагмент из документации. Что есть в примере и что подготовить самостоятельно:

Примеры на вкладках JS (TS), JS (UMD) и JS рассчитаны на приложение, открытое во фрейме внутри интерфейса Битрикс24: $b24 в них — объект B24Frame, его создает функция initializeB24Frame. Для серверного кода на Node.js нужен другой класс подключения — B24Hook или B24OAuth, они описаны в статье Установка и использование B24JsSDK.

В ссылке на UMD-сборку почти во всех примерах закреплена первая мажорная версия, @bitrix24/b24jssdk@1. Если проект работает на второй версии, замените номер в ссылке на @2.

Если ставите B24JsSDK из npm, сверьте версию с примером. В версии 3.0.0 удалены методы $b24.callMethod, $b24.callListMethod, $b24.fetchListMethod, $b24.callBatch и $b24.callBatchByChunk, а на многих страницах примеры еще написаны через них. Чтобы такой пример заработал, установите вторую версию SDK или замените вызов на $b24.actions.v2, как описано в разделе Способы вызова методов.

Разбор ответа у инструментов тоже разный. Запрос через cURL отдает сырой JSON, а каждый SDK оборачивает его по-своему. Состав ответа описан на странице метода в разделе «Обработка ответа». Как добраться до данных, объясняет страница SDK.

Названия полей и параметровНазвания полей и параметров

Копируйте названия полей из примера и из раздела «Параметры метода» без изменений. В разных группах методов приняты разные соглашения об именовании:

• универсальные методы CRM, например crm.item.add, используют camelCase — title, stageId, entityTypeId
• более ранние методы, например crm.deal.add, используют верхний регистр с подчеркиваниями — TITLE, STAGE_ID

Универсальные методы crm.item.* принимают и названия в верхнем регистре с подчеркиваниями, но полагаться на это не стоит.

Методы CRM из обеих групп относятся к прежней версии API и игнорируют незнакомое название поля в fields: значение такого поля не сохранится, а ошибки из-за него не будет. Методы REST 3.0 на такое поле вернут ошибку.

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

Сначала проверьте, не помечен ли метод как устаревший. На странице такого метода указана замена, используйте ее.

Раздел Ошибки и диагностика статьи о первом запросе разбирает общие ошибки вызова, например неверный адрес вебхука или нехватку scope. При запуске примеров чаще встречаются такие ошибки:

Остальные коды собраны в статье Коды ошибок.

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

• Как выполнить свой первый запрос к API
• Как выполняется запрос
• Как выполнить пакет запросов batch
• SDK для разработки под Битрикс24
• Туториалы: готовые сценарии использования REST API