REST API Битрикс24: основы для разработчика

Что такое REST API Битрикс24

REST API — это программный интерфейс для работы с Битрикс24. Через него можно создавать/обновлять сущности (контакты, сделки, задачи), получать списки, управлять пользователями, запускать бизнес-процессы.

Любая интеграция Битрикс24 со сторонними системами (сайт, телефония, 1С, Telegram-боты, кастомные приложения) идёт через REST API.

Способы аутентификации

1. Входящие вебхуки. Самый простой. Создаётся в админке Битрикс24, выдаётся URL вида https://portal.bitrix24.ru/rest/USER_ID/SECRET/. Прямые вызовы методов через этот URL. Подходит для серверных скриптов и единичных интеграций.

2. Исходящие вебхуки. Битрикс отправляет HTTP-запросы при событиях (создание сделки, добавление задачи). Используется для callback в внешние сервисы.

3. Локальные приложения (приложения для портала). Регистрируются в админке. Получают токен через OAuth. Подходят для приложений, развёрнутых на сторонних серверах для конкретного портала.

4. Тиражируемые приложения (OAuth 2.0). Для приложений, продаваемых через Маркетплейс Битрикс24 — устанавливаются на разные порталы.

Базовый запрос через входящий вебхук

POST https://portal.bitrix24.ru/rest/1/abc123secret/crm.deal.add.json
Content-Type: application/json

{
  "fields": {
    "TITLE": "Новая сделка",
    "STAGE_ID": "NEW",
    "OPPORTUNITY": 100000
  }
}

Ответ:

{
  "result": 12345,
  "time": { ... }
}

Структура методов

Методы группируются по сущностям:

• crm.deal.* — сделки
• crm.contact.* — контакты
• crm.company.* — компании
• crm.lead.* — лиды
• tasks.task.* — задачи
• im.message.add — сообщения в чаты
• user.get — пользователи
• im.notify.system.add — системные уведомления

Полный список — в официальной документации.

Типовые операции

Создать сущность: crm.deal.add — передаём fields, получаем ID.

Обновить: crm.deal.update — передаём ID и fields.

Получить одну: crm.deal.get — передаём ID, получаем все поля.

Получить список: crm.deal.list — передаём filter, select, order.

Удалить: crm.deal.delete.

Списки и пагинация

API возвращает максимум 50 элементов за запрос. Для больших выборок — пагинация через параметр start:

{
  "filter": { ">DATE_CREATE": "2025-01-01" },
  "select": ["ID", "TITLE", "OPPORTUNITY"],
  "order": { "DATE_CREATE": "DESC" },
  "start": 0
}

В ответе будет next — значение для start следующего запроса, или его не будет, если выборка закончилась.

Batch-запросы

Когда нужно сделать много операций — отправлять каждый отдельным запросом долго. batch позволяет в одном запросе сделать до 50 операций:

POST /rest/batch.json
{
  "halt": 0,
  "cmd": {
    "deal1": "crm.deal.get?id=1",
    "deal2": "crm.deal.get?id=2",
    "newDeal": "crm.deal.add?fields[TITLE]=test"
  }
}

Можно ссылаться на результаты предыдущих команд через $result.

Обработка ошибок

API возвращает HTTP 200 даже при ошибках. Проверять нужно по полю error в JSON ответа:

{
  "error": "ACCESS_DENIED",
  "error_description": "Action not allowed"
}

Типичные ошибки: ACCESS_DENIED (нет прав), ERROR_CORE (сервер), QUERY_LIMIT_EXCEEDED (превысили лимит запросов).

Лимиты

• 2 запроса в секунду на портал (мягкий лимит)
• 50 операций в одном batch
• Максимум 50 элементов в списках
• Дневные лимиты на тарифах (на бесплатном — строже)

Для интенсивных интеграций нужны паузы и обработка превышения лимитов.

Лучшие практики

• Хранить URL вебхука в защищённом конфиге (не в коде)
• Логировать все запросы и ответы
• Обрабатывать ошибки с retry-логикой
• Использовать batch везде, где можно
• Кэшировать справочные данные (статусы, пользователи)

SDK

Чтобы не работать с raw HTTP, есть SDK:

• PHP — официальный CRest от Битрикс24
• Python — pyrus_b24, b24sdk
• Node.js — bitrix24-rest, b24-rest-client

Сколько стоит интеграция

Простая интеграция (например, форма с сайта → лид в CRM): 15 000–50 000 ₽. Срок 1–3 недели.

Сложная (двусторонний обмен с 1С, кастомная логика): 100 000–500 000 ₽. Срок 1–3 месяца.

Рассчитать →   Записаться на разбор →

FAQ

Что выбрать для своего проекта: вебхук или приложение?

Для разовой интеграции на одном портале — входящий вебхук. Для приложения, которое будет устанавливаться на разные порталы — OAuth-приложение.

Можно ли работать с Битрикс24 коробкой?

Да, REST API работает и в коробке, и в облаке.