PHPackages                             andrey-tech/bx24-wrapper-js - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Queues & Workers](/categories/queues)
4. /
5. andrey-tech/bx24-wrapper-js

ActiveLibrary[Queues & Workers](/categories/queues)

andrey-tech/bx24-wrapper-js
===========================

Простой класс-обертка на JavaScript для стандартной JS-библиотеки Битрикс24. Позволяет избежать ада колбеков и работать c REST API Битрикс24 с помощью асинхронных функций и асинхронных генераторов ECMAScript 9

1.5.1(2y ago)321314MITJavaScript

Since Jun 14Pushed 2y ago3 watchersCompare

[ Source](https://github.com/andrey-tech/bx24-wrapper-js)[ Packagist](https://packagist.org/packages/andrey-tech/bx24-wrapper-js)[ Docs](https://github.com/andrey-tech/bx24-wrapper-js)[ RSS](/packages/andrey-tech-bx24-wrapper-js/feed)WikiDiscussions master Synced today

READMEChangelog (4)DependenciesVersions (7)Used By (0)

Bitrix24 JS-lib Wrapper
=======================

[](#bitrix24-js-lib-wrapper)

[![Bitrix24 logo](./assets/bitrix24-logo.png)](./assets/bitrix24-logo.png)

[![Latest Stable Version](https://camo.githubusercontent.com/d1e11003bd67a7fdf0803665b9e6e9d3f33899cc9df6923a5cf039c9d65a6b95/68747470733a2f2f706f7365722e707567782e6f72672f616e647265792d746563682f627832342d777261707065722d6a732f76)](https://packagist.org/packages/andrey-tech/bx24-wrapper-js)[![GitHub stars](https://camo.githubusercontent.com/af64ddd50afa71c987a1f62b576abd547f4f33ce5fd68bb58924f6658b602b9a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f616e647265792d746563682f627832342d777261707065722d6a73)](https://github.com/andrey-tech/bx24-wrapper-js/stargazers)[![GitHub forks](https://camo.githubusercontent.com/50e9e8503b0710dd30042f17d0eb229c7a5bd596a46aa30d58fa53e7613f3f9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f666f726b732f616e647265792d746563682f627832342d777261707065722d6a73)](https://github.com/andrey-tech/bx24-wrapper-js/network)[![GitHub watchers](https://camo.githubusercontent.com/f9497b55f8521e7332cfb26afbec7163a129c91464b4740f16434138da23b9fc/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f77617463686572732f616e647265792d746563682f627832342d777261707065722d6a73)](https://github.com/andrey-tech/bx24-wrapper-js/watchers)[![License](https://camo.githubusercontent.com/0cb2b1ca01753402bdbb516f1ec2275b3de179d8ff498504188be97142998e2d/68747470733a2f2f706f7365722e707567782e6f72672f616e647265792d746563682f627832342d777261707065722d6a732f6c6963656e7365)](https://packagist.org/packages/andrey-tech/bx24-wrapper-js)

Класс-обертка на JavaScript для стандартной [JS-библиотеки](https://dev.1c-bitrix.ru/rest_help/js_library/index.php) Битрикс24. Данный класс позволяет избежать [ада колбеков](http://callbackhell.ru) и работать c API Битрикс24 с помощью асинхронных функций и асинхронных генераторов ECMAScript 9.

Разработчики на PHP могут воспользоваться классом-оберткой [andrey-tech/bitrix24-api-php](https://github.com/andrey-tech/bitrix24-api-php).

Содержание
----------

[](#содержание)

- [Требования](#%D1%82%D1%80%D0%B5%D0%B1%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F)
- [Класс BX24Wrapper](#%D0%BA%D0%BB%D0%B0%D1%81%D1%81-bx24wrapper)
- [Методы класса BX24Wrapper](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B-%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B0-bx24wrapper)
    - [Метод `async callMethod()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-callmethod)
    - [Метод `async callListMethod()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-calllistmethod)
    - [Метод `async *fetchList()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-fetchlist)
    - [Метод `async callBatch()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-callbatch)
    - [Метод `async callLongBatch()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-calllongbatch)
    - [Метод `async *callLargeBatch()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-async-calllargebatch)
    - [Метод `static createCalls()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-static-createcalls)
    - [Метод `getLastResult()`](#%D0%BC%D0%B5%D1%82%D0%BE%D0%B4-getlastresult)
- [Обработка ошибок](#%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BE%D0%BA)
- [Автор](#%D0%B0%D0%B2%D1%82%D0%BE%D1%80)
- [Лицензия](#%D0%BB%D0%B8%D1%86%D0%B5%D0%BD%D0%B7%D0%B8%D1%8F)

Требования
----------

[](#требования)

- Стандартная [JS-библиотека](https://dev.1c-bitrix.ru/rest_help/js_library/index.php) Битрикс24 v1.0, которая представляет собой JavaScriptS SDK для REST API, что позволяет обращаться к API прямо из front-end приложения не погружаясь в реализацию авторизации по OAuth 2.0. **Для внешних приложений и вебхуков библиотека использоваться не может.**

Подключение стандартной библиотеки Битрикс24 v1.0:

```

```

- Среда исполнения JavaScript, соответствущая спецификации ECMAScript 9 ([ECMAScript® 2018](http://www.ecma-international.org/ecma-262/9.0/index.html)) в части [поддержки асинхронных генераторов JavaScript](https://caniuse.com/#search=async%20generator) :
    - Google Chrome >= 63
    - Mozilla Firefox >= 55
    - Apple Safari >= 12
    - Microsoft Edge >= 79
    - Opera >= 50

Класс BX24Wrapper
-----------------

[](#класс-bx24wrapper)

Создание нового объекта класса `BX24Wrapper`:

- `new BX24Wrapper();`

Дополнительные параметры работы устанавливаются через свойства объекта класса `BX24Wrapper`.

СвойствоПо умолчаниюОписание`batchSize`50Максимальное число команд в одном пакете запросе ([не более 50](https://dev.1c-bitrix.ru/rest_help/general/lists.php))`throttle`2Максимальное число запросов к API в секунду ([не более 2-х запросов в секунду](https://dev.1c-bitrix.ru/rest_help/rest_sum/index.php))`progress``percent => {};`Функция для контроля прогресса выполнения запросов в методах `callListMethod()`, `fetchList()`, `callLongBatch()` и `callLargeBatch()` (`percent` - прогресс 0-100, %)```
(async () => {
    let bx24 = new BX24Wrapper();

    // Устанавливаем максимальное число команд в одном пакете запросе
    bx24.batchSize = 25;

    // Устанавливаем троттлинг запросов к API Битрикс24 на уровне 0,5 запросов в секунду,
    // то есть 1 запрос в 2 секунды
    bx24.throttle = 0.5;

    // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах
    bx24.progress = percent => console.log(`Progress: ${percent}%`);

})().catch(error => console.log('Error:', error));
```

Методы класса BX24Wrapper
-------------------------

[](#методы-класса-bx24wrapper)

### Метод `async callMethod()`

[](#метод-async-callmethod)

Вызывает указанный метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис).
Обертка метода [callMethod](https://dev.1c-bitrix.ru/rest_help/js_library/rest/callMethod.php) стандартной библиотеки Битрикс24.

- `callMethod(method [, params = {}, dataExtractor = null ]);`
    Параметры:
    - *string* `method` - строка, указывающая вызываемый метод REST-сервиса;
    - *object* `params` - объект параметров для метода REST-сервиса;
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Загружаем компанию по её ID
    let company = await bx24.callMethod('crm.company.get', { ID: 6 });
    console.log('Company:', company);

})().catch(error => console.log('Error:', error));
```

### Метод `async callListMethod()`

[](#метод-async-calllistmethod)

Вызывает указанный **списочный** метод REST-сервиса с заданными параметрами и возвращает объект Promise (промис). Позволяет одним вызовом загружать произвольное число сущностей с фильтрацией по параметрам в виде массива объектов и контролировать прогресс выполнения загрузки.

- `callListMethod(listMethod [, params = {}, dataExtractor = null ]);`
    Параметры:
    - *string* `listMethod` - строка, указывающая вызываемый списочный метод REST-сервиса;
    - *object* `params` - объект параметров для списочного метода REST-сервиса;
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах
    bx24.progress = percent => console.log(`progress: ${percent}%`);

    let params = {
        filter: { CATALOD_ID: 21 },
        select: [ '*', 'PROPERTY_*' ]
    };

    // Загружем список всех товаров в заданном товарном каталоге CRM
    let products = await bx24.callListMethod('crm.product.list', params);
    for (let product of products) {
        console.log('Product:', product);
    }

    params = {
        filter: { iblockId: 11 },
        select: [ '*', 'id', 'iblockId' ]
    };

    // Задаем собственную функцию для извлечения массива товаров из объекта с результатами запроса
    let dataExtractor = data => data.products;

    // Загружем список всех товаров в заданном товарном каталоге
    products = await bx24.callListMethod('catalog.product.list', params, dataExtractor);
    for (let product of products) {
        console.log('Product:', product);
    }

})().catch(error => console.log('Error:', error));
```

### Метод `async *fetchList()`

[](#метод-async-fetchlist)

Вызывает указанный **списочный** метод REST-сервиса с заданными параметрами и возвращает объект Generator (генератор). Позволяет одним вызовом загружать произвольное число сущностей с фильтрацией по параметрам в виде массива объектов и контролировать прогресс выполнения загрузки.

Реализует быстрый алгоритм, описанный в статье ["Как правильно выгружать большие объемы данных"](https://dev.1c-bitrix.ru/rest_help/rest_sum/start.php). Использование асинхронного генератора дает существенную экономию памяти при обработке большого количества сущностей.

- `fetchList(listMethod [, params = {}, dataExtractor = null, idKey = 'ID' ]);`
    Параметры:
    - *string* `listMethod` - строка, указывающая вызываемый списочный метод REST-сервиса;
    - *object* `params` - объект параметров для списочного метода REST-сервиса;
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса;
    - *string* `idKey` - имя поля ID загружаемых сущностей (`ID` - CRM или `id`).

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Устанавливаем собственную функцию для вывода в веб-консоль прогресса выполнения запросов в процентах
    bx24.progress = percent => console.log(`progress: ${percent}%`);

    let params = {
        filter: { CATALOD_ID: 21 }
    };

    // Загружем список всех товаров в заданном товарном каталоге CRM, используя асинхронный генератор
    let generator = bx24.fetchList('crm.product.list', params);
    for await (let products of generator) {
        for (let product of products) {
            console.log('Product:', product);
        }
    }

    params = {
        filter: { iblockId: 11 },
        select: [ '*', 'id', 'iblockId' ]
    };

    // Задаем собственную функцию для извлечения массива товаров из объекта с результатами запроса
    let dataExtractor = data => data.products;

    // Задаем имя поля ID загружаемых сущностей (товаров) в результатах запроса
    let idKey = 'id';

    // Загружем список всех товаров в заданном товарном каталоге, используя асинхронный генератор
    generator = bx24.fetchList('catalog.product.list', params, dataExtractor, idKey);
    for await (let products of generator) {
        for (let product of products) {
            console.log('Product:', product);
        }
    }

})().catch(error => console.log('Error:', error));
```

### Метод `async callBatch()`

[](#метод-async-callbatch)

Отправляет пакет запросов к REST-сервису с максимальным числом команд в запросе 50 и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива или объекта. Обертка метода [callBatch](https://dev.1c-bitrix.ru/rest_help/js_library/rest/callBatch.php) стандартной библиотеки Битрикс24.

- `callBatch(calls [, haltOnError = true, dataExtractor = null ]);`
    Параметры:
    - *array|object* `calls` - пакет запросов в виде массива или объекта;
    - *bool* `haltOnError` - флаг "прерывать исполнение пакета в при возникновении ошибки";
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Пакет запросов в виде массива с максимальным числом команд в запросе 50
    let calls = [
        [ 'crm.deal.get', { id: 2880 } ],
        [ 'crm.contact.get', { id: 8 } ],
        [ 'crm.company.get', { id: 6 } ]
    ];

    // Отправляем пакет запросов в виде массива
    let response = await bx24.callBatch(calls, false);
    console.log('Response array:', response);

    // Пакет запросов в виде объекта с максимальным числом команд в запросе 50
    calls = {
        get_deal: [ 'crm.deal.get', { id: 2880 } ],
        get_company: [ 'crm.company.get', { id: '$result[get_deal][COMPANY_ID]' } ],
        get_contact: [ 'crm.contact.get', { id: '$result[get_deal][CONTACT_ID]' } ]
    };

    // Отправляем пакет запросов в виде объекта
    response = await bx24.callBatch(calls);
    console.log('Response object:', response);

})().catch(error => console.log('Error:', error));
```

### Метод `async callLongBatch()`

[](#метод-async-calllongbatch)

Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Promise (промис). Позволяет получить результаты пакетного выполнения запросов в виде массива.

- `callLongBatch(calls [, haltOnError = true, dataExtractor = null ]);`
    Параметры:
    - *array* `calls` - пакет запросов в виде массива;
    - *bool* `haltOnError` - флаг "прерывать исполнение пакета в при возникновении ошибки";
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Длинный пакет запросов в виде массива с произвольным числом команд в запросе
    let calls = [
        [ 'crm.deal.get', { id: 2880 } ],
        [ 'crm.contact.get', { id: 8 } ],
        [ 'crm.company.get', { id: 6 } ],
        [ 'crm.product.get', { id: 1 } ]
    ];

    // Отправляем длинный пакет запросов в виде массива
    let response = await bx24.callLongBatch(calls);
    console.log('Response array:', response);

})().catch(error => console.log('Error:', error));
```

### Метод `async *callLargeBatch()`

[](#метод-async-calllargebatch)

Отправляет пакет запросов к REST-сервису в виде массива с произвольным числом команд в запросе и возвращает Generator (генератор). Позволяет получить результаты пакетного выполнения запросов в виде массива. Использование асинхронного генератора дает существенную экономию памяти при работе с длинными пакетами запросов.

- `callLargeBatch(calls [, haltOnError = true, dataExtractor = null ]);`
    Параметры:
    - *array* `calls` - пакет запросов в виде массива;
    - *bool* `haltOnError` - флаг "прерывать исполнение пакета в при возникновении ошибки";
    - *function* `dataExtractor` - функция для извлечения данных из результатов запроса.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Длинный пакет запросов в виде массива с произвольным числом команд в запросе
    let calls = [
        [ 'crm.deal.get', { id: 2880 } ],
        [ 'crm.contact.get', { id: 8 } ],
        [ 'crm.company.get', { id: 6 } ],
        [ 'crm.product.get', { id: 1 } ]
    ];

    // Отправляем длинный пакет запросов в виде массива, используя асинхронный генератор
    let generator = bx24.callLargeBatch(calls, true);
    for await (let response of generator) {
        console.log('Response array:', response);
    }

})().catch(error => console.log('Error:', error));
```

### Метод `static createCalls()`

[](#метод-static-createcalls)

Создает пакет однотипных запросов для методов `callBatch()`, `callLongBatch()` и `callLargeBatch()`и возвращает пакет запросов в виде массива.

- `BX24Wrapper.createCalls(method, items);`
    Параметры:
    - *string* `method` - строка, указывающая вызываемый метод REST-сервиса во всех запросах;
    - *array* `items` - массив параметров запросов.

```
(async () => {
    let bx24 = new BX24Wrapper();

    // Массив параметров однотипных запросов
    let items = [
        { id: 4 },
        { id: 6 },
        { id: 8 }
    ];

    // Создаем пакет запросов в виже массива
    let calls = BX24Wrapper.createCalls('crm.contact.get', items);

    // Отправляем пакет запросов в виде массива
    let response = await bx24.callBatch(calls);
    console.log('Response:', response);

})().catch(error => console.log('Error:', error));
```

### Метод `getLastResult()`

[](#метод-getlastresult)

Возвращает последний объект [ajaxResult](https://dev.1c-bitrix.ru/rest_help/js_library/rest/callMethod.php), полученный от стандартной библиотеки Битрикс24.

- `getLastResult();`

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

[](#обработка-ошибок)

При возникновении ошибок в методах класса выбрасываются исключения.
Последний объект [ajaxResult](https://dev.1c-bitrix.ru/rest_help/js_library/rest/callMethod.php), полученный от стандартной библиотеки Битрикс24, может быть получен посредством метода `getLastResult()`.

```
(async () => {

    let bx24 = new BX24Wrapper();

    // Загружаем несуществующую компанию по её ID и перехватываем возникающее исключение
    let company = await bx24.callMethod('crm.company.get', { ID: 9999999999 })
        .catch(error => {
            console.log('Error:', error);

            // Получаем последний объект ajaxResult, полученный от стандартной библиотеки Битрикс24
            let ajaxResult = bx24.getLastResult();
            console.log('ajaxResult:', ajaxResult);
        });

})().catch(error => console.log('Error:', error));
```

Автор
-----

[](#автор)

© 2019-2023 andrey-tech

Лицензия
--------

[](#лицензия)

Данный класс распространяется на условиях лицензии [MIT](./LICENSE).

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity19

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity59

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~382 days

Total

4

Last Release

1007d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/de69f7116b4bbba0435826347eeea01c7c6d831ae5ca5325ccf0686e7ddb92b4?d=identicon)[andrey-tech](/maintainers/andrey-tech)

---

Top Contributors

[![andrey-tech](https://avatars.githubusercontent.com/u/51994444?v=4)](https://github.com/andrey-tech "andrey-tech (18 commits)")

---

Tags

apiasyncasync-awaitasync-generatorawaitbitrixbitrix24ecmascript2018generatorjavasciptthrottlingasyncapijavascriptJSbitrixthrottlingBitrix24BX24async-generatorECMAScriptECMAScript9

### Embed Badge

![Health badge](/badges/andrey-tech-bx24-wrapper-js/health.svg)

```
[![Health](https://phpackages.com/badges/andrey-tech-bx24-wrapper-js/health.svg)](https://phpackages.com/packages/andrey-tech-bx24-wrapper-js)
```

###  Alternatives

[andrey-tech/bitrix24-api-php

Обертка на PHP7+ для работы с API Битрикс24 с использованием механизма входящих вебхуков, троттлингом запросов и логированием в файл

9874.2k](/packages/andrey-tech-bitrix24-api-php)[bnomei/kirby3-htmlhead

Kirby Plugin for a best-practice HTML Head Element extendable with snippets.

253.7k](/packages/bnomei-kirby3-htmlhead)[ufo-tech/json-rpc-bundle

The bundle for easy using json-rpc api on your project

224.6k3](/packages/ufo-tech-json-rpc-bundle)[richarddobron/bigpipe

BigPipe: Pipelining web pages for high performance built in PHP.

1110.9k](/packages/richarddobron-bigpipe)[ufo-tech/json-rpc-client-sdk

Simple clientSDK builder for any json-RPC servers

182.7k1](/packages/ufo-tech-json-rpc-client-sdk)[clue/reactphp-ssh-proxy

Async SSH proxy connector and forwarder, tunnel any TCP/IP-based protocol through an SSH server, built on top of ReactPHP

2113.2k5](/packages/clue-reactphp-ssh-proxy)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)