REST-модуль: создание своих методов

Модуль rest — это не только REST для Битрикс24: он позволяет опубликовать собственные методы API, доступные приложениям и внешним системам по единому протоколу. Свои методы регистрируются через событие OnRestServiceBuildDescription, получают авторизацию, права и стандартный формат ошибок «из коробки».

Когда нужен свой REST-метод

Штатное API Битрикс24 закрывает CRM, задачи и каталог, но собственная бизнес-логика в него не входит. Свои REST-методы нужны, когда:

• мобильное приложение или SPA обращается к бэкенду за нестандартными данными;
• внешняя система дергает вашу логику (расчёт цены, проверка остатка, оформление B2B-заявки);
• нужно отдать наружу агрегированные данные без прямого доступа к БД.

Регистрация методов через событие

REST-методы объявляются в обработчике события OnRestServiceBuildDescription модуля rest. Обработчик возвращает дерево «сервис → метод → колбэк».

use Bitrix\Main\EventManager;
EventManager::getInstance()->addEventHandler(
  'rest',
  'OnRestServiceBuildDescription',
  ['MyRestHandler', 'onBuild']
);

class MyRestHandler {
  public static function onBuild() {
    return [
      'myservice' => [
        'myservice.stock.get' => [__CLASS__, 'getStock'],
      ],
    ];
  }
}

Ключ первого уровня (myservice) — имя сервиса (scope). Ключ второго уровня — полное имя метода, которое клиент вызовет как myservice.stock.get. Значение — callback, которому передаются параметры запроса.

Реализация метода-обработчика

Колбэк получает три аргумента: массив параметров запроса, номер навигации и объект \CRestServer. Возвращённое значение сериализуется в JSON/XML автоматически.

public static function getStock($params, $n, \CRestServer $server) {
  $id = (int)($params['PRODUCT_ID'] ?? 0);
  if ($id <= 0) {
    throw new \Bitrix\Rest\RestException(
      'PRODUCT_ID is required',
      'ERROR_ARGUMENT'
    );
  }
  \Bitrix\Main\Loader::includeModule('catalog');
  $row = \Bitrix\Catalog\Model\Product::getById($id)->fetch();
  return ['PRODUCT_ID' => $id, 'QUANTITY' => $row['QUANTITY'] ?? 0];
}

Через объект \CRestServer доступны метаданные вызова: авторизованный пользователь, scope, версия. Не возвращайте объекты Result — приводите к скалярам и массивам, которые корректно сериализуются.

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

Правильный способ вернуть ошибку клиенту — бросить \Bitrix\Rest\RestException. Модуль сам сформирует стандартный ответ с полями error и error_description.

Авторизация и права

Модуль rest поддерживает два основных сценария авторизации:

• Вебхуки — входящий вебхук с токеном в URL, привязанный к конкретному пользователю и набору прав (scope). Быстрый способ для внутренних интеграций;
• OAuth 2.0 — для приложений Marketplace и внешних сервисов с полноценным потоком авторизации и refresh-токенами.

Ваш метод исполняется от имени авторизованного пользователя, поэтому проверки прав внутри колбэка так же валидны, как в обычном коде: global $USER; $USER->GetID(). Ограничить метод определённым scope можно, разместив его под соответствующим сервисом в описании.

Вызов метода клиентом

Метод вызывается по общему REST-эндпоинту. Для вебхука URL выглядит так:

POST https://site.ru/rest/1/xxxxTOKENxxxx/myservice.stock.get.json
Content-Type: application/json

{ "PRODUCT_ID": 1024 }

Формат ответа задаётся расширением (.json или .xml). Успешный ответ приходит в поле result, ошибка — в error. Пагинация больших выборок — через возврат управляющих полей и параметр start, аналогично штатным методам.

Практические рекомендации

• Именуйте методы иерархически: сервис.сущность.действие — так их проще документировать и версионировать;
• Валидируйте все входные параметры: REST открыт наружу, доверять данным нельзя;
• Тяжёлые операции выносите в очередь/агент, а методом отдавайте статус — REST не место для долгих задач;
• Логируйте вызовы для аудита и отладки интеграций;
• Держите обработчик события в init.php или в своём модуле, чтобы регистрация не терялась при обновлениях.

Итог

Свои REST-методы в Битрикс строятся на событии OnRestServiceBuildDescription: вы описываете дерево «сервис → метод → колбэк», реализуете логику в статических методах, а модуль rest берёт на себя авторизацию (вебхуки или OAuth), права, сериализацию и формат ошибок через RestException. Это надёжнее самописных JSON-эндпоинтов и совместимо с экосистемой Битрикс24.

Когда REST становится точкой интеграции с мобильным приложением, B2B-порталом или партнёрскими системами, важны продуманный контракт, безопасность и документация. Мы в B2Bsite проектируем такие API под нагрузку, с версионированием, аутентификацией и логированием.