API Битрикс24: с чего начать и как проверить первый запрос
Сначала проверьте, доступен ли REST API на вашем портале и от чьего имени пойдёт запрос. Для первой проверки подойдёт метод profile, который не меняет данные.
«Подключиться к API» часто означает две разные задачи. Администратор хочет один раз выгрузить данные своего портала. Разработчик готовит приложение, которое будут устанавливать другие компании. Оба отправляют запросы к REST API Битрикс24, но получают доступ разными способами. Начать удобнее с простого запроса чтения, чтобы увидеть, где именно возникает отказ.
Что даёт REST API Битрикс24
Программа отправляет HTTP-запрос к методу Битрикс24 и получает ответ. Конкретный метод определяет действие: прочитать карточку, получить список или изменить запись. Для выполнения нужны авторизация и параметры метода. Доступность результата зависит от тарифа, полномочий пользователя, выданных scope и правил самого метода.
Перед выбором авторизации запишите один ожидаемый результат. Например: «Получить названия полей сделки, чтобы составить карту импорта». Для такой задачи полезно открыть разбор кодов полей CRM и страницу выбранного метода в официальном справочнике. Не начинайте проверку с удаления или массовой записи данных.
Вебхук или приложение: как выбрать
Входящий вебхук подходит для быстрой проверки и внутренней интеграции с одним порталом. Запрос выполняется с правами сотрудника, который создал вебхук, и в пределах выбранных scope. У приложения с OAuth 2.0 другая модель установки и временные токены; этот путь используют для решений, работающих на разных порталах или от имени разных пользователей.
| Ситуация | Способ | Что учесть |
|---|---|---|
| Проверить метод или связать одну внутреннюю систему с одним порталом | Входящий вебхук | Постоянный секрет в URL; запрос идёт от имени создателя |
| Установить решение на разные порталы или работать от имени разных пользователей | Приложение с OAuth 2.0 | Токены, установка и нужные scope приложения |
Входящий вебхук вызывает метод API. Исходящий вебхук решает другую задачу: Битрикс24 отправляет событие внешнему обработчику. Смешение направлений часто приводит к неверному выбору инструмента.
Когда сотруднику нужен экран приложения прямо в карточке сделки, проверьте точки встраивания в CRM и права для вкладки.
Как проверить первый запрос
Официальная инструкция предлагает метод profile: он работает без параметров и отдельного scope. В разделе «Разработчикам» откройте «Готовые сценарии → Другое → Входящий вебхук», затем используйте генератор запросов. При успешном вызове в result придут данные пользователя, создавшего вебхук. Секретный URL не вставляйте в публичный документ или чат.
Назовите задачу
Например, прочитать поля одной сделки. Выберите метод по результату, который нужен, а не по похожему названию.
Проверьте доступ к REST API
Тариф и подписка определяют доступность REST. Затем проверьте право пользователя создать вебхук.
Сделайте безопасную первую проверку
В генераторе входящего вебхука вызовите profile. Метод не изменяет данные и не требует отдельного scope.
Перейдите к нужному методу
На его странице уточните параметры и scope. Проверьте права пользователя на объект и результат на тестовых данных.
Успешный profile подтверждает авторизацию этого вебхука. Чтобы прочитать CRM, потребуется отдельный метод со scope crm и правами пользователя на нужную запись. Если запрос вернул лишь часть списка, проверьте пагинацию и фильтр до вывода о полноте данных. Для сопоставления полей разных систем пригодится карта соответствия.
Если запрос не прошёл
У методов прежней версии REST API отказ обычно описан полями error и error_description. Читайте оба: один и тот же общий код доступа может относиться к правам пользователя или к недоступной подписке. В новых версиях API формат ошибок может отличаться; ориентируйтесь на страницу конкретного метода.
| Ответ | Вероятная причина | Что проверить |
|---|---|---|
| insufficient_scope | У вебхука нет scope для метода | Сверить scope на странице метода и настройки вебхука |
| ACCESS_DENIED | Проверить права пользователя; при сообщении о подписке — доступ к REST API | Прочитать error_description и проверить соответствующее условие |
| ERROR_METHOD_NOT_FOUND | Метод не найден | Сверить имя со справочником методов |
Если пункт создания вебхука отсутствует, администратор может проверить право сотрудника на его создание. Если вместо формы появилось сообщение о тарифе, проверьте доступ к REST API. Для ошибки уже выбранного метода сначала уточните его scope и права пользователя, а затем параметры запроса.
После первого ответа: одна рабочая операция
Проверьте один метод чтения на тестовой записи. Сохраните имя метода, нужные поля, права исполнителя и ожидаемый ответ без секрета вебхука. Если интеграция будет работать постоянно, определите способ хранения ключа на сервере и порядок его замены. Для приложения добавятся установка, выдача scope и обновление OAuth-токенов.
Мы используем API Битрикс24 и в разработке MCP TrueTell для разрешённых сценариев работы ИИ с CRM. Готовность конкретного клиента и открытая установка здесь не заявлены. Если задача связана с ИИ, заранее определите, какие записи агент вправе читать и как человек проверит ответ. Подробности — в статье о доступе ИИ к CRM.
Частые вопросы об API Битрикс24
Можно ли сделать первый запрос к API Битрикс24 без программы?
Да. В разделе создания входящего вебхука есть генератор запросов. Метод profile проверяет авторизацию без параметров и без отдельного scope. Для рабочей интеграции всё равно нужно выбрать способ доступа и проверить права.
Успешный profile означает, что интеграция прочитает сделки?
Нет. profile подтверждает работу вебхука и показывает пользователя, от имени которого прошёл запрос. Доступ к сделкам зависит также от тарифа, scope crm, прав этого пользователя и условий выбранного метода.
Когда вместо вебхука нужно приложение?
Если решение устанавливается на разные порталы или должно работать от имени разных пользователей, изучите приложение с OAuth 2.0. Отдельные методы требуют контекста приложения и через входящий вебхук недоступны.
Почему метод вернул ошибку при верном адресе?
Проверьте точное имя метода, доступность REST API на тарифе, выбранный scope и права пользователя на объект. У методов прежней версии API код и пояснение ошибки обычно приходят в error и error_description.
Документация проверена 30 октября 2026 года. Вызовы на клиентском портале для этой статьи не выполнялись; доступность методов и тарифа проверяйте в своём Битрикс24.