Bitrix24 REST API: документация по методам, OAuth и BX24.callMethod на практике

Что такое REST API Битрикс24 и как устроен вызов метода

Когда к нам приходят с задачей «подружить» внешнюю систему с Битрикс24 — телефонию, сайт-каталог, собственную админку или выгрузку из 1С — первое, что мы объясняем заказчику: REST API Битрикс24 это не отдельный сервис, не SDK и не библиотека. Это набор методов, доступных по обычному HTTP-запросу. Никакой «магии»: тот же транспорт, что у любого веб-хука, любой формы, любого curl-запроса. Поэтому API работает из кода на любом языке веб-разработки и в большинстве традиционных языков программирования — PHP, Python, Go, Node.js, да хоть из bash-скрипта.

Имя метода описывает сразу две вещи: область функциональности и операцию. Смотрите: crm.lead.add — это CRM, сущность «лид», действие «добавить». crm.deal.list — CRM, сделки, получить список. user.get — пользователи, получить данные. task.item.add — задачи, элемент, создать. Такая нотация читается с первого взгляда, и по ней же удобно искать нужный метод в документации: сначала область, потом операция.

Чтобы вызвать метод, нужны всего четыре вещи: домен портала, имя метода, параметры и access_token. Никаких WSDL, SOAP-конвертов и сложной сериализации. Параметры уходят как обычный POST. В проектах, где мы делали интеграции с коробочными порталами, это же правило работает без изменений: меняется только домен.

Посмотрим на сырой запрос — так понятнее, что никакой прослойки между вами и API нет.

curl -X POST \
"https://mycompany.bitrix24.ru/rest/crm.deal.list" \
-H "Content-Type: application/json" \
-d '{
"SELECT": ["ID", "TITLE", "STAGE_ID", "OPPORTUNITY"],
"FILTER": {"STAGE_ID": "NEW"},
"auth": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}'

Разберём построчно. https://mycompany.bitrix24.ru — это домен портала, тот самый, куда вы логинитесь в браузере; в коробке он будет свой, в облаке — вида *.bitrix24.ru. Дальше /rest/crm.deal.list — путь, где rest это точка входа REST-сервиса, а crm.deal.list — имя метода. Имя метода в URL не разбирается на части сервером «на лету»: оно зарегистрировано целиком, и переиспользовать его нельзя. Если пишете свой модуль с методом, занять уже существующее имя вроде crm.deal.list не получится — это чужое пространство.

Параметры (SELECT, FILTER) уходят телом POST-запроса. У каждого метода свой набор параметров и свои значения по умолчанию, поэтому перед вызовом стоит открыть документацию по конкретному методу, а не угадывать. Токен auth — это тот самый access_token из OAuth-авторизации. Без него сервер ответит ошибкой авторизации, даже если метод и домен указаны верно.

У нас на проектах домен и токен обычно лежат в конфиге, а имя метода остаётся в коде вызова. При переносе с облака на коробку меняется одна переменная окружения, а не сотня мест в коде. Если метод вызывается регулярно, токен удобнее хранить в отдельном сервисе-обёртке, который сам следит за его актуальностью — об этом ниже, в разделе про OAuth.

OAuth Битрикс24: как получить access_token и refresh_token

Самый частый запрос на эту тему звучит так: «приложение зарегистрировали, права отметили, а токена нет». OAuth 2.0 — открытый стандарт авторизации, который даёт приложению ограниченный доступ к данным пользователя без передачи пароля. В Битрикс24 он работает одинаково и для локальных приложений, и для приложений Маркетплейса: разница только в том, где вы регистрируете приложение и как получаете первые данные для обмена.

Регистрация начинается в разделе «Разработчикам»: вы создаёте приложение, указываете URL обработчика — адрес, на который Битрикс24 будет присылать авторизационный код, — и отмечаете нужные права. Права (scope) определяют, что приложение вообще сможет делать: crm, задачи, диск, бизнес-процессы, размещения и другие разделы. Если право не отмечено, метод вернёт ошибку доступа, даже когда токен валиден.

Дальше всё идёт по стандартной схеме OAuth: приложение получает access_token для вызовов REST API и refresh_token для продления доступа. Именно этой паре и посвящена секция — как её получить, что означают поля ответа и где легко ошибиться.

Какие поля возвращает сервер авторизации

Сервер авторизации отвечает JSON-объектом — набор полей фиксирован, и каждое из них пригодится в коде. Ниже матрица полей ответа: что означает каждое значение и как его использовать.

Как получить первую пару токенов

Первую пару токенов приложение получает в обмен на авторизационный код code, который Битрикс24 присылает на URL обработчика. Обмен идёт обычным HTTP-запросом к серверу авторизации с параметром grant_type=authorization_code. Ниже рабочий пример на bash — его удобно прогнать вручную, чтобы увидеть реальный ответ до того, как заворачивать это в PHP-класс.

curl -X POST "https://oauth.bitrix.info/oauth/token/" \
-d "grant_type=authorization_code" \
-d "client_id=local.5f8a1c9d2e3b7a4f6c0d1e2f3a4b5c6d" \
-d "client_secret=ВАШ_CLIENT_SECRET" \
-d "code=Код_из_параметра_callback" \
-d "scope=crm,task,disk"
# В ответе придут access_token, refresh_token, expires_in, scope, domain

Ключевое здесь — параметр code: он одноразовый и привязан к конкретной попытке авторизации. Место, которое читатель захочет поменять под свой проект, — набор scope: перечислите там ровно те права, что отметили при регистрации. Если приложение коробочное, обращаетесь к реальному серверу авторизации напрямую по адресу oauth.bitrix.info/oauth/token/, потому что коробочный Битрикс24 может не «прокидывать» запрос через себя.

Авторизационный код code живёт всего 30 секунд. Не успели обменять его на пару токенов — начинать придётся заново, с новой авторизации: повторно использовать тот же code нельзя. Поэтому обмен кода делайте сразу в обработчике callback, а не откладывайте в очередь.

BX24.callMethod: примеры вызова методов из JS-приложения

Если приложение рисует свой интерфейс прямо внутри Битрикс24 — карточку сделки, вкладку в лиде, слайдер в таймлайне — REST удобнее всего вызывать из браузера через BX24.callMethod(). Этот путь выбирают в большинстве наших проектов с JS-приложениями: SDK сам подхватывает токен, обновляет его при необходимости и подставляет домен портала. Разработчику не нужно вручную собирать OAuth-цепочку, о которой мы говорили в предыдущей секции.

Сигнатура метода: BX24.callMethod(String method, Object params[, Function callback]). Первый аргумент — имя REST-метода строкой, второй — ассоциативный массив параметров, который библиотека преобразует в строку POST-запроса, третий (необязательный) — функция-колбэк, куда придёт результат или ошибка. bx24.js берёт на себя всю авторизацию, если приложение встроено в интерфейс Битрикс24. Тот же вызов извне портала работать «из коробки» не будет — об этом ниже. Для бот-платформы документация допускает три равнозначных варианта: свою функцию-обёртку, тот же BX24.callMethod или bitrix24-php-sdk на серверной стороне.

BX24.callMethod(
    'crm.deal.list', {
        select: ['ID', 'TITLE', 'OPPORTUNITY', 'STAGE_ID'],
        filter: {
            '>OPPORTUNITY': 10000
        },
        order: {
            'OPPORTUNITY': 'DESC'
        }
    },
    function(result) {
        if (result.error()) {
            console.error('REST error:', result.error(), result.error_description());
            return;
        }
        var deals = result.data();
        deals.forEach(function(deal) {
            console.log(deal.ID, deal.TITLE, deal.OPPORTUNITY);
        });
        // Пагинация: если есть следующая страница — запрашиваем её
        if (result.next()) {
            result.next();
        }
    }
);

Что делать, если приложение не встроено в Битрикс24

Вне встройки bx24.js не подходит: библиотеке неоткуда взять контекст портала и токен. Здесь у нас два рабочих пути. Первый — серверная интеграция через bitrix24-php-sdk: он сам хранит и обновляет пару токенов, а вызовы методов выглядят почти так же лаконично, как в JS. Второй — своя обёртка над OAuth: получаете токен, сохраняете, перед каждым запросом проверяете срок и при необходимости обновляете через refresh_token.

Второй вариант даёт полный контроль, но требует аккуратной работы с состоянием. Именно на этом этапе чаще всего ломаются самописные интеграции.

BX24Wrapper и async callMethod()

В сообществе встречается и промежуточный JS-подход — обёртки вроде BX24Wrapper с асинхронным методом callMethod(), который возвращает промис вместо колбэка. Это удобно, когда код уже написан на async/await, но мы помечаем такой вариант как практику сообщества, а не норму: официальный SDK работает на колбэках, и в проектах, которые мы сопровождаем, сторонние обёртки добавляют слой, о котором забывают при обновлении. Если команда готова поддерживать эту зависимость — берите; если нет — пишите свой промис поверх колбэка в пять строк.

// Приложение Маркетплейса, встроенное в интерфейс Битрикс24.
// BX24.placement.info отдаёт данные о текущем месте встройки:
// куда именно открыт слайдер и какие параметры передал портал.
BX24.placement.info(function(result) {
    if (result.error()) {
        console.error('placement.info error:', result.error());
        return;
    }
    var info = result.data();
    console.log('Placement:', info.placement, 'Options:', info.options);

    // Типичный сценарий: по placement решаем, что рисовать
    if (info.placement === 'CRM_DEAL_DETAIL_TAB') {
        loadDealContext(info.options.ID);
    }
});

function loadDealContext(dealId) {
    BX24.callMethod('crm.deal.get', {
        id: dealId
    }, function(res) {
        if (res.error()) {
            console.error(res.error());
            return;
        }
        renderDealPanel(res.data());
    });
}

REST API Битрикс24 методы: как читать имя и где искать нужный

Типичный сценарий: разработчик открывает документацию Битрикс24, видит десятки разделов и не понимает, с какого метода начинать. Половину поиска заменяет одно правило — имя метода читается как «область.операция». Слева от точки стоит функциональный блок (crm, user, task, calendar), справа — действие (add, get, update, list, delete). Как только вы это усвоили, crm.lead.add перестаёт быть абстракцией: это добавление лида в CRM, а crm.deal.list — выборка списка сделок.

Схема работает не только в CRM. user.current возвращает текущего пользователя, task.item.add создаёт задачу, calendar.event.get тянет событие календаря. Даже в сервисных модулях вроде messageservice.* логика та же: сначала область, потом операция. В наших проектах мы сначала проговариваем имя метода вслух. Если оно не складывается в осмысленную фразу, скорее всего, вы смотрите не туда.

Когда схема «область.операция» усвоена, по имени метода можно предсказать и поведение, и набор параметров. Метод с суффиксом add почти всегда ждёт объект с полями сущности, get — идентификатор, list — фильтр и пагинацию. Перед первым вызовом мы обычно сверяемся с *.fields: там перечислены типы, ограничения и допустимые значения. Проще говоря, ровно то, что метод вернёт вам в ошибке, если вы угадали неправильно.

Отдельно про переиспользование имён. Имя REST-метода в интеграции нельзя занять «своим» смыслом: это не неймспейс вашего кода, а глобальное пространство платформы. Если вы напишете обёртку crm.deal.list со своей логикой и однажды Битрикс24 поменяет поведение метода, вы получите несовпадение ожиданий на ровном месте. Свои методы регистрируются через OnRestServiceBuildDescription — об этом ниже, в отдельной секции.

Полный перечень методов в статье мы не приводим сознательно: он живёт в официальной документации и меняется чаще, чем обновляется любая статья. Здесь — только схема чтения имени и рабочие точки входа.

Есть четыре способа найти нужный метод, которыми мы пользуемся по очереди:

• Поиск по официальной документации по названию области — если знаете, что задача про CRM, начинайте с раздела crm.*.
• crm.deal.fields — отдаёт полное описание полей сделки: стандартных и пользовательских, с типами и допустимыми значениями.
• crm.deal.userfield.list — если нужны именно пользовательские поля, этот метод покажет их отдельно, без шума стандартных.
• Чтение имени по схеме область.операция — когда область известна, а операция нет, переберите add, get, update, list, delete в голове.

Документация по REST API Битрикс24: что реально описано, а что нет

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

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

Ниже — что реально зафиксировано в источниках, а что приходится проверять эмпирически.

Как с этой неопределённостью работать на живом проекте? У нас сложилось три правила. Первое: не строить логику на точных сроках. Если в архитектуре зашито «refresh_token живёт ровно 30 дней, обновляем на 29-й», при расхождении источников интеграция отвалится. Правильнее обновлять токен по факту ошибки авторизации, а не по календарю. Второе: формат ответа проверять эмпирически — сделать тестовый вызов, залогировать сырой JSON и уже по нему писать парсер. Третье: для коробочного Битрикс24 держать fallback на реальный сервер авторизации oauth.bitrix.info — коробка не всегда «прокидывает» запрос, и это описано в документации, но на практике всплывает неожиданно.

По методам ситуация мягче: имена вроде crm.deal.list или user.current читаются интуитивно, как мы разбирали выше, — область и операция прямо в названии. Но полагаться на догадку по имени в проде нельзя: метод может существовать, а может быть только в новых версиях модуля.

Как добавить свой метод в REST API через OnRestServiceBuildDescription

Бывает так: задача вроде бы типовая, но готового REST-метода под неё нет. Нужно отдать наружу расчёт доставки по своей логике, отфильтровать лиды по кастомному правилу или вернуть агрегат из нескольких сущностей одним запросом. Штатный способ расширить REST API Битрикс24 своими методами — подписка на событие OnRestServiceBuildDescription. Через него платформа собирает карту доступных REST-методов, и мы можем добавить туда свои.

В качестве фильтра используется метод RestApi::prepareEventData — он позволяет не обрабатывать событие вслепую, а работать с подготовленными данными. Этот приём нужен именно тогда, когда готовых методов не хватает под бизнес-логику: не «обойти ограничение», а легально расширить API своим методом, который затем вызывается как обычный REST-метод по HTTP с доменом и access_token.

Читать код стоит с двух точек. Первая — где описывается имя метода: ключ массива mystudio.delivery.calc — именно то, что клиент передаст в запросе. Вторая — где область и колбэк: имя строится по схеме область.сущность.действие, а значение callback указывает, какой метод PHP вызовется. Возвращаемое значение колбэка — это то, что уйдёт в ответ REST.

Что вы захотите поменять под свой проект: префикс области (у нас mystudio — замените на свой), набор параметров и логику внутри колбэка. Если методов несколько — просто добавляйте ключи в тот же массив. Если нужен метод только для авторизованных — проверяйте права внутри колбэка.

Важная оговорка: полный список аргументов и возвращаемого значения события OnRestServiceBuildDescription в доступных источниках не зафиксирован. Сигнатуру prepareEventData мы тоже не нашли описанной явно. Поэтому проверяйте поведение на своей версии платформы — облако и коробка могут отличаться, а между релизами детали меняются.

Что учесть при интеграции Битрикс24 с 1С и внешними системами

REST API Битрикс24 — это транспорт, а не бизнес-логика. Метод crm.deal.add примет данные и вернёт ID, но он не знает, что у вас в 1С та же сделка называется «Заказ покупателя», что сумма хранится в копейках, а контрагент обязан быть привязан к компании. В проектах с 1С и внешними системами поверх REST мы всегда строим отдельный слой синхронизации: маппинг полей, идемпотентность, обработка ошибок, ретраи. Это не «дописать пару строк в обмен» — это самостоятельный кусок работы, который нельзя пропустить, иначе интеграция развалится на первом же расхождении справочников.

Когда к нам приходят с задачей «связать 1С и портал», половина времени уходит именно на этот слой, а не на вызовы REST. Ниже — порядок, по которому мы его собираем.

1. Определить область синхронизации: crm (сделки, контакты, компании), tasks (задачи), catalog (товары) — и зафиксировать, что именно едет в каждую сторону.
2. Зарегистрировать приложение и отметить нужные права (scope) — лишние права не запрашивать, они расширяют поверхность отказа.
3. Получить токены и сохранить пару access_token + refresh_token в защищённом хранилище, а не в коде.
4. Реализовать слой маппинга: таблица соответствия полей 1С ↔ Битрикс24, включая пользовательские поля из crm.deal.fields.
5. Настроить логирование каждого вызова и ретраи с задержкой для сетевых ошибок и лимитов.

Соблазн вызвать crm.deal.add прямо из обработчика 1С понятен — код короче. Но тогда вся логика синхронизации живёт внутри 1С: обновление схемы сделки требует правки на стороне учётной системы, ошибки REST теряются в журнале регистрации, а повторный запуск обмена создаёт дубли. Мы разделяем роли: 1С отдаёт данные, REST-слой решает, что с ними делать. Если обмен идёт через модуль «1С-Битрикс» на стороне портала — комбинируйте: штатный обмен закрывает каталог и заказы, а REST добивает то, чего в нём нет (например, кастомные поля сделки или задачи по заказу). Токены храните в переменных окружения или в отдельной таблице с ограниченным доступом — репозиторий и init.php для этого не годятся. Подробнее про хранение и обновление токенов — в секции про OAuth выше.

Самые частые ошибки при работе с REST API Битрикс24

За годы практики мы собрали небольшой «топ» грабель, на которые наступает почти каждый, кто впервые подключает приложение к Битрикс24 через REST. Характерная черта этих ошибок — они выглядят как «API сломался», хотя ломается интеграция: не тот токен, не тот scope, не тот сервер авторизации. Разберём матрицу «грабля → причина → что делать», а потом покажем, как по одному ответу сервера быстро понять, где искать.

Почему всё это выглядит как «API не работает»? Потому что сервер отвечает коротко и формально — invalid_grant, insufficient_scope, method not found, — а разработчик читает это как отказ самого REST. На деле ни один из этих ответов не про API: они про то, как приложение получило доступ.

Локализуется проблема быстро, если смотреть на что именно вернул сервер:

• invalid_grant на этапе обмена code — почти всегда истёкшие 30 секунд или повторный обмен уже использованного кода.
• insufficient_scope при вызове метода — приложению не выданы права на этот раздел, а не «метод сломан».
• Пустой ответ на коробке — запрос до сервера авторизации просто не дошёл, проверяйте сеть и адрес.
• method not found — либо опечатка в имени, либо метода действительно нет в этом scope.

Разделять «ошибку API» и «ошибку интеграции» — привычка, которая экономит часы. Первое лечится ожиданием или обращением в поддержку, второе — правкой кода и настроек приложения.

Короткий чеклист перед запуском интеграции на REST API Битрикс24

Перед тем как отдать интеграцию клиенту, мы прогоняем её по одному и тому же списку. Неважно, локальное это приложение, тиражное или кастом под конкретный портал. Список появился не из теории: каждый пункт закрывает грабли, на которые мы уже наступали. Проверяем шесть вещей: приложение зарегистрировано и права выданы, URL обработчика прописан, токены не лежат в репозитории, refresh_token реально обменивается, вызовы логируются, повторные отправки защищены мьютексом. Ниже сам чеклист и объяснение, что ломается, если пункт пропустить.

• Приложение зарегистрировано — в разделе «Разработчикам» создано локальное приложение, известны его client_id и client_secret.
• Права выданы — отмечены ровно те scope, которые нужны (crm, задачи, диск, бизнес-процессы), без «на всякий случай».
• URL обработчика указан — совпадает с реальным адресом на проде, доступен по HTTPS и не редиректит.
• Токены хранятся вне репозитория - access_token и refresh_token в БД или секретах окружения, не в config.php под git.
• Реализован обмен refresh_token — при истечении access_token приложение само получает новую пару и продолжает работу без ручного вмешательства.
• Есть логирование вызовов — пишем метод, параметры, код ответа и тело ошибки, чтобы разбирать инциденты постфактум.
• Есть ретраи — сетевые сбои и 5xx повторяются с задержкой, а не роняют весь обмен.
• Есть мьютекс на повторные отправки — параллельный запуск агента или повторный вебхук не создадут дубли сделок и задач.

Каждый пункт закрывает свой класс отказов. Без регистрации и прав запрос вернёт ошибку авторизации, и её видно сразу. Это дешёвый сбой. Дороже, когда URL обработчика на проде отличается от того, что прописан в настройках приложения: OAuth-редирект уходит в никуда, и токен не приходит. Хранение токенов в репозитории обернётся утечкой доступа ко всему порталу при первом же утёкшем бэкапе. Отсутствие обмена refresh_token даёт классическую картину: интеграция работает неделю, потом молча умирает. Логирование и ретраи — про наблюдаемость. Без них сетевой сбой выглядит как «ничего не пришло», и искать причину негде. Мьютекс — про идемпотентность: агент по расписанию и вебхук могут сработать одновременно.

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

Подробнее об услуге: внедрение и доработка Битрикс24 CRM.

Читайте также: Массовое редактирование задач Битрикс24 через REST API: полный гайд, Отправка форм с сайта Битрикс в Битрикс24 через init.php: события, кастомные поля, лиды и сделки.