Bitrix24 REST API - Документация

🚀 Введение

Добро пожаловать в документацию Bitrix24 REST API! Наш API позволяет разработчикам создавать мощные интеграции с платформой Bitrix24, автоматизировать бизнес-процессы и расширять функциональность системы.

Базовый URL: https://your-domain.bitrix24.com/rest

Быстрый старт

1. Получите токен

Зарегистрируйте приложение и получите access_token для доступа к API

2. Сделайте запрос

Используйте REST для взаимодействия с данными вашего портала

3. Обработайте ответ

Получите данные в формате JSON и интегрируйте их в ваше приложение

Основные возможности

Управление пользователями и группами
Работа с CRM: лиды, контакты, компании, сделки
Создание и управление задачами
Интеграция с календарем и событиями
Работа с документами и файлами
Webhooks для получения уведомлений в реальном времени

🔐 Аутентификация

Bitrix24 API использует OAuth 2.0 для аутентификации. Все запросы должны содержать действительный access token.

Получение токена

POST /oauth/token/

Параметры запроса:

Параметр	Тип	Обязательный	Описание
grant_type	string	Да	Тип авторизации: "authorization_code"
client_id	string	Да	ID вашего приложения
client_secret	string	Да	Секретный ключ приложения
code	string	Да	Код авторизации

Пример запроса:

curl -X POST https://your-domain.bitrix24.com/oauth/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "code": "authorization_code"
  }'

Пример ответа:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1f2b3c4d5e6f7g8h9i0j1k2l3...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Важно: Access token действителен в течение 1 часа. Используйте refresh_token для получения нового токена.

Использование токена

Включайте access token в каждый запрос через заголовок Authorization:

Authorization: Bearer your_access_token

👥 Пользователи

API для работы с пользователями портала.

Получить список пользователей

GET /user.get

Параметры запроса:

Параметр	Тип	Описание
filter	object	Фильтр для отбора пользователей
start	integer	Смещение для пагинации
limit	integer	Количество записей (максимум 50)

Пример запроса:

curl -X GET "https://your-domain.bitrix24.com/rest/user.get?limit=10" \
  -H "Authorization: Bearer your_access_token"

Пример ответа:

{
  "result": [
    {
      "ID": "1",
      "NAME": "Иван",
      "LAST_NAME": "Петров",
      "EMAIL": "ivan@example.com",
      "PERSONAL_PHONE": "+7 (123) 456-78-90",
      "UF_DEPARTMENT": [1, 3],
      "ACTIVE": true,
      "DATE_REGISTER": "2024-01-15T10:30:00+03:00"
    }
  ],
  "total": 45,
  "time": {
    "start": 1702901234.567,
    "finish": 1702901234.789,
    "duration": 0.222
  }
}

Получить текущего пользователя

GET /user.current

Добавить пользователя

POST /user.add

Тело запроса:

{
  "NAME": "Мария",
  "LAST_NAME": "Иванова",
  "EMAIL": "maria@example.com",
  "PERSONAL_PHONE": "+7 (987) 654-32-10",
  "UF_DEPARTMENT": [2],
  "PASSWORD": "SecurePassword123!"
}

Обновить пользователя

PUT /user.update

Удалить пользователя

DELETE /user.delete

💼 CRM

Работа с лидами, контактами, компаниями и сделками.

Лиды (Leads)

GET /crm.lead.list

POST /crm.lead.add

PUT /crm.lead.update

Пример создания лида:

curl -X POST https://your-domain.bitrix24.com/rest/crm.lead.add \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "TITLE": "Новый клиент из веб-формы",
      "NAME": "Алексей",
      "LAST_NAME": "Смирнов",
      "EMAIL": [{"VALUE": "alexey@example.com", "VALUE_TYPE": "WORK"}],
      "PHONE": [{"VALUE": "+7 (999) 888-77-66", "VALUE_TYPE": "MOBILE"}],
      "SOURCE_ID": "WEB",
      "OPPORTUNITY": 50000,
      "CURRENCY_ID": "RUB",
      "ASSIGNED_BY_ID": 1
    }
  }'

Ответ:

{
  "result": 123,
  "time": {
    "start": 1702901234.567,
    "finish": 1702901234.789,
    "duration": 0.222
  }
}

Контакты (Contacts)

GET /crm.contact.list

POST /crm.contact.add

Компании (Companies)

GET /crm.company.list

POST /crm.company.add

Сделки (Deals)

GET /crm.deal.list

POST /crm.deal.add

Фильтры для CRM:

Оператор	Описание	Пример
=	Равно	{"ASSIGNED_BY_ID": 1}
!=	Не равно	{"!STATUS_ID": "LOSE"}
>	Больше	{">OPPORTUNITY": 10000}
<	Меньше	{"
%	LIKE	{"%TITLE": "клиент"}

✅ Задачи

Создание и управление задачами в Bitrix24.

Получить список задач

GET /tasks.task.list

Параметры:

Параметр	Тип	Описание
filter	object	Фильтр задач
select	array	Поля для выборки
order	object	Сортировка

Создать задачу

POST /tasks.task.add

Пример запроса:

{
  "fields": {
    "TITLE": "Подготовить презентацию",
    "DESCRIPTION": "Создать презентацию для встречи с клиентом",
    "RESPONSIBLE_ID": 5,
    "CREATED_BY": 1,
    "DEADLINE": "2024-12-25T18:00:00+03:00",
    "PRIORITY": "2",
    "GROUP_ID": 10,
    "TAGS": ["презентация", "клиент", "срочно"]
  }
}

Обновить задачу

PUT /tasks.task.update

Завершить задачу

POST /tasks.task.complete

Комментарии к задаче

GET /task.commentitem.get

POST /task.commentitem.add

Приоритеты задач:
0 - Низкий | 1 - Средний | 2 - Высокий

📅 Календарь

Работа с календарями и событиями.

Получить события

GET /calendar.event.get

Добавить событие

POST /calendar.event.add

Пример создания события:

{
  "type": "user",
  "ownerId": 1,
  "name": "Встреча с клиентом",
  "description": "Обсуждение условий сотрудничества",
  "from": "2024-12-20T10:00:00+03:00",
  "to": "2024-12-20T11:30:00+03:00",
  "location": "Офис, переговорная №3",
  "attendees": [2, 5, 7],
  "remindType": "min",
  "remind": [15, 60]
}

Обновить событие

PUT /calendar.event.update

Удалить событие

DELETE /calendar.event.delete

⚠️ Коды ошибок

Описание возможных ошибок API.

Код	Название	Описание
200	OK	Запрос выполнен успешно
400	Bad Request	Неверный формат запроса
401	Unauthorized	Отсутствует или недействителен токен
403	Forbidden	Недостаточно прав доступа
404	Not Found	Ресурс не найден
429	Too Many Requests