Что такое списки в Битрикс24 и зачем нужен API

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

Основные возможности API списков:

• Создание и управление структурой списков
• Добавление, изменение и удаление элементов
• Массовые операции с данными
• Интеграция с внешними системами
• Автоматизация бизнес-процессов

Настройка доступа к API списков

Получение токена доступа

Для работы с API списков необходимо получить токен доступа. Существует несколько способов авторизации:

1. Входящий вебхук

Самый простой способ для начала работы с API. Создается в разделе «Приложения» → «Вебхуки».

2. Локальное приложение

Подходит для интеграции внутри одного портала. Требует регистрации приложения и получения ключей.

3. Облачное приложение

Используется для коммерческих решений, которые планируется распространять через Битрикс24.Маркет.

Права доступа

Для работы с API списков необходимо предоставить следующие права:

• lists — основные операции со списками
• user — получение информации о пользователях
• department — работа с подразделениями

Основные методы API списков

Получение списка всех списков

Метод lists.get возвращает все доступные списки на портале:

GET https://ваш-портал.bitrix24.ru/rest/lists.get?auth=ваш_токен
Параметры:
- IBLOCK_TYPE_ID: тип информационного блока (lists - пользовательские списки)
- IBLOCK_CODE: символьный код списка
- IBLOCK_ID: числовой идентификатор списка

Создание нового списка

Метод lists.add позволяет создать новый список:

POST https://ваш-портал.bitrix24.ru/rest/lists.add
Обязательные параметры:
{
"IBLOCK_TYPE_ID": "lists",
"IBLOCK_CODE": "my_custom_list",
"NAME": "Мой пользовательский список",
"DESCRIPTION": "Описание списка",
"WORKFLOW": "N",
"BIZPROC": "N",
"SORT": 500
}

Получение полей списка

Метод lists.field.get возвращает структуру полей списка:

GET https://ваш-портал.bitrix24.ru/rest/lists.field.get?auth=ваш_токен&IBLOCK_ID=123

Добавление полей в список

Метод lists.field.add создает новое поле в списке:

POST https://ваш-портал.bitrix24.ru/rest/lists.field.add
{
"IBLOCK_ID": 123,
"FIELD_ID": "UF_MY_FIELD",
"NAME": "Мое поле",
"TYPE": "string",
"MULTIPLE": "N",
"MANDATORY": "Y",
"SORT": 100
}

Работа с элементами списков

Получение элементов

Метод lists.element.get возвращает элементы списка с возможностью фильтрации:

GET https://ваш-портал.bitrix24.ru/rest/lists.element.get
Параметры:
- IBLOCK_ID: идентификатор списка
- FILTER: массив фильтров
- SELECT: выбираемые поля
- ORDER: сортировка
- START: начальная позиция для пагинации

Добавление элементов

Метод lists.element.add создает новый элемент в списке:

POST https://ваш-портал.bitrix24.ru/rest/lists.element.add
{
"IBLOCK_ID": 123,
"ELEMENT_CODE": "element_001",
"FIELDS": {
"NAME": "Название элемента",
"PROPERTY_UF_MY_FIELD": "Значение поля"
}
}

Обновление элементов

Метод lists.element.update изменяет существующий элемент:

POST https://ваш-портал.bitrix24.ru/rest/lists.element.update
{
"IBLOCK_ID": 123,
"ELEMENT_ID": 456,
"FIELDS": {
"NAME": "Новое название",
"PROPERTY_UF_MY_FIELD": "Новое значение"
}
}

Типы полей в списках

API списков поддерживает различные типы полей для хранения данных:

Базовые типы

• string — текстовая строка
• integer — целое число
• double — число с плавающей точкой
• datetime — дата и время
• date — только дата
• boolean — логический тип (да/нет)

Специальные типы

• employee — сотрудник
• crm_status — статус CRM
• iblock_section — раздел инфоблока
• iblock_element — элемент инфоблока
• file — файл
• url — ссылка

Практические примеры использования

Создание справочника товаров

Рассмотрим создание списка товаров с различными характеристиками:

// Создаем список
const listData = {
"IBLOCK_TYPE_ID": "lists",
"IBLOCK_CODE": "products_catalog",
"NAME": "Каталог товаров",
"DESCRIPTION": "Справочник товаров компании",
"WORKFLOW": "N",
"BIZPROC": "N"
};
// Добавляем поля
const fields = [
{
"FIELD_ID": "UF_ARTICLE",
"NAME": "Артикул",
"TYPE": "string",
"MANDATORY": "Y"
},
{
"FIELD_ID": "UF_PRICE",
"NAME": "Цена",
"TYPE": "double",
"MANDATORY": "Y"
},
{
"FIELD_ID": "UF_CATEGORY",
"NAME": "Категория",
"TYPE": "string",
"MANDATORY": "N"
}
];

Массовое добавление элементов

Для массового добавления элементов используется метод batch:

POST https://ваш-портал.bitrix24.ru/rest/batch
{
"cmd": {
"item_1": "lists.element.add?IBLOCK_ID=123&FIELDS[NAME]=Товар 1&FIELDS[PROPERTY_UF_PRICE]=1000",
"item_2": "lists.element.add?IBLOCK_ID=123&FIELDS[NAME]=Товар 2&FIELDS[PROPERTY_UF_PRICE]=2000",
"item_3": "lists.element.add?IBLOCK_ID=123&FIELDS[NAME]=Товар 3&FIELDS[PROPERTY_UF_PRICE]=3000"
}
}

Интеграция с внешними системами

Синхронизация с 1С

Списки часто используются для синхронизации данных между Битрикс24 и системами учета:

// Получаем данные из 1С
const products1C = await get1CProducts();
// Обновляем список в Битрикс24
for (const product of products1C) {
const existingElement = await findElementByCode(product.code);
if (existingElement) {
await updateListElement(existingElement.id, product);
} else {
await addListElement(product);
}
}

Интеграция с внешними API

Пример интеграции с внешним API для получения курсов валют:

// Получаем курсы валют
const rates = await fetch('https://api.exchangerate-api.com/v4/latest/USD');
const ratesData = await rates.json();
// Обновляем список курсов в Битрикс24
for (const [currency, rate] of Object.entries(ratesData.rates)) {
await updateCurrencyRate(currency, rate);
}

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

Типичные ошибки

1. Ошибка доступа (403)

Проверьте права доступа к спискам и корректность токена авторизации.

2. Неверный формат данных (400)

Убедитесь, что передаваемые данные соответствуют типам полей списка.

3. Превышение лимитов (429)

Соблюдайте ограничения на количество запросов в минуту (не более 2 запросов в секунду).

Логирование запросов

Рекомендуется вести лог всех API-запросов для отладки:

function logApiRequest(method, url, data, response) {
console.log({
timestamp: new Date().toISOString(),
method,
url,
data,
response,
status: response.status
});
}

Оптимизация производительности

Кеширование данных

Для улучшения производительности рекомендуется кешировать часто используемые данные:

class ListsCache {
constructor() {
this.cache = new Map();
this.ttl = 300000; // 5 минут
}
async get(key, fetcher) {
const cached = this.cache.get(key);
if (cached && Date.now() - cached.timestamp < this.ttl) {
return cached.data;
}
const data = await fetcher();
this.cache.set(key, {
data,
timestamp: Date.now()
});
return data;
}
}

Пагинация больших объемов данных

При работе с большими списками используйте пагинацию:

async function getAllListElements(iblockId) {
const elements = [];
let start = 0;
const limit = 50;
while (true) {
const response = await BX24.callMethod('lists.element.get', {
IBLOCK_ID: iblockId,
START: start,
LIMIT: limit
});
elements.push(...response.result);
if (response.result.length < limit) {
break;
}
start += limit;
}
return elements;
}

Безопасность при работе с API

Валидация данных

Всегда валидируйте входящие данные перед отправкой в API:

function validateListElement(data) {
const errors = [];
if (!data.NAME || data.NAME.trim() === '') {
errors.push('Название элемента обязательно');
}
if (data.PROPERTY_UF_PRICE && isNaN(data.PROPERTY_UF_PRICE)) {
errors.push('Цена должна быть числом');
}
return errors;
}

Ограничение прав доступа

Настройте минимально необходимые права доступа для приложения:

• Используйте принцип минимальных привилегий
• Регулярно ротируйте токены доступа
• Мониторьте использование API
• Логируйте все операции с чувствительными данными

Автоматизация бизнес-процессов

Создание автоматических задач

Пример создания задачи при добавлении нового элемента в список:

// Обработчик события добавления элемента
async function onElementAdd(elementData) {
// Создаем задачу ответственному
await BX24.callMethod('tasks.task.add', {
fields: {
DESCRIPTION: `Добавлен новый элемент с ID: ${elementData.ID}`,
RESPONSIBLE_ID: elementData.RESPONSIBLE_ID,
DEADLINE: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString()
}
});
}

Уведомления по email

Настройка email-уведомлений при изменении элементов списка:

async function sendNotification(elementId, changes) {
const emailData = {
USER_ID: changes.RESPONSIBLE_ID,
MESSAGE_SUBJECT: 'Изменения в списке',
MESSAGE_BODY: `Элемент ${elementId} был изменен`,
MESSAGE_TYPE: 'email'
};
await BX24.callMethod('im.notify.system.add', emailData);
}

Мониторинг и аналитика

Отслеживание изменений

Ведите журнал изменений для аудита:

class ChangeTracker {
constructor() {
this.changes = [];
}
track(action, elementId, oldData, newData) {
this.changes.push({
timestamp: new Date().toISOString(),
action,
elementId,
oldData,
newData,
user: BX24.getAuth().member_id
});
}
async saveChanges() {
// Сохраняем изменения в отдельный список аудита
await this.saveToAuditList(this.changes);
this.changes = [];
}
}

Метрики использования

Собирайте статистику использования API:

class ApiMetrics {
constructor() {
this.metrics = {
requests: 0,
errors: 0,
responseTime: []
};
}
recordRequest(duration, success) {
this.metrics.requests++;
this.metrics.responseTime.push(duration);
if (!success) {
this.metrics.errors++;
}
}
getStats() {
return {
totalRequests: this.metrics.requests,
errorRate: this.metrics.errors / this.metrics.requests,
avgResponseTime: this.metrics.responseTime.reduce((a, b) => a + b, 0) / this.metrics.responseTime.length
};
}
}

Заключение

API списков Битрикс24 предоставляет мощные возможности для автоматизации работы с пользовательскими данными. Правильное использование методов API позволяет создавать эффективные интеграции с внешними системами, автоматизировать бизнес-процессы и обеспечивать актуальность данных в реальном времени.

Ключевые моменты для успешной работы с API:

• Соблюдение лимитов и ограничений API
• Правильная обработка ошибок и исключений
• Использование кеширования для оптимизации производительности
• Валидация данных перед отправкой
• Мониторинг и логирование операций

Наша компания предоставляет профессиональные услуги по настройке и внедрению Битрикс24:

• Настройка API интеграций с внешними системами
• Создание пользовательских списков и справочников
• Разработка автоматизированных бизнес-процессов
• Миграция данных и настройка синхронизации
• Техническая поддержка и сопровождение

Обращайтесь к нам за консультацией и помощью в реализации ваших задач по автоматизации с использованием Битрикс24.

Сообщение `Новый элемент в списке: ${elementData.NAME}`, появились сначала на Битрикс24.