Download the PHP package reutskiy-a/simple-api-bitrix24 without Composer

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

lang: English

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

Что умеет:

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

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

Пример установки локального приложения: https://github.com/reutskiy-a/simple-api-bitrix24/tree/master/examples

Содержание:

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

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

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

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

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

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

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

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

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

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

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

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

6. Batch запросы

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

   6.2 Batch сервис

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://apidocs.bitrix24.ru/limits.html

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

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

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

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

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

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

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

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

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

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

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

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

6. Batch запросы

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

6.2 Batch сервис

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.

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: https://github.com/reutskiy-a/simple-api-bitrix24/tree/master/examples

Table of Contents:

1. Webhook Authorization — Quick Start

2. OAuth 2.0 Authorization — Quick Start

   2.1 Preparing the database connection and creating the users table

   2.2 Creating a REST API client with OAuth 2.0 authorization

   2.3 Application installation and saving user data to the database

3. Detailed usage of the REST API client

   3.1 Setting default authorization for the REST API client

   3.2 Switching authorization / working with multiple portals or users simultaneously

   3.3 Saving user data to the database

   3.4 Working with users via UserRepository

4. Configuring Bitrix24 REST API rate‑limit handling

5. Logging

6. Batch requests

   6.1 Basic batch request

   6.2 Batch service

1. Webhook Authorization — Quick Start

2. OAuth 2.0 Authorization — Quick Start

2.1 Preparing the database connection and creating the users table

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

2.2 Creating a REST API client with OAuth 2.0 authorization

2.3 Application installation and saving user data to the database

3. Detailed usage of the REST API client

3.1 Setting default authorization for the REST API client

3.2 Switching authorization / working with multiple portals or users simultaneously

3.3 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.

3.4 Working with users via UserRepository

4. Configuring Bitrix24 REST API rate‑limit handling

For more details on Bitrix24 REST API limits, see:

https://apidocs.bitrix24.com/limits.html

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

Examples of handled errors:

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.

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

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

6. Batch requests

6.1 Basic batch request

6.2 Batch service