Как работать с REST API Bitrix24 на PHP: авторизация, вебхуки и примеры запросов

REST API Bitrix24 — главный способ интеграции внешних сервисов с CRM. В этой статье разберём три подхода к авторизации, покажем реальные примеры запросов на PHP и объясним, чем входящие вебхуки отличаются от исходящих.

Три способа авторизации в REST API Bitrix24

1. Входящий вебхук (Incoming webhook)

Самый простой вариант для личного использования или внутренних скриптов. Создаётся в разделе Приложения → Вебхуки → Входящий вебхук.

URL вебхука выглядит так:

https://your-domain.bitrix24.ru/rest/1/ваш_токен/

Достаточно просто добавить метод в конец URL:

$result = file_get_contents(
    "https://your-domain.bitrix24.ru/rest/1/TOKEN/crm.contact.list.json"
    . "?FILTER[NAME]=Иван&SELECT[]=ID&SELECT[]=NAME&SELECT[]=PHONE"
);

2. OAuth 2.0 (для публичных приложений)

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

3. Серверный OAuth с refresh token

Для долгоживущих интеграций. Access token истекает через 1 час, поэтому нужно автоматически его обновлять через refresh_token.

function refreshToken(string $refreshToken): array {
    $response = file_get_contents(
        "https://oauth.bitrix.info/oauth/token/"
        . "?grant_type=refresh_token"
        . "&client_id=" . CLIENT_ID
        . "&client_secret=" . CLIENT_SECRET
        . "&refresh_token=" . $refreshToken
    );
    return json_decode($response, true);
}

Класс-обёртка для удобной работы с API

class B24Api {
    private string $webhookUrl;

    public function __construct(string $domain, string $userId, string $token) {
        $this->webhookUrl = "https://{$domain}/rest/{$userId}/{$token}/";
    }

    public function call(string $method, array $params = []): array {
        $url = $this->webhookUrl . $method . ".json";
        $context = stream_context_create([
            "http" => [
                "method"  => "POST",
                "header"  => "Content-Type: application/x-www-form-urlencoded\r\n",
                "content" => http_build_query($params),
                "timeout" => 15,
            ]
        ]);
        $response = file_get_contents($url, false, $context);
        if ($response === false) {
            throw new \RuntimeException("B24 API request failed: {$method}");
        }
        $data = json_decode($response, true);
        if (!empty($data["error"])) {
            throw new \RuntimeException($data["error_description"] ?? $data["error"]);
        }
        return $data["result"] ?? $data;
    }
}

// Использование:
$b24 = new B24Api("company.bitrix24.ru", "1", "your_token");
$contacts = $b24->call("crm.contact.list", [
    "filter" => ["TYPE_ID" => "CLIENT"],
    "select" => ["ID", "NAME", "PHONE", "EMAIL"],
    "start"  => 0,
]);

Постраничная выборка (pagination)

Большинство методов возвращают не более 50 записей за раз. Чтобы получить все записи, используйте параметр start:

function getAllItems(B24Api $b24, string $method, array $params = []): array {
    $result = [];
    $start  = 0;
    do {
        $params["start"] = $start;
        $response = $b24->call($method, $params);
        $result = array_merge($result, $response);
        $start += 50;
    } while (count($response) === 50);
    return $result;
}

Исходящий вебхук (Outgoing webhook)

Исходящий вебхук — это когда Bitrix24 сам отправляет данные на ваш сервер при наступлении события (новый лид, изменение сделки и т.д.). Настраивается в Приложения → Вебхуки → Исходящий вебхук.

Bitrix24 пришлёт POST-запрос с данными события. Пример обработки:

// your-handler.php
$event  = $_POST["event"] ?? "";
$data   = $_POST["data"]  ?? [];
$auth   = $_POST["auth"]  ?? [];

if ($event === "ONCRMLEADADD") {
    $leadId = $data["FIELDS"]["ID"] ?? null;
    // обрабатываем новый лид
    file_put_contents("/tmp/b24_lead.log", json_encode($_POST) . "\n", FILE_APPEND);
}

Полезные методы API

Итог

REST API Bitrix24 достаточно прост в освоении: для начала хватит входящего вебхука и базового класса-обёртки. Главное помнить о постраничной выборке при работе с большими списками и правильно обрабатывать ошибки в ответе API.