PHPackages                             reutskiy-a/simple-api-bitrix24 - 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. [HTTP & Networking](/categories/http)
4. /
5. reutskiy-a/simple-api-bitrix24

ActiveLibrary[HTTP & Networking](/categories/http)

reutskiy-a/simple-api-bitrix24
==============================

Simple REST API Bitrix24 client: OAuth 2.0, Webhook, flexible DB support, app installer, API Limit Handling Service

v2.1.0(1mo ago)1472MITPHPPHP ^8.1

Since Mar 18Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/reutskiy-a/simple-api-bitrix24)[ Packagist](https://packagist.org/packages/reutskiy-a/simple-api-bitrix24)[ RSS](/packages/reutskiy-a-simple-api-bitrix24/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (17)Versions (14)Used By (0)

[![Unit Tested](https://camo.githubusercontent.com/0a421e1cf01db7afd8f609bef85f581c46fdd4c06d3e6edb4048d0cffa0e2784/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e697425323054657374732d50617373696e672d627269676874677265656e)](https://camo.githubusercontent.com/0a421e1cf01db7afd8f609bef85f581c46fdd4c06d3e6edb4048d0cffa0e2784/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e697425323054657374732d50617373696e672d627269676874677265656e)[![Integration Tests](https://camo.githubusercontent.com/8f60c66c64536bf092f1b8200bd032dfe8ad11183f84b722f23d0e196ca6b3eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e746567726174696f6e25323054657374732d50617373696e672d627269676874677265656e)](https://camo.githubusercontent.com/8f60c66c64536bf092f1b8200bd032dfe8ad11183f84b722f23d0e196ca6b3eb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e746567726174696f6e25323054657374732d50617373696e672d627269676874677265656e)[![License](https://camo.githubusercontent.com/18e29809194e5e1c8357512e59570bcc168ab4961b65cad3a00b34aea59689e0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72657574736b69792d612f73696d706c652d6170692d6269747269783234)](https://camo.githubusercontent.com/18e29809194e5e1c8357512e59570bcc168ab4961b65cad3a00b34aea59689e0/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f72657574736b69792d612f73696d706c652d6170692d6269747269783234)

> REST API клиент для облачной версии Битрикс24 (совместим с REST API 2.0)

```
composer require reutskiy-a/simple-api-bitrix24
```

lang: [Русский](#%D1%87%D1%82%D0%BE-%D1%83%D0%BC%D0%B5%D0%B5%D1%82) / [English](#english)

Этот REST API клиент подойдёт тем, кому нужен быстрый старт, минимализм и вся необходимая функциональность для разработки полноценных приложений для облачной версии Битрикс24.
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[](#этот-rest-api-клиент-подойдёт-тем-кому-нужен-быстрый-старт-минимализм-и-вся-необходимая-функциональность-для-разработки-полноценных-приложений-для-облачной-версии-битрикс24)

### Что умеет:

[](#что-умеет)

- авторизация через Webhook и OAuth 2.0
- автоматическая работа с любой реляционной БД (MySQL, PostgreSQL, SQLite): быстрое создание таблицы пользователей и сохранение данных через встроенный UserRepository.
- авто‑обновление пользовательских токенов.
- сохранение и использование токенов любых пользователей портала, работа с их правами доступа.
- обработка лимитов REST API — приложение не прерывает работу при ошибках Bitrix24.
- локальные приложения могут работать, как тиражные (одно приложение - много порталов).
- сервис установки приложений.
- логирование.
- знакомый подход для тех, кто работал с CRest.

Более детальную информацию и примеры по работе с REST API клиентом смотрите в содержании ниже.

> Пример установки локального приложения:

[![Installation-demo](https://raw.githubusercontent.com/reutskiy-a/assets/main/simple-api-bitrix24/simple_api_bitrix24_v2_local-app.gif)](https://raw.githubusercontent.com/reutskiy-a/assets/main/simple-api-bitrix24/simple_api_bitrix24_v2_local-app.gif)

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

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

1. [Webhook авторизация - быстрый старт](#1-webhook-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F---%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82)
2. [OAuth 2.0 авторизация - быстрый старт](#2-oauth-20-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F---%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82)

    2.1 [Подготовка соединения с базой данных и создание таблицы пользователей](#21-%D0%BF%D0%BE%D0%B4%D0%B3%D0%BE%D1%82%D0%BE%D0%B2%D0%BA%D0%B0-%D1%81%D0%BE%D0%B5%D0%B4%D0%B8%D0%BD%D0%B5%D0%BD%D0%B8%D1%8F-%D1%81-%D0%B1%D0%B0%D0%B7%D0%BE%D0%B9-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85-%D0%B8-%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D0%BD%D0%B8%D0%B5-%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D1%8B-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D0%B5%D0%B9)

    2.2 [Создание объекта REST API клиента с OAuth 2.0 авторизацией](#22-%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D0%BD%D0%B8%D0%B5-%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%B0-rest-api-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%B0-%D1%81-oauth-20-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B5%D0%B9)

    2.3 [Установка приложения и сохранение данных пользователя в БД](#23-%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%BF%D1%80%D0%B8%D0%BB%D0%BE%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F-%D0%B8-%D1%81%D0%BE%D1%85%D1%80%D0%B0%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F-%D0%B2-%D0%B1%D0%B4)
3. [Подробно о работе с REST API клиентом](#3-%D0%BF%D0%BE%D0%B4%D1%80%D0%BE%D0%B1%D0%BD%D0%BE-%D0%BE-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B5-%D1%81-rest-api-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%BE%D0%BC)

    3.1 [Установка авторизации для REST API клиента по умолчанию](#31-%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8-%D0%B4%D0%BB%D1%8F-rest-api-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%B0-%D0%BF%D0%BE-%D1%83%D0%BC%D0%BE%D0%BB%D1%87%D0%B0%D0%BD%D0%B8%D1%8E)

    3.2 [Смена авторизации REST API клиента / работа с разными порталами или пользователями одновременно](#32-%D1%81%D0%BC%D0%B5%D0%BD%D0%B0-%D0%B0%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8-rest-api-%D0%BA%D0%BB%D0%B8%D0%B5%D0%BD%D1%82%D0%B0--%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D1%80%D0%B0%D0%B7%D0%BD%D1%8B%D0%BC%D0%B8-%D0%BF%D0%BE%D1%80%D1%82%D0%B0%D0%BB%D0%B0%D0%BC%D0%B8-%D0%B8%D0%BB%D0%B8-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F%D0%BC%D0%B8-%D0%BE%D0%B4%D0%BD%D0%BE%D0%B2%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%BD%D0%BE)

    3.3 [Сохранение данных пользователя в БД](#33-%D1%81%D0%BE%D1%85%D1%80%D0%B0%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F-%D0%B2-%D0%B1%D0%B4)

    3.4 [Работа с пользователями через UserRepository](#34-%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%B0-%D1%81-%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F%D0%BC%D0%B8-%D1%87%D0%B5%D1%80%D0%B5%D0%B7-userrepository)
4. [Настройка обработки лимитов REST API bitrix24](#4-%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0-%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B8-%D0%BB%D0%B8%D0%BC%D0%B8%D1%82%D0%BE%D0%B2-rest-api-bitrix24)
5. [Логирование](#5-%D0%BB%D0%BE%D0%B3%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
6. [Batch запросы](#6-batch-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D1%8B)

    6.1 [Обычный batch запрос](#61-%D0%BE%D0%B1%D1%8B%D1%87%D0%BD%D1%8B%D0%B9-batch-%D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81)

    6.2 [Batch сервис](#62-batch-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81)

1. Webhook авторизация - быстрый старт
--------------------------------------

[](#1-webhook-авторизация---быстрый-старт)

```
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\Connectors\Models\Webhook;
use SimpleApiBitrix24\Enums\AuthType;

$apiSettings = new ApiClientSettings(AuthType::WEBHOOK);
$apiSettings->setDefaultCredentials(new Webhook('https://test.bitrix24.ru/rest/1/b1hw1*****k12t/'));

$api = new ApiClientBitrix24($apiSettings);

print_r($api->call('crm.deal.get', ['ID' => 2]));
```

2. OAuth 2.0 авторизация - быстрый старт
----------------------------------------

[](#2-oauth-20-авторизация---быстрый-старт)

### 2.1 Подготовка соединения с базой данных и создание таблицы пользователей

[](#21-подготовка-соединения-с-базой-данных-и-создание-таблицы-пользователей)

> Используйте любую удобную базу данных: MySQL, PostgreSQL, SQLite.

```
use PDO;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\TableManager;

// Создаём объект PDO.
$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');

// Создаём объект описывающий схему будущей таблицы.
// Если нужно указать свои названия колонок и самой таблицы, то задайте их через ApiDatabaseConfig::__construct();
$databaseConfig = ApiDatabaseConfig::build($pdo);

// Создаём таблицу в базе, если она там отсутствует.
$tableManager = new TableManager($databaseConfig);
$tableManager->createUsersTableIfNotExists();   // или $tableManager->createUsersTableIfNotExists('your_table_name')
```

### 2.2 Создание объекта REST API клиента с OAuth 2.0 авторизацией

[](#22-создание-объекта-rest-api-клиента-с-oauth-20-авторизацией)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()

// Создаём объект пользователя, авторизацию которого будем использовать.
$repository = new UserRepository($databaseConfig);
$user = $repository->getUserByIdAndMemberId(1, 'bitrix24_member_id');

// создаём объект настроек REST API клиента и зададим в этом примере авторизацию по умолчанию.
// так же авторизацию можно установить или изменить методом ApiClientBitrix24::setCredentials
$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings->setDefaultCredentials($user);

// создаём объект REST API клиента
$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

print_r($api->call('crm.deal.get', ['ID' => 2]));
```

### 2.3 Установка приложения и сохранение данных пользователя в БД

[](#23-установка-приложения-и-сохранение-данных-пользователя-в-бд)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;
use SimpleApiBitrix24\Services\Installation\InstallationService;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()

$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

// сохраняем данные пользователя в базу
$user = InstallationService::createUserFromProfileAndSave(
    $databaseConfig,
    'local.693c2b5c42e7c3.81926786',
    'fDlCI34BZbbWv31iNm7H1jpwmu5py9vMyMkkVzQ3IC3WQdPQC4',
    $_REQUEST['member_id'],
    $_REQUEST['AUTH_ID'],
    $_REQUEST['REFRESH_ID'],
    $_REQUEST['DOMAIN']
);

// Тут ваша логика установки приложения
$api->setCredentials($user); // устанавливаем авторизацию для REST API клиента
print_r($api->call('scope'));

// Вызываем метод завершения установки приложения
InstallationService::finishInstallation();
```

3. Подробно о работе с REST API клиентом
----------------------------------------

[](#3-подробно-о-работе-с-rest-api-клиентом)

### 3.1 Установка авторизации для REST API клиента по умолчанию

[](#31-установка-авторизации-для-rest-api-клиента-по-умолчанию)

```
use SimpleApiBitrix24\ApiClientSettings;

$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings->setDefaultCredentials($user);
```

### 3.2 Смена авторизации REST API клиента / работа с разными порталами или пользователями одновременно

[](#32-смена-авторизации-rest-api-клиента--работа-с-разными-порталами-или-пользователями-одновременно)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;
use SimpleApiBitrix24\Services\Installation\InstallationService;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()
$apiSettings = new ApiClientSettings(AuthType::TOKEN);

// Пользователь №1
$repository = new UserRepository($databaseConfig);
$user_1 = $repository->getUserByIdAndMemberId(1, 'bitrix24_member_id_1');

$apiClient_1 = new ApiClientBitrix24($apiSettings, $databaseConfig);
$apiClient_1->setCredentials($user_1);

// Пользователь №2
$user_2 = $repository->getFirstAdminByMemberId('bitrix24_member_id_2');

$apiClient_2 = clone $apiClient_1;
$apiClient_2->setCredentials($user_2);

// далее можем работать с разными независимыми друг от друга объектами REST API клиента
print_r($apiClient_1->call('profile'));
print_r($apiClient_2->call('profile'));
```

### 3.3 Сохранение данных пользователя в БД

[](#33-сохранение-данных-пользователя-в-бд)

Будьте внимательны передавая client\_id и client\_secret в методе InstallationService::createUserFromProfileAndSave, они будут записаны в БД для каждого пользователя отдельно, что позволяет работать локальным приложениям, как тиражным (одно приложение - много порталов). Если вы укажете client\_id и client\_secret не верно для конкретного пользователя, то его токены авторизации не обновятся и REST API клиент выбросит исключение.

```
use SimpleApiBitrix24\Services\Installation\InstallationService;

// метод добавляет или обновляет данные пользователя в базе
InstallationService::createUserFromProfileAndSave(
    $databaseConfig,
    'local.693c2b5c42e7c3.81926786',
    'fDlCI34BZbbWv31iNm7H1jpwmu5py9vMyMkkVzQ3IC3WQdPQC4',
    $_REQUEST['member_id'],
    $_REQUEST['AUTH_ID'],
    $_REQUEST['REFRESH_ID'],
    $_REQUEST['DOMAIN']
);
```

### 3.4 Работа с пользователями через UserRepository

[](#34-работа-с-пользователями-через-userrepository)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\DatabaseCore\UserRepository;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()

// Все методы и описание смотрите в реализации репозитория
$repository = new UserRepository($databaseConfig);

$user = $repository->getFirstUserByMemberId('member_id');
$user = $repository->getFirstAdminByMemberId('member_id');

$users = $repository->getAllUsersByMemberId('member_id');

$repository->delete($user);
```

4. Настройка обработки лимитов REST API Bitrix24
------------------------------------------------

[](#4-настройка-обработки-лимитов-rest-api-bitrix24)

> Подробнее о лимитах REST API смотрите в официальной документации
>
>

Этот REST API клиент может обрабатывать ответы об ошибках лимитов REST API:

Пример обрабатываемых ошибок от сервера REST API:

```
{
    "error": "QUERY_LIMIT_EXCEEDED",
    "error_description": "Too many requests"
}
```

```
{
  "error": "OPERATION_TIME_LIMIT",
  "error_description": "Method is blocked due to operation time limit."
}
```

По умолчанию обработка выше перечисленных ошибок включена в этом REST API клиенте.

Как работает обработка ошибок - при получении ответа с одной из ошибок API Client будет делать повторный запрос через заданный интервал времени, не останавливая работу скрипта, делать это будет постоянно пока не завершится выполнение скрипта или не истечёт время жизни приложения.

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()

// по умолчанию обработка лимитов всегда включена при создании объекта ApiClientSettings;
// вы можете отключить или задать свой интервал для повторного запроса в микросекундах
$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings
    ->setOperationTimeLimitHandler(true, 5000000)
    ->setQueryLimitExceededHandler(true, 1000000);

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);
```

Так же REST API клиент обрабатывает по умолчанию ошибки:

- Крайне редко наблюдались пустые ответы от сервера REST API Bitrix24, в случае такой ситуации клиент сделает повторный запрос.
- Обновление токенов авторизации и сохранение новых в базе данных, в случае получения ошибки об истечении срока жизни токенов. После запрос повторится.

В остальных случаях клиент выбрасывает исключения на другие ответы с ошибками от сервера REST API Bitrix24.

5. Логирование
--------------

[](#5-логирование)

При уровне логирования DEBUG в журнал будут записываться:

- все запросы, отправленные на сервер Bitrix24, и все полученные ответы
- все исключения, возникающие в работе этого клиента

При уровне логирования WARNING в журнал будут записываться:

- запрос и ответ, если любой из элементов Batch‑запроса получил ошибку от сервера Bitrix24
- все запросы и ответы, содержащие ошибку, возвращённую сервером Bitrix24
- все исключения, возникающие в работе этого клиента

```
use Monolog\Formatter\LineFormatter;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Logger;
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // или задайте свою схему таблицы через ApiDatabaseConfig::__construct()
$apiSettings = new ApiClientSettings(AuthType::TOKEN);

$logger = new Logger('api-b24');
$handler = new RotatingFileHandler(
    storage_path('logs/rest-api-bitrix24.log'),
    15,
    Logger::DEBUG
);
$formatter = new LineFormatter(
    "[%datetime%] %level_name%: %message% %context%\n",
    'Y-m-d H:i:s',
    true
);
$formatter->setJsonPrettyPrint(true);
$handler->setFormatter($formatter);
$logger->pushHandler($handler);

$api = new ApiClientBitrix24($apiSettings, $databaseConfig, $logger);
```

6. Batch запросы
----------------

[](#6-batch-запросы)

### 6.1 Обычный batch запрос

[](#61-обычный-batch-запрос)

```
use SimpleApiBitrix24\ApiClientBitrix24;

//...

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

$result = $api->callBatch([
    ['method' => 'scope', 'params' => []],
    ['method' => 'crm.deal.list', 'params' => ['select' => ['ID', 'TITLE']]],
]);

print_r($result);
```

### 6.2 Batch сервис

[](#62-batch-сервис)

```
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\Services\Batch;

// ...

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

$batchService = new Batch($api);

// получаем все элементы сущности, работает только со списочными методами
$getAllResult = $batchService->getAll('tasks.task.list', ['filter' => ['STATUS' => 5]]);

// вернёт ответы предварительно отсортировав их по тем же ключам массива, которые вы укажете в аргументе метода.
$resultWithKeys = $batchService->callWithKeys([
    'scope_response' => ['method' => 'scope', 'params' => []],
    'deal_list_response' => ['method' => 'crm.deal.list', 'params' => ['select' => ['ID', 'TITLE']]],
])
```

### English:

[](#english)

This REST API client is ideal for those who need a quick start, minimalism, and all the essential functionality for building full‑featured applications for the cloud version of Bitrix24.
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[](#this-rest-api-client-is-ideal-for-those-who-need-a-quick-start-minimalism-and-all-the-essential-functionality-for-building-fullfeatured-applications-for-the-cloud-version-of-bitrix24)

### Features:

[](#features)

- authorization via Webhook and OAuth 2.0
- automatic integration with any relational database (MySQL, PostgreSQL, SQLite): fast user table creation and data persistence through the built‑in UserRepository
- automatic refresh of user access tokens
- storing and using tokens of any portal users, working with their access permissions
- REST API rate‑limit handling — the application does not stop when Bitrix24 returns errors
- local applications can operate as multi‑tenant apps (one application for many portals)
- application installation service
- logging
- familiar workflow for those who have used CRest

For more detailed information and usage examples, see the sections below.

> Example of installing a local application:

[![Installation-demo](https://raw.githubusercontent.com/reutskiy-a/assets/main/simple-api-bitrix24/simple_api_bitrix24_v2_local-app.gif)](https://raw.githubusercontent.com/reutskiy-a/assets/main/simple-api-bitrix24/simple_api_bitrix24_v2_local-app.gif)

Table of Contents:
------------------

[](#table-of-contents)

1. [Webhook Authorization — Quick Start](#1-webhook-authorization--quick-start)
2. [OAuth 2.0 Authorization — Quick Start](#2-oauth-20-authorization--quick-start)

    2.1 [Preparing the database connection and creating the users table](#21-preparing-the-database-connection-and-creating-the-users-table)

    2.2 [Creating a REST API client with OAuth 2.0 authorization](#22-creating-a-rest-api-client-with-oauth-20-authorization)

    2.3 [Application installation and saving user data to the database](#23-application-installation-and-saving-user-data-to-the-database)
3. [Detailed usage of the REST API client](#3-detailed-usage-of-the-rest-api-client)

    3.1 [Setting default authorization for the REST API client](#31-setting-default-authorization-for-the-rest-api-client)

    3.2 [Switching authorization / working with multiple portals or users simultaneously](#32-switching-authorization--working-with-multiple-portals-or-users-simultaneously)

    3.3 [Saving user data to the database](#33-saving-user-data-to-the-database)

    3.4 [Working with users via UserRepository](#34-working-with-users-via-userrepository)
4. [Configuring Bitrix24 REST API rate‑limit handling](#4-configuring-bitrix24-rest-api-ratelimit-handling)
5. [Logging](#5-logging)
6. [Batch requests](#6-batch-requests)

    6.1 [Basic batch request](#61-basic-batch-request)

    6.2 [Batch service](#62-batch-service)

1. Webhook Authorization — Quick Start
--------------------------------------

[](#1-webhook-authorization--quick-start)

```
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\Connectors\Models\Webhook;
use SimpleApiBitrix24\Enums\AuthType;

$apiSettings = new ApiClientSettings(AuthType::WEBHOOK);
$apiSettings->setDefaultCredentials(new Webhook('https://test.bitrix24.ru/rest/1/b1hw1*****k12t/'));

$api = new ApiClientBitrix24($apiSettings);

print_r($api->call('crm.deal.get', ['ID' => 2]));
```

2. OAuth 2.0 Authorization — Quick Start
----------------------------------------

[](#2-oauth-20-authorization--quick-start)

### 2.1 Preparing the database connection and creating the users table

[](#21-preparing-the-database-connection-and-creating-the-users-table)

> You can use any relational database: MySQL, PostgreSQL, SQLite.

```
use PDO;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\TableManager;

// Create a PDO instance
$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');

// Create a database configuration object.
// If you need custom table or column names, pass them via ApiDatabaseConfig::__construct()
$databaseConfig = ApiDatabaseConfig::build($pdo);

// Create the users table if it does not exist
$tableManager = new TableManager($databaseConfig);
$tableManager->createUsersTableIfNotExists();   // or $tableManager->createUsersTableIfNotExists('your_table_name')
```

### 2.2 Creating a REST API client with OAuth 2.0 authorization

[](#22-creating-a-rest-api-client-with-oauth-20-authorization)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);

// Load a user whose authorization tokens will be used
$repository = new UserRepository($databaseConfig);
$user = $repository->getUserByIdAndMemberId(1, 'bitrix24_member_id');

// Create settings and set default credentials
$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings->setDefaultCredentials($user);

// Create the REST API client
$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

print_r($api->call('crm.deal.get', ['ID' => 2]));
```

### 2.3 Application installation and saving user data to the database

[](#23-application-installation-and-saving-user-data-to-the-database)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;
use SimpleApiBitrix24\Services\Installation\InstallationService;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);

$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

// Create and save the user in the database
$user = InstallationService::createUserFromProfileAndSave(
    $databaseConfig,
    'local.693c2b5c42e7c3.81926786',
    'fDlCI34BZbbWv31iNm7H1jpwmu5py9vMyMkkVzQ3IC3WQdPQC4',
    $_REQUEST['member_id'],
    $_REQUEST['AUTH_ID'],
    $_REQUEST['REFRESH_ID'],
    $_REQUEST['DOMAIN']
);

// Your installation logic here
$api->setCredentials($user);
print_r($api->call('scope'));

// Finalize installation
InstallationService::finishInstallation();
```

3. Detailed usage of the REST API client
----------------------------------------

[](#3-detailed-usage-of-the-rest-api-client)

### 3.1 Setting default authorization for the REST API client

[](#31-setting-default-authorization-for-the-rest-api-client)

```
use SimpleApiBitrix24\ApiClientSettings;

$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings->setDefaultCredentials($user);
```

### 3.2 Switching authorization / working with multiple portals or users simultaneously

[](#32-switching-authorization--working-with-multiple-portals-or-users-simultaneously)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\DatabaseCore\UserRepository;
use SimpleApiBitrix24\Enums\AuthType;
use SimpleApiBitrix24\Services\Installation\InstallationService;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // If you need custom table or column names, pass them via ApiDatabaseConfig::__construct()
$apiSettings = new ApiClientSettings(AuthType::TOKEN);

// User #1
$repository = new UserRepository($databaseConfig);
$user_1 = $repository->getUserByIdAndMemberId(1, 'bitrix24_member_id_1');

$apiClient_1 = new ApiClientBitrix24($apiSettings, $databaseConfig);
$apiClient_1->setCredentials($user_1);

// User #2
$user_2 = $repository->getFirstAdminByMemberId('bitrix24_member_id_2');

$apiClient_2 = clone $apiClient_1;
$apiClient_2->setCredentials($user_2);

// Now both clients work independently
print_r($apiClient_1->call('profile'));
print_r($apiClient_2->call('profile'));
```

### 3.3 Saving user data to the database

[](#33-saving-user-data-to-the-database)

Be careful when passing client\_id and client\_secret to InstallationService::createUserFromProfileAndSave. They are stored per user, enabling local apps to behave like multi‑tenant apps. If you provide incorrect values, token refresh will fail and the client will throw an exception.

```
use SimpleApiBitrix24\Services\Installation\InstallationService;

InstallationService::createUserFromProfileAndSave(
    $databaseConfig,
    'local.693c2b5c42e7c3.81926786',
    'fDlCI34BZbbWv31iNm7H1jpwmu5py9vMyMkkVzQ3IC3WQdPQC4',
    $_REQUEST['member_id'],
    $_REQUEST['AUTH_ID'],
    $_REQUEST['REFRESH_ID'],
    $_REQUEST['DOMAIN']
);
```

### 3.4 Working with users via UserRepository

[](#34-working-with-users-via-userrepository)

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\DatabaseCore\UserRepository;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // If you need custom table or column names, pass them via ApiDatabaseConfig::__construct()

// All methods and description can be found in the repository implementation
$repository = new UserRepository($databaseConfig);

$user = $repository->getFirstUserByMemberId('member_id');
$user = $repository->getFirstAdminByMemberId('member_id');

$users = $repository->getAllUsersByMemberId('member_id');

$repository->delete($user);
```

4. Configuring Bitrix24 REST API rate‑limit handling
----------------------------------------------------

[](#4-configuring-bitrix24-rest-api-ratelimit-handling)

> For more details on Bitrix24 REST API limits, see:
>
>

This client can automatically handle REST API rate‑limit errors.

Examples of handled errors:

```
{
    "error": "QUERY_LIMIT_EXCEEDED",
    "error_description": "Too many requests"
}
```

```
{
  "error": "OPERATION_TIME_LIMIT",
  "error_description": "Method is blocked due to operation time limit."
}
```

By default, rate‑limit handling is enabled.

When such an error occurs, the client retries the request after a configured delay, continuing until the script finishes or the application lifetime ends.

```
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);

// by default, limit processing is always enabled when creating an ApiClientSettings object;
// you can disable it or set your own interval for re-request in microseconds
$apiSettings = new ApiClientSettings(AuthType::TOKEN);
$apiSettings
    ->setOperationTimeLimitHandler(true, 5000000)
    ->setQueryLimitExceededHandler(true, 1000000);

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);
```

Additionally, the client handles:

- rare cases of empty responses from Bitrix24 (automatically retries)
- token refresh and saving new tokens to the database

All other errors result in exceptions.

5. Logging
----------

[](#5-logging)

With the DEBUG logging level, the following will be recorded:

- all requests sent to the Bitrix24 server and all responses received
- any exceptions thrown by this client

With the WARNING logging level, the following will be recorded:

- the request and response if any key within a Batch request returns an error from the Bitrix24 server
- all requests and responses that contain an error returned by the Bitrix24 server
- any exceptions thrown by this client

```
use Monolog\Formatter\LineFormatter;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Logger;
use PDO;
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\ApiClientSettings;
use SimpleApiBitrix24\ApiDatabaseConfig;
use SimpleApiBitrix24\Enums\AuthType;

$pdo = new PDO('mysql:host=localhost;port=3306;dbname=test', 'root', 'password');
$databaseConfig = ApiDatabaseConfig::build($pdo);   // If you need custom table or column names, pass them via ApiDatabaseConfig::__construct()
$apiSettings = new ApiClientSettings(AuthType::TOKEN);

$logger = new Logger('api-b24');
$handler = new RotatingFileHandler(
    storage_path('logs/rest-api-bitrix24.log'),
    15,
    Logger::DEBUG
);
$formatter = new LineFormatter(
    "[%datetime%] %level_name%: %message% %context%\n",
    'Y-m-d H:i:s',
    true
);
$formatter->setJsonPrettyPrint(true);
$handler->setFormatter($formatter);
$logger->pushHandler($handler);

$api = new ApiClientBitrix24($apiSettings, $databaseConfig, $logger);
```

6. Batch requests
-----------------

[](#6-batch-requests)

### 6.1 Basic batch request

[](#61-basic-batch-request)

```
use SimpleApiBitrix24\ApiClientBitrix24;

//...

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

$result = $api->callBatch([
    ['method' => 'scope', 'params' => []],
    ['method' => 'crm.deal.list', 'params' => ['select' => ['ID', 'TITLE']]],
]);

print_r($result);
```

### 6.2 Batch service

[](#62-batch-service)

```
use SimpleApiBitrix24\ApiClientBitrix24;
use SimpleApiBitrix24\Services\Batch;

// ...

$api = new ApiClientBitrix24($apiSettings, $databaseConfig);

$batchService = new Batch($api);

// Retrieve all items of an entity (works only with list‑type methods)
$getAllResult = $batchService->getAll('tasks.task.list', ['filter' => ['STATUS' => 5]]);

// Returns responses sorted by the same keys you provide
$resultWithKeys = $batchService->callWithKeys([
    'scope_response' => ['method' => 'scope', 'params' => []],
    'deal_list_response' => ['method' => 'crm.deal.list', 'params' => ['select' => ['ID', 'TITLE']]],
])
```

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance92

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity53

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 ~34 days

Recently: every ~22 days

Total

12

Last Release

40d ago

Major Versions

v1.2.0 → v2.0.02026-01-02

### Community

Maintainers

![](https://www.gravatar.com/avatar/3b0a3136bb2a1ff8774b9b5ad139c4ab765e311dea18df338f1a40b16253d65d?d=identicon)[Reutskiy](/maintainers/Reutskiy)

---

Top Contributors

[![reutskiy-a](https://avatars.githubusercontent.com/u/118709337?v=4)](https://github.com/reutskiy-a "reutskiy-a (42 commits)")

---

Tags

phpapisdkrestbitrixSimpleBitrix24b24

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/reutskiy-a-simple-api-bitrix24/health.svg)

```
[![Health](https://phpackages.com/badges/reutskiy-a-simple-api-bitrix24/health.svg)](https://phpackages.com/packages/reutskiy-a-simple-api-bitrix24)
```

###  Alternatives

[huaweicloud/huaweicloud-sdk-php

Huawei Cloud SDK for PHP

1829.2k2](/packages/huaweicloud-huaweicloud-sdk-php)[onesignal/onesignal-php-api

A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com

34170.2k2](/packages/onesignal-onesignal-php-api)[ory/hydra-client

Documentation for all of Ory Hydra's APIs.

17435.9k](/packages/ory-hydra-client)[zenditplatform/zendit-php-sdk

PHP client for Zendit API

1204.3k](/packages/zenditplatform-zendit-php-sdk)[ory/hydra-client-php

Documentation for all of Ory Hydra's APIs.

1710.8k](/packages/ory-hydra-client-php)

PHPackages © 2026

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