Bitrix24 REST API: создание приложения на PHP с нуля

Bitrix24 REST API позволяет интегрировать внешние сервисы с корпоральным порталом: управлять задачами, сделками CRM, пользователями и отправлять уведомления. Разберём как создать приложение с нуля.

Способы подключения к API

1. Входящий вебхук — простой URL с токеном, без OAuth
2. Локальное приложение — OAuth 2.0 для конкретного портала
3. Тиражное приложение — OAuth 2.0 для публикации в маркетплейс

Входящий вебхук — быстрый старт

В Bitrix24: Приложения → Вебхуки → Добавить входящий вебхук.

// Базовый запрос через file_get_contents
$webhookUrl = 'https://your-portal.bitrix24.ru/rest/1/your_token/';

function b24Call(string $method, array $params = [], string $webhookUrl = ''): array
{
    $url  = $webhookUrl . $method . '.json';
    $opts = [
        'http' => [
            'method'  => 'POST',
            'header'  => 'Content-Type: application/x-www-form-urlencoded',
            'content' => http_build_query($params),
            'timeout'=> 30,
        ],
    ];
    $response = file_get_contents($url, false, stream_context_create($opts));
    return json_decode($response, true) ?? [];
}

// Получить список пользователей
$result = b24Call('user.get', ['ACTIVE' => true], $webhookUrl);
print_r($result['result']);

Работа с CRM (сделки, контакты, лиды)

// Получить список сделок
$deals = b24Call('crm.deal.list', [
    'order'  => ['DATE_CREATE' => 'DESC'],
    'filter' => ['STAGE_ID' => 'WON'],
    'select' => ['ID', 'TITLE', 'OPPORTUNITY', 'CONTACT_ID'],
    'start'  => 0,
], $webhookUrl);

// Создать сделку
$newDeal = b24Call('crm.deal.add', [
    'fields' => [
        'TITLE'       => 'Новая сделка',
        'STAGE_ID'    => 'NEW',
        'OPPORTUNITY' => 150000,
        'CURRENCY_ID' => 'RUB',
        'ASSIGNED_BY_ID' => 1,
    ],
], $webhookUrl);

echo 'Создана сделка ID: ' . $newDeal['result'];

Работа с задачами

// Список задач пользователя
$tasks = b24Call('tasks.task.list', [
    'filter'  => ['RESPONSIBLE_ID' => 1, 'STATUS' => 2], // в работе
    'select'  => ['ID', 'TITLE', 'DEADLINE', 'STATUS'],
    'order'   => ['DEADLINE' => 'ASC'],
], $webhookUrl);

// Создать задачу
$task = b24Call('tasks.task.add', [
    'fields' => [
        'TITLE'          => 'Проверить интеграцию',
        'RESPONSIBLE_ID' => 5,
        'DEADLINE'       => date('c', strtotime('+3 days')),
        'DESCRIPTION'    => 'Описание задачи',
    ],
], $webhookUrl);

// Завершить задачу
b24Call('tasks.task.complete', ['taskId' => $task['result']['task']['id']], $webhookUrl);

Отправка уведомлений

// Уведомление пользователю
b24Call('im.notify.personal.add', [
    'USER_ID' => 5,
    'MESSAGE' => 'Заказ #123 оплачен. Проверьте CRM.',
], $webhookUrl);

// Сообщение в чат
b24Call('im.message.add', [
    'DIALOG_ID' => 'chat123',
    'MESSAGE'   => 'Автоматическое уведомление: новый лид',
], $webhookUrl);

Пагинация (обход всех записей)

function b24GetAll(string $method, array $params, string $webhookUrl): array
{
    $all   = [];
    $start = 0;

    do {
        $params['start'] = $start;
        $response = b24Call($method, $params, $webhookUrl);
        $items    = $response['result'] ?? [];
        $all      = array_merge($all, $items);
        $total    = $response['total'] ?? 0;
        $start   += 50;
    } while ($start < $total);

    return $all;
}

// Получить всех контактов
$contacts = b24GetAll('crm.contact.list', [
    'select' => ['ID', 'NAME', 'PHONE', 'EMAIL'],
], $webhookUrl);

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

$response = b24Call('crm.deal.get', ['id' => 99999], $webhookUrl);

if (isset($response['error'])) {
    $errorCode = $response['error'];         // 'NOT_FOUND'
    $errorDesc = $response['error_description']; // 'Item not found'
    throw new \RuntimeException("Bitrix24 API error: {$errorCode} — {$errorDesc}");
}

Итог

Входящий вебхук — самый быстрый способ начать работать с Bitrix24 API. Для продакшн-интеграций с несколькими порталами используйте OAuth-приложения. Всегда реализуйте пагинацию при получении списков — по умолчанию API возвращает не более 50 записей.