denx-b/b24-rest

Bitrix24 REST wrapper library

v1.0.4 2026-02-21 19:52 UTC

Requires

• php: >=8.1
• ext-ctype: *
• ext-curl: *
• ext-iconv: *
• ext-json: *

proprietary

README

composer require denx-b/b24-rest:dev-main

Базовая инициализация

use B24Rest\Rest\Bitrix24RestFactory;

$b24 = Bitrix24RestFactory::fromWebhook('https://<portal>/rest/1/<webhook>/');

Сделки (примеры)

// Получить список сделок через crm.item.list
$page = $b24->deals()->list();

// Выгрузить все сделки (start = -1 + внутренний курсор по <ID, сортировка ID DESC)
$allDeals = $b24->deals()->all();

// Выгрузить все сделки с фильтром
$allInWork = $b24->deals()->all([
    'filter' => ['STAGE_ID' => 'NEW'],
    'select' => ['ID', 'TITLE', 'STAGE_ID'],
]);

// Получить сделку по ID
$deal = $b24->deals()->getById(123);

// Добавить сделку
$created = $b24->deals()->add([
    'TITLE' => 'Сделка из API',
    'STAGE_ID' => 'NEW',
]);

// Обновить сделку
$ok = $b24->deals()->update(123, [
    'TITLE' => 'Обновлённый заголовок',
]);

// Массовое добавление (под капотом batch, с чанками по 50)
$created = $b24->deals()->addMany([
    ['TITLE' => 'Сделка #1', 'STAGE_ID' => 'NEW'],
    ['TITLE' => 'Сделка #2', 'STAGE_ID' => 'NEW'],
]);

// Массовое обновление
$updated = $b24->deals()->updateMany([
    ['id' => 123, 'fields' => ['TITLE' => 'Сделка #123 v2']],
    ['id' => 124, 'fields' => ['TITLE' => 'Сделка #124 v2']],
]);

// Удалить сделку
$deleted = $b24->deals()->delete(123);

// Добавить товарную позицию в сделку
$row = $b24->deals()->productRowAdd(359, [
    'productName' => 'Пакет услуг',
    'price' => 1000,
    'quantity' => 1,
]);

// Обновить товарную позицию
$row = $b24->deals()->productRowUpdate(5001, [
    'price' => 1500,
    'quantity' => 2,
]);

// Получить товарную позицию по ID
$row = $b24->deals()->productRowGet(5001);

// Получить список товарных позиций по сделке
$rows = $b24->deals()->productRowList(359);

// Удалить товарную позицию
$deleted = $b24->deals()->productRowDelete(5001);

// Направления сделок (воронки)
$directions = $b24->dealCategories()->list();

// Направление сделки по ID
$direction = $b24->dealCategories()->getById(1);

// Добавить направление сделки
$createdDirection = $b24->dealCategories()->add([
    'name' => 'Новая воронка',
    'sort' => 500,
]);

// Обновить направление сделки
$updatedDirection = $b24->dealCategories()->update(1, [
    'name' => 'Воронка v2',
]);

// Удалить направление сделки
$deletedDirection = $b24->dealCategories()->delete(1);

// Получить список стадий выбранного направления (ID категории)
$stages = $b24->dealCategoryStages()
    ->listByCategoryId(1);

// Получить список стадий (любой фильтр ENTITY_ID можно передать в params)
$allStages = $b24->dealCategoryStages()->list([
    'filter' => ['ENTITY_ID' => 'DEAL_STAGE_1'],
]);

// Получить стадию по ID
$stage = $b24->dealCategoryStages()
    ->getById(100);

// Добавить стадию (с явным ENTITY_ID)
$createdStage = $b24->dealCategoryStages()->add([
    'ENTITY_ID' => 'DEAL_STAGE_1',
    'STATUS_ID' => 'NEW_CUSTOM_STAGE',
    'NAME' => 'Новая пользовательская стадия',
    'SORT' => 500,
]);

// Добавить стадию в выбранное направление
$createdStage = $b24->dealCategoryStages()->addForCategory(1, [
    'STATUS_ID' => 'NEW_CUSTOM_STAGE',
    'NAME' => 'Новая пользовательская стадия',
    'SORT' => 500,
]);

// Добавить стадию в выбранное направление (STATUS_ID генерируется автоматически)
$createdStage = $b24->dealCategoryStages()->addForCategoryWithGeneratedStatusId(
    1,
    'Стадия с авто STATUS_ID'
);

// Обновить стадию
$updatedStage = $b24->dealCategoryStages()->updateForCategory(1, 100, [
    'NAME' => 'Переименованная стадия',
]);

// Обновить стадию по ID (с явным ENTITY_ID)
$updatedStage = $b24->dealCategoryStages()->update(100, [
    'ENTITY_ID' => 'DEAL_STAGE_1',
    'NAME' => 'Переименованная стадия',
]);

// Удалить стадию
$deletedStage = $b24->dealCategoryStages()->delete(100);

Другие сущности crm.item (примеры)

// Лиды
$lead = $b24->leads()->list();

// Контакты
$contactsPage = $b24->contacts()->list();

// Компании
$companyId = $b24->companies()->list();

// Счета
$invoice = $b24->invoices()->list();

// Предложения
$quote = $b24->quotes()->list();

// Элементы смарт-процесса (пример entityTypeId=136)
$smartItems = $b24->smartItems(1086)->list();

contacts() и companies() поддерживают только crm.item.* (без productRow*).

Задачи

// Добавить задачу
$task = $b24->tasks()->add([
    'TITLE' => 'Задача из API',
    'RESPONSIBLE_ID' => 1,
]);

// Обновить задачу
$ok = $b24->tasks()->update(100, [
    'TITLE' => 'Обновлённый заголовок задачи',
]);

// Массовое добавление задач (под капотом tasks.task.add через batch, с чанками по 50)
$createdTasks = $b24->tasks()->addMany([
    ['TITLE' => 'Задача #1', 'RESPONSIBLE_ID' => 1],
    ['TITLE' => 'Задача #2', 'RESPONSIBLE_ID' => 1],
]);

// Массовое обновление задач (под капотом tasks.task.update через batch, с чанками по 50)
$updated = $b24->tasks()->updateMany([
    ['taskId' => 100, 'fields' => ['TITLE' => 'Задача #100 v2']],
    ['taskId' => 101, 'fields' => ['TITLE' => 'Задача #101 v2']],
]);

// Получить задачу
$task = $b24->tasks()->get(100);

// Список задач (page = 1, фиксированный размер страницы = 50)
$tasks = $b24->tasks()->list([
    'order' => ['ID' => 'DESC'],
    'select' => ['ID', 'TITLE', 'STATUS'],
], 1);

// Все задачи (start=-1 + курсор по ID)
$allTasks = $b24->tasks()->taskAll([
    'filter' => ['GROUP_ID' => 7],
    'select' => ['ID', 'TITLE', 'STATUS'],
]);

// Список шаблонов задач
$templates = $b24->tasks()->templateList();

// Создать задачу по шаблону (поля задачи можно переопределить)
$created = $b24->tasks()->taskAddFromTemplate(3, [
    'RESPONSIBLE_ID' => 1,
    'TITLE' => 'Задача из шаблона #3',
]);

// Получить шаблон задачи по ID
$template = $b24->tasks()->templateGet(3);

// Получить чек-лист шаблона задачи
$templateChecklist = $b24->tasks()
    ->templateChecklistList(3);

// Прикрепить файл к задаче
$ok = $b24->tasks()->taskFilesAttach(100, 555);

// Делегировать задачу
$ok = $b24->tasks()->taskDelegate(100, 1);

// Массово делегировать задачи (под капотом tasks.task.delegate через batch, с чанками по 50)
$delegated = $b24->tasks()->taskDelegateMany([
    ['taskId' => 100, 'userId' => 1],
    ['taskId' => 101, 'userId' => 1],
]);

// Завершить задачу
$ok = $b24->tasks()->taskComplete(100);

// Массово завершить задачи (под капотом tasks.task.complete через batch, с чанками по 50)
$completed = $b24->tasks()
    ->taskCompleteMany([100, 101, 102]);

// Удалить задачу
$ok = $b24->tasks()->taskDelete(100);

// Массово удалить задачи (под капотом tasks.task.delete через batch, с чанками по 50)
$deleted = $b24->tasks()->taskDeleteMany([100, 101, 102]);

// Добавить пункты чек-листа (всегда через batch, даже для одного пункта): создать новый чек-лист по названию
$checklistItems = $b24->tasks()->checklistItemAdd(100, 'Основной чек-лист', [
    ['TITLE' => 'Первый пункт'],
    ['TITLE' => 'Второй пункт'],
]);

// Добавить пункты в существующий чек-лист (checklistId / parentId)
$checklistItems = $b24->tasks()->checklistItemAdd(100, '', [
    ['TITLE' => 'Третий пункт'],
], [
    'checklistId' => 200,
]);

// Обновить пункт чек-листа
$ok = $b24->tasks()->checklistItemUpdate(100, 200, [
    'TITLE' => 'Пункт обновлён',
]);

// Получить пункт чек-листа
$checklistItem = $b24->tasks()->checklistItemGet(100, 200);

// Получить список пунктов чек-листа
$checklist = $b24->tasks()->checklistItemGetList(100);

// Переместить пункт чек-листа после другого пункта
$ok = $b24->tasks()->checklistItemMoveAfterItem(100, 201, 200);

// Отметить пункт чек-листа как выполненный
$ok = $b24->tasks()->checklistItemComplete(100, 200);

// Возобновить пункт чек-листа
$ok = $b24->tasks()->checklistItemRenew(100, 200);

// Удалить пункт чек-листа
$ok = $b24->tasks()->checklistItemDelete(100, 200);

// Переименовать чек-лист по текущему названию
$ok = $b24->tasks()->checklistRenameByTitle(100, 'Основной чек-лист', 'Основной чек-лист v2');

// Добавить комментарий к задаче
$comment = $b24->tasks()->commentItemAdd(100, 'Комментарий к задаче из API', 1);

// Добавить запись о затраченном времени
$elapsed = $b24->tasks()->elapsedItemAdd(100, 600, 'Потратил 10 минут', 1);

// Обновить запись о затраченном времени
$ok = $b24->tasks()->elapsedItemUpdate(100, 300, 900, 'Потратил 15 минут');

// Получить запись о затраченном времени
$elapsedItem = $b24->tasks()->elapsedItemGet(100, 300);

// Получить список записей о затраченном времени
$elapsedItems = $b24->tasks()->elapsedItemGetList([
    'filter' => ['TASK_ID' => 100],
    'order' => ['ID' => 'DESC'],
]);

// Удалить запись о затраченном времени
$ok = $b24->tasks()->elapsedItemDelete(100, 300);

// Получить все записи о затраченном времени по произвольному фильтру
$allElapsed = $b24->tasks()->elapsedItemAll([
    'filter' => ['USER_ID' => 1],
    'order' => ['ID' => 'DESC'],
]);

// Получить все записи о затраченном времени по задаче
$allTaskElapsed = $b24->tasks()->elapsedItemAllByTaskId(100);

// Получить все записи о затраченном времени по группе (сначала собираются ID задач группы, затем выборка по TASK_ID)
$allGroupElapsed = $b24->tasks()->elapsedItemAllByGroupId(7);

// Добавить пользовательское поле задачи
$userField = $b24->tasks()->itemUserFieldAdd([
    'ENTITY_ID' => 'TASKS_TASK',
    'FIELD_NAME' => 'UF_API_FIELD',
    'USER_TYPE_ID' => 'string',
    'EDIT_FORM_LABEL' => ['ru' => 'Поле API'],
]);

Структура компании

// Все департаменты (внутренняя пагинация по start/next, сортировка по умолчанию ID DESC)
$departments = $b24->departments()->all();

// Департамент по ID
$department = $b24->departments()->getById(1);

// Сотрудники департамента по ID департамента
$departmentUsers = $b24->departments()->getUsersById(1, [
    'SELECT' => ['ID', 'NAME', 'LAST_NAME', 'UF_DEPARTMENT'],
]);

// Добавить департамент
$createdDepartment = $b24->departments()->add([
    'NAME' => 'Новый департамент',
    'PARENT' => 1,
]);

// Обновить департамент
$updatedDepartment = $b24->departments()->update(100, [
    'NAME' => 'Переименованный департамент',
]);

// Удалить департамент
$deletedDepartment = $b24->departments()->delete(100);

Типы цен

// Список типов цен (page = 1, фиксированный размер страницы = 50)
$priceTypesPage = $b24->priceTypes()->list([
    'select' => ['id', 'name', 'xmlId'],
], 1);

// Все типы цен (start=-1 + внутренний курсор по <id)
$allPriceTypes = $b24->priceTypes()->all([
    'select' => ['id', 'name', 'xmlId'],
]);

// Тип цены по ID
$priceType = $b24->priceTypes()->getById(2);

// Добавить тип цены
$createdPriceType = $b24->priceTypes()->add([
    'name' => 'Base wholesale price',
    'base' => 'N',
    'sort' => 200,
    'xmlId' => 'basewholesale',
]);

// Обновить тип цены
$updatedPriceType = $b24->priceTypes()->update(2, [
    'name' => 'Base wholesale price v2',
    'sort' => 300,
]);

// Массовое добавление типов цен (под капотом catalog.priceType.add через batch, с чанками по 50)
$createdPriceTypes = $b24->priceTypes()->addMany([
    ['name' => 'Wholesale A', 'base' => 'N', 'sort' => 400, 'xmlId' => 'wholesale_a'],
    ['name' => 'Wholesale B', 'base' => 'N', 'sort' => 500, 'xmlId' => 'wholesale_b'],
]);

// Массовое обновление типов цен (под капотом catalog.priceType.update через batch, с чанками по 50)
$updatedPriceTypes = $b24->priceTypes()->updateMany([
    ['id' => 2, 'fields' => ['name' => 'Base wholesale price v3']],
    ['id' => 3, 'fields' => ['sort' => 600]],
]);

// Удалить тип цены
$deletedPriceType = $b24->priceTypes()->delete(2);

// Получить доступные поля типа цены
$priceTypeFields = $b24->priceTypes()->getFields();

Единицы измерения

// Список единиц измерения (page = 1, фиксированный размер страницы = 50)
$measuresPage = $b24->measures()->list([
    'select' => ['id', 'code', 'symbolIntl'],
], 1);

// Все единицы измерения (start=-1 + внутренний курсор по <id)
$allMeasures = $b24->measures()->all([
    'select' => ['id', 'code', 'symbolIntl'],
]);

// Единица измерения по ID
$measure = $b24->measures()->getById(6);

// Добавить единицу измерения
$createdMeasure = $b24->measures()->add([
    'code' => 800,
    'measureTitle' => 'Комплект',
    'symbolLetterIntl' => 'set',
    'symbolIntl' => 'pcs',
]);

// Обновить единицу измерения
$updatedMeasure = $b24->measures()->update(6, [
    'measureTitle' => 'Комплект v2',
    'symbolIntl' => 'set.',
]);

// Массовое добавление единиц измерения (под капотом catalog.measure.add через batch, с чанками по 50)
$createdMeasures = $b24->measures()->addMany([
    ['code' => 801, 'measureTitle' => 'Набор A', 'symbolIntl' => 'setA'],
    ['code' => 802, 'measureTitle' => 'Набор B', 'symbolIntl' => 'setB'],
]);

// Массовое обновление единиц измерения (под капотом catalog.measure.update через batch, с чанками по 50)
$updatedMeasures = $b24->measures()->updateMany([
    ['id' => 6, 'fields' => ['measureTitle' => 'Комплект v3']],
    ['id' => 7, 'fields' => ['symbolIntl' => 'pcs.']],
]);

// Удалить единицу измерения
$deletedMeasure = $b24->measures()->delete(6);

// Получить доступные поля единиц измерения
$measureFields = $b24->measures()->getFields();

Валюты

// Список валют (page = 1, фиксированный размер страницы = 50)
$currenciesPage = $b24->currencies()->list([
    'order' => ['currency' => 'DESC'],
], 1);

// Все валюты (первый запрос с start=-1)
$allCurrencies = $b24->currencies()->all([
    'order' => ['currency' => 'DESC'],
]);

// Валюта по коду
$currency = $b24->currencies()->getById('USD');

// Добавить валюту
$createdCurrency = $b24->currencies()->add([
    'CURRENCY' => 'CNY',
    'AMOUNT' => 1,
    'AMOUNT_CNT' => 1,
    'SORT' => 100,
]);

// Обновить валюту
$updatedCurrency = $b24->currencies()->update('CNY', [
    'AMOUNT' => 15.3449,
]);

// Массовое добавление валют (под капотом crm.currency.add через batch, с чанками по 50)
$createdCurrencies = $b24->currencies()->addMany([
    ['CURRENCY' => 'KZT', 'AMOUNT' => 1, 'AMOUNT_CNT' => 1, 'SORT' => 200],
    ['CURRENCY' => 'AED', 'AMOUNT' => 1, 'AMOUNT_CNT' => 1, 'SORT' => 300],
]);

// Массовое обновление валют (под капотом crm.currency.update через batch, с чанками по 50)
$updatedCurrencies = $b24->currencies()->updateMany([
    ['id' => 'CNY', 'fields' => ['AMOUNT' => 15.5000]],
    ['id' => 'USD', 'fields' => ['SORT' => 50]],
]);

// Удалить валюту
$deletedCurrency = $b24->currencies()->delete('IDR');

// Получить базовую валюту
$baseCurrency = $b24->currencies()->baseGet();

// Установить базовую валюту
$setBaseCurrency = $b24->currencies()->baseSet('RUB');