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

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

Ниже описано, как выбрать вкладку под свою среду, что подставить вместо меток вида **put_your_webhook_here** и какой код добавить, чтобы пример заработал. После прочтения вы сможете взять любой пример со страницы метода и выполнить его в своем проекте.

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

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

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

Подписи вкладок оформлены не везде одинаково. Учитывайте варианты:

• вкладка с примером на B24JsSDK может называться просто JS
• примера на B24PhpSDK может не быть — тогда используйте CRest или соберите вызов по описанию параметров метода

Ориентируйтесь не только на подпись, но и на код. У B24PhpSDK вызовы идут через $b24Service или $serviceBuilder, у CRest — через CRest::call, у BX24.js — через BX24.callMethod, у B24JsSDK — через $b24.

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

Если подходят несколько SDK, сравните их в обзоре SDK.

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

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

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

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

Примеры на вкладках cURL (Webhook) и cURL (OAuth) не требуют установки. Достаточно заменить метки на свои значения.

Упрощенный пример по образцу вкладки cURL (Webhook) со страницы метода crm.item.add — набор полей сокращен до одного:

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
        

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

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

Часть примеров подключение уже содержит — дублировать его не нужно:

• JS (UMD) — готовая HTML-страница целиком, вместе с тегом script и созданием $b24
• PHP CRest — строка require_once('crest.php') обычно уже стоит в примере, от вас нужны только файлы SDK на сервере и заполненный settings.php
• JS — изредка попадаются самодостаточные примеры с созданием $b24

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

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

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

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

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

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

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

Если пример не работаетЕсли пример не работает

Проверьте по порядку:

1. Метод помечен как DEPRECATED. На странице метода указана актуальная замена — используйте ее
2. Приложению не выдан scope. Нужный scope указан в начале страницы метода, список значений — в справочнике Доступные скоупы Битрикс24
3. Пользователю не хватает прав. Запрос выполняется от имени того, чьи авторизационные данные использованы: для вебхука — создателя вебхука, для приложения — владельца токена, обычно пользователя, который открыл приложение
4. Ошибка в структуре параметров. Правила передачи массивов и вложенных структур описаны в статьях Как выполняется запрос и Кодирование данных
5. Слишком много запросов. Ограничения на частоту вызовов описаны в статье Лимиты REST API

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

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