reutskiy-a/simple-api-bitrix24

Simple REST API Bitrix24 client: OAuth 2.0, Webhook, flexible DB support, app installer.

Maintainers

Details

github.com/reutskiy-a/simple-api-bitrix24

Source

Issues

Installs: 7

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 1

Forks: 0

Open Issues: 0

v1.0.2 2025-03-20 04:12 UTC

Requires

Requires (Dev)

MIT ade675f190bf35d95d9a19ae9cebddb2a69cb617

phprestapisdkSimplebitrixBitrix24b24

This package is not auto-updated.

Last update: 2025-03-21 04:06:31 UTC

README

Unit Tested Integration Tests License

Simple REST API Bitrix24 client: OAuth 2.0, Webhook, flexible DB support, app installer.

Клиент для REST API Bitrix24:

OAuth 2.0 (с автообновлением токенов), Webhook, поддержка всех популярных реляционных БД, менеджер установки локальных/тиражных приложений. Установка одного локального приложения на несколько порталов.

Installation

composer require reutskiy-a/simple-api-bitrix24

LANGUAGE:

Русский

English

Русский:

Содержание:

  1. Быстрый старт: Webhook соединение

  2. Соединение OAuth 2.0 (Локальное или Тиражное приложение)

    2.1. Подготовка базы данных для хранения токенов

    2.2. Создание объекта соединения OAuth 2.0

    2.3. Установка приложения

  3. Смена соединения или клонирование объекта соединения

  4. Логирование

    4.1. Debug логирование

    4.2. Рекомендуемый уровень логирования

  5. Пакетные запросы

    5.1 Стандартный пакетный запрос

    5.2 Сервис списочных методов для получения всех элементов

1. Быстрый старт Webhook соединение

    use SimpleApiBitrix24\ApiClientSettings;
    use SimpleApiBitrix24\ApiClientBitrix24;

    $apiSettings = new ApiClientSettings();
    $apiSettings->setWebhookAuthEnabled(true)
                ->setDefaultConnection('https://portal.bitrix24.ru/rest/1/cj03r****1wbeg/');

    $api = new ApiClientBitrix24($apiSettings);
    
    $result = $api->call('crm.deal.get', ['ID' => 1]);

2. Соединение OAuth 2.0 (Локальное или Тиражное приложение)

Вы можете устанавливать одно и тоже локальное приложение на разные порталы. Только следите за корректностью client_id и client_secret при установке, иначе токены не обновятся, когда их время жизни закончится, и приложение выбросит исключение.

2.1 Подготовка базы данных для хранения токенов

Используйте любую удобную базу данных:

  • PostgreSQL
  • MySQL
  • SQLite
  • SQLServer

Создайте таблицу в базе данных. Пример запроса для MySQL:

    CREATE TABLE api_tokens_bitrix24(
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    member_id VARCHAR(255) UNIQUE NOT NULL,
    access_token VARCHAR(255) NOT NULL,
    expires_in VARCHAR(255) NOT NULL,
    application_token VARCHAR(255) NOT NULL,
    refresh_token VARCHAR(255) NOT NULL,
    domain VARCHAR(255) NOT NULL,
    client_endpoint VARCHAR(255) NOT NULL,
    client_id VARCHAR(255) NOT NULL,
    client_secret VARCHAR(255) NOT NULL
    );

2.2 Создание объекта соединения OAuth 2.0

    use SimpleApiBitrix24\ApiDatabaseConfig;
    use SimpleApiBitrix24\ApiClientSettings;
    use SimpleApiBitrix24\ApiClientBitrix24;

    $pdo = new PDO('mysql:host=172.17.0.1;port=3306;dbname=bitrix24', 'root', 'password'); // Ваши настройки подключения к базе

    $databaseConfig = new ApiDatabaseConfig(
        pdo: $pdo,
        tableName: 'api_tokens_bitrix24',
        primaryKeyColumnName: 'id',
        memberIdColumnName: 'member_id',
        accessTokenColumnName: 'access_token',
        expiresInColumnName: 'expires_in',
        applicationTokenColumnName: 'application_token',
        refreshTokenColumnName: 'refresh_token',
        domainColumnName: 'domain',
        clientEndpointColumnName: 'client_endpoint',
        clientIdColumnName: 'client_id',
        clientSecretColumnName: 'client_secret'
    );

    $apiSettings = new ApiClientSettings();
    $apiSettings->setTokenAuthEnabled(true)
                ->setDefaultConnection('your_member_id');

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

    $result = $api->call('crm.deal.get', ['ID' => 1]);

Если надо динамически устанавливать соединение к порталу на входящий $_REQUEST['member_id'], то делайте так:

    // ...
    
    $apiSettings = new ApiClientSettings();
    $apiSettings->setTokenAuthEnabled(true);
    
    $api = new ApiClientBitrix24($apiSettings, $databaseConfig);
    $api->connectTo($_REQUEST['member_id']);
    
    $result = $api->call('crm.deal.get', ['ID' => 1]);

2.3 Установка приложения

    use SimpleApiBitrix24\Services\Installation\InstallationService;
    
    // старт установки (добавление пользователя в базу данных)
    $installationService = new InstallationService();
    $installationService->startInstallation(
        'local.67c9b****83.1668***79',                              // client id
        '7KriLM5****T6tCgVSqUj2ILZFms5*****keBzYbzqso',             // client secret
        $databaseConfig,                                            // SimpleApiBitrix24\ApiDatabaseConfig, пример создания объекта выше
        $_REQUEST
    );
    
    // тут логика установки приложения, если требуется.
    $api->connectTo($_REQUEST['member_id']);                        // SimpleApiBitrix24\ApiClientBitrix24, пример создания объекта выше 
    $result = $api->call('scope');

    // завершение установки
    $installationService->finishInstallation();                     // перезагрузка страницы на index

3. Смена соединения или клонирование объекта соединения

Смена/установка соединения

    $api->connectTo('member_id__or__webhook_url');

Клонирование объекта соединения, если нужно работать одновременно с разными порталами Битрикс24.

    $secondApi = clone $firstApi;                                   // объект SimpleApiBitrix24\ApiClientBitrix24
    $secondApi->connectTo('new_member_id__or__webhook_url');        // получаем второй объект с соединением к другому порталу

4. Логирование

Используйте любой пакет для логирования реализующий PSR-3: Logger Interface.

В примере будет пакет monolog/monolog.

4.1 Debug логирование

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

    use Monolog\Formatter\LineFormatter;
    use Monolog\Handler\RotatingFileHandler;
    use Monolog\Logger;

    $logger = new Logger('api-b24');
        
    $handler = new RotatingFileHandler(
        '/var/www/poject/storage/logs/api-b24.log',                     // ваша путь для логов
        5,
    Logger::DEBUG
    );
    
    $formatter = new LineFormatter(
        "[%datetime%] %level_name%: %message% %context%\n",
        'Y-m-d H:i:s',
        true
    );
    $handler->setFormatter($formatter);
    $logger->pushHandler($handler);

    $api = new ApiClientBitrix24($apiSettings, null, $logger);          // SimpleApiBitrix24\ApiClientBitrix24, пример создания объекта выше

4.2 Рекомендуемый уровень логирования

Рекомендуемый уровень логирования WARNING. В логи попадут только ответы сервера Bitrix24 с ошибками, или исключения этого пакета SimpleApiBitrix24.

    // ...
    
    $handler = new RotatingFileHandler(
        '/var/www/poject/storage/logs/api-b24.log',                     // ваша путь для логов
        5,
    Logger::WARNING
    );
    
    // ...

5. Пакетные запросы

5.1 Стандартный пакетный запрос

Про все ограничения запросов в официальной документации https://apidocs.bitrix24.ru/limits.html

В один пакетный запрос можно завернуть до 50 запросов.

    $result = $api->callBatch([
        [
            'method' => 'crm.deal.get',
            'params' => ['id' => 1]
        ],
        [
            'method' => 'tasks.deal.get',
            'params' => ['id' => 2]
        ],
    ]);

5.2 Сервис списочных методов для получения всех элементов

SimpleApiBitrix24\Services\Batch::getAll() работает только с методами списочного типа. Возвращает все элементы указанной сущости.

    use SimpleApiBitrix24\Services\Batch;
    
    $batchService = new Batch($api);                   // $api объект SimpleApiBitrix24\ApiClientBitrix24
    $tasks = $batchService->getAll('tasks.task.list', ['filter' => ['STATUS' => 5]]);

English

Client for Bitrix24 REST API:

OAuth 2.0 (with automatic token refresh), Webhook, support for all popular relational databases, manager for installing local/distributed applications. Installation of a single local application across multiple portals.

Table of Contents:

  1. Quick Start: Webhook Connection

  2. OAuth 2.0 Connection (Local or Edition App))

    2.1. Preparing the Database for Token Storage

    2.2. Creating an OAuth 2.0 Connection Object

    2.3. App Installation

  3. Switching or Cloning the Connection

  4. Logging

    4.1. Debug Logging

    4.2. Recommended Logging Level

  5. Batch Requests

    5.1 Standard Batch Request

    5.2 Service for List Methods to Retrieve All Items

1. Quick Start: Webhook Connection

    use SimpleApiBitrix24\ApiClientSettings;
    use SimpleApiBitrix24\ApiClientBitrix24;

    $apiSettings = new ApiClientSettings();
    $apiSettings->setWebhookAuthEnabled(true)
                ->setDefaultConnection('https://portal.bitrix24.ru/rest/1/cj03r****1wbeg/');

    $api = new ApiClientBitrix24($apiSettings);
    
    $result = $api->call('crm.deal.get', ['ID' => 1]);

2. OAuth 2.0 Connection (Local or Edition App

You can install the same local app on different portals. Ensure client_id and client_secret are correct during installation, otherwise tokens won’t refresh when they expire, and the app will throw an exception.

2.1 Preparing the Database for Token Storage

Use any database of your choice:

  • PostgreSQL
  • MySQL
  • SQLite
  • SQLServer

Create a table in the database. Example query for MySQL:

    CREATE TABLE api_tokens_bitrix24(
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    member_id VARCHAR(255) UNIQUE NOT NULL,
    access_token VARCHAR(255) NOT NULL,
    expires_in VARCHAR(255) NOT NULL,
    application_token VARCHAR(255) NOT NULL,
    refresh_token VARCHAR(255) NOT NULL,
    domain VARCHAR(255) NOT NULL,
    client_endpoint VARCHAR(255) NOT NULL,
    client_id VARCHAR(255) NOT NULL,
    client_secret VARCHAR(255) NOT NULL
    );

2.2 Creating an OAuth 2.0 Connection Object

    use SimpleApiBitrix24\ApiDatabaseConfig;
    use SimpleApiBitrix24\ApiClientSettings;
    use SimpleApiBitrix24\ApiClientBitrix24;

    $pdo = new PDO('mysql:host=172.17.0.1;port=3306;dbname=bitrix24', 'root', 'password'); // Your database connection settings

    $databaseConfig = new ApiDatabaseConfig(
        pdo: $pdo,
        tableName: 'api_tokens_bitrix24',
        primaryKeyColumnName: 'id',
        memberIdColumnName: 'member_id',
        accessTokenColumnName: 'access_token',
        expiresInColumnName: 'expires_in',
        applicationTokenColumnName: 'application_token',
        refreshTokenColumnName: 'refresh_token',
        domainColumnName: 'domain',
        clientEndpointColumnName: 'client_endpoint',
        clientIdColumnName: 'client_id',
        clientSecretColumnName: 'client_secret'
    );

    $apiSettings = new ApiClientSettings();
    $apiSettings->setTokenAuthEnabled(true)
                ->setDefaultConnection('your_member_id');

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

    $result = $api->call('crm.deal.get', ['ID' => 1]);

To dynamically set the connection based on $_REQUEST['member_id'], do this:

    // ...
    
    $apiSettings = new ApiClientSettings();
    $apiSettings->setTokenAuthEnabled(true);
    
    $api = new ApiClientBitrix24($apiSettings, $databaseConfig);
    $api->connectTo($_REQUEST['member_id']);
    
    $result = $api->call('crm.deal.get', ['ID' => 1]);

2.3 App Installation

    use SimpleApiBitrix24\Services\Installation\InstallationService;
    
    // Start installation (add user to the database)
    $installationService = new InstallationService();
    $installationService->startInstallation(
        'local.67c9b****83.1668***79',                              // client id
        '7KriLM5****T6tCgVSqUj2ILZFms5*****keBzYbzqso',             // client secret
        $databaseConfig,                                            // SimpleApiBitrix24\ApiDatabaseConfig, see creation example above
        $_REQUEST
    );
    
    // Add your app installation logic here, if needed
    $api->connectTo($_REQUEST['member_id']);                        // SimpleApiBitrix24\ApiClientBitrix24, see creation example above
    $result = $api->call('scope');

    // Finish installation
    $installationService->finishInstallation();                     // Reloads the page to index

3. Switching or Cloning the Connection

Switching/setting a connection:

    $api->connectTo('member_id__or__webhook_url');                  // SimpleApiBitrix24\ApiClientBitrix24 object

Cloning the connection object to work with multiple Bitrix24 portals simultaneously:

    $secondApi = clone $firstApi;                                   // SimpleApiBitrix24\ApiClientBitrix24 object
    $secondApi->connectTo('new_member_id__or__webhook_url');        // Creates a second object connected to another portal

4. Logging

Use any PSR-3 Logger Interface compatible logging package.

The example below uses monolog/monolog.

4.1 Debug Logging

At the DEBUG logging level, all requests and responses will be logged.

    use Monolog\Formatter\LineFormatter;
    use Monolog\Handler\RotatingFileHandler;
    use Monolog\Logger;

    $logger = new Logger('api-b24');
        
    $handler = new RotatingFileHandler(
        '/var/www/poject/storage/logs/api-b24.log',                     // Your log file path
        5,
    Logger::DEBUG
    );
    
    $formatter = new LineFormatter(
        "[%datetime%] %level_name%: %message% %context%\n",
        'Y-m-d H:i:s',
        true
    );
    $handler->setFormatter($formatter);
    $logger->pushHandler($handler);

    $api = new ApiClientBitrix24($apiSettings, null, $logger);          // SimpleApiBitrix24\ApiClientBitrix24, see creation example above

4.2 Recommended Logging Level

The recommended logging level is WARNING.

Only Bitrix24 server error responses or exceptions from this SimpleApiBitrix24 package will be logged.

    // ...
    
    $handler = new RotatingFileHandler(
        '/var/www/poject/storage/logs/api-b24.log',                     // Your log file path
        5,
    Logger::WARNING
    );
    
    // ...

5. Batch Requests

5.1 Standard Batch Request

See all request limits in the official documentation: https://apidocs.bitrix24.com/limits.html

Up to 50 requests can be included in a single batch request.

    $result = $api->callBatch([
        [
            'method' => 'crm.deal.get',
            'params' => ['id' => 1]
        ],
        [
            'method' => 'tasks.deal.get',
            'params' => ['id' => 2]
        ],
    ]);

5.2 Service for List Methods to Retrieve All Items

SimpleApiBitrix24\Services\Batch::getAll() works only with list-type methods and retrieves all items of the specified entity.

    use SimpleApiBitrix24\Services\Batch;
    
    $batchService = new Batch($api);                   // $api is an instance of SimpleApiBitrix24\ApiClientBitrix24
    $tasks = $batchService->getAll('tasks.task.list', ['filter' => ['STATUS' => 5]]);