Документация1С-Битрикс: Модулиnative.apiРазработчикамПримеры работыЗапросы

PHP

Замените https://example.ru/api/ адресом своего API. Нужные наборы роутов должны быть включены.

Отправка запроса

Примеры для серверного PHP с расширением cURL. Функция возвращает тело ответа, включая ответы с HTTP-ошибкой

<?php

const API_URL = 'https://example.ru/api/';

function apiRequest(
    string $path,
    string $method = 'GET',
    ?string $authorization = null,
    ?array $body = null,
): string {
    $headers = [];
    $options = [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_USERAGENT => 'MyIntegration/1.0',
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
    ];

    if ($authorization !== null) {
        $headers[] = 'Authorization: ' . $authorization;
    }

    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        $options[CURLOPT_POSTFIELDS] = json_encode($body, JSON_THROW_ON_ERROR);
    }

    $options[CURLOPT_HTTPHEADER] = $headers;
    $curl = curl_init(rtrim(API_URL, '/') . '/' . ltrim($path, '/'));

    if ($curl === false) {
        throw new RuntimeException('Не удалось создать HTTP-запрос');
    }

    curl_setopt_array($curl, $options);
    $response = curl_exec($curl);
    $error = curl_error($curl);
    curl_close($curl);

    if ($response === false) {
        throw new RuntimeException($error);
    }

    return $response;
}

Сервисные роуты

Параметры адреса

// Проверить работу API
echo apiRequest('up');

// Передать id в адресе и name в строке запроса
echo apiRequest('up/user/15?name=Ivan');

Передача JSON

// Передать параметры в теле запроса
echo apiRequest('up', method: 'POST', body: [
    'name' => 'Иван',
    'quantity' => 2,
]);

XML-ответ

// Отправить JSON и получить XML-ответ встроенного PUT-роута
echo apiRequest('up', method: 'PUT', body: ['name' => 'Иван']);

// Выбрать XML для GET-запроса
echo apiRequest('up?format=xml');

Доступ по группам

// HTTP 403: в штатной карте задан whitelist без авторизации API
echo apiRequest('up/group/1');

Вызываемый класс

// Проверить вызываемый класс; данные не удаляются
echo apiRequest('up', method: 'DELETE');

Токены

При AUTH_MFA_REQUIRED для выпуска и списка токенов через Basic нужны cookie сессии того же пользователя после входа с MFA. Эти примеры cookie не передают. Для серверной интеграции можно выпустить токен в админке и использовать Bearer.

Подставьте логин, пароль, <ACCESS_TOKEN>, <REFRESH_TOKEN> и <CLIENT_ID>. В функции задан постоянный User-Agent: MyIntegration/1.0 для выпуска, обновления и использования токенов. Используйте пару, выпущенную этим клиентом, либо пару, созданную вручную: привязанный токен другого клиента вернёт HTTP 401.

$login = 'login';
$password = '<PASSWORD>';
$accessToken = '<ACCESS_TOKEN>';
$refreshToken = '<REFRESH_TOKEN>';
$clientId = '<CLIENT_ID>';
$basicAuthorization = 'Basic ' . base64_encode($login . ':' . $password);

Выпуск

// Создать пару токенов для постоянного серверного клиента
echo apiRequest('token', method: 'POST', authorization: $basicAuthorization);

Обновление

// Заменить пару по refresh-токену
echo apiRequest('token', method: 'PUT', authorization: 'Bearer ' . $refreshToken);

Список

// Получить активные токен-сессии пользователя
echo apiRequest('token', authorization: $basicAuthorization);

Отзыв

// client.id берётся из списка сессий
echo apiRequest(
    'token?client_id=' . rawurlencode($clientId),
    method: 'DELETE',
    authorization: 'Bearer ' . $accessToken,
);

После выпуска или обновления сохраните оба токена из ответа: access и refresh. Поля ответа и правила работы с токенами.

Провайдер

Описание метода

// Узнать параметры разрешённого метода
$query = http_build_query([
    'class' => 'Bitrix\\Main\\Localization\\Loc',
    'method' => 'getCurrentLang',
], '', '&', PHP_QUERY_RFC3986);

echo apiRequest('provider?' . $query, authorization: 'Bearer ' . $accessToken);

Выполнение метода

// Получить текущий язык Битрикса
echo apiRequest('provider', method: 'POST', authorization: 'Bearer ' . $accessToken, body: [
    'class' => 'Bitrix\\Main\\Localization\\Loc',
    'method' => 'getCurrentLang',
]);