Сайт на «1С-Битрикс: Управление сайтом» почти никогда не живёт в одиночестве. Рядом всегда оказывается CRM, складская программа, служба доставки, платёжный сервис, мобильное приложение или банальная выгрузка остатков из Excel, которую кто-то делает руками каждое утро. Пока этих связок одна-две, их закрывают костылями: cron-скрипт, файл на FTP, обмен по расписанию. Когда их становится пять, костыли начинают ломаться по очереди, и бизнес приходит к вопросу: как связать сайт с внешними системами нормально, через API.
Разберём, что реально умеет REST API в «1С-Битрикс», чем он отличается от одноимённого механизма в Битрикс24 (и почему половина найденных в интернете инструкций вам не подойдёт), как его включить и что мы обычно закладываем в проект интеграции сайта через API, чтобы он не рассыпался через полгода.
REST API в 1С-Битрикс: не то же самое, что REST API в Битрикс24
Первая ловушка, в которую попадают почти все: путаница между двумя продуктами. «1С-Битрикс: Управление сайтом» (разработчики сокращают её до БУС) и «Битрикс24» сделаны одной компанией и используют общее ядро, но REST-механика у них разная по степени готовности.
REST в Битрикс24 работает как витрина: сотни готовых методов вида crm.deal.add, tasks.task.list, интерфейс создания вебхуков прямо в портале, каталог приложений. Пришёл, нажал «Создать входящий вебхук», получил ссылку, дёрнул её из внешнего сервиса, и всё работает.
В «Управлении сайтом» модуль REST API скорее каркас. Он доступен в продукте начиная с версии 16.6.0, устанавливается и настраивается через Настройки → Настройки продукта → Настройки модулей → REST API, но готового набора прикладных методов «под ключ» и удобного интерфейса управления ключами доступа там нет. Страницу управления вебхуками разработчик обычно собирает сам, в каталоге /local/rest/ на базе штатного компонента bitrix:rest.hook. Сам обработчик запросов при этом штатный: после установки модуля появляется адрес /rest/, за которым стоит компонент bitrix:rest.server.
Практический вывод для владельца сайта простой: rest api 1с битрикс не «включить галочку», а небольшой проект разработки. Час-два уходит на подготовку инфраструктуры, остальное время занимает описание тех методов, которые нужны именно вашему бизнесу. Зато на выходе вы получаете интерфейс, спроектированный под ваши процессы, а не универсальный набор из коробки, к которому потом всё равно приходится приделывать переходники.
Когда сайту действительно нужен API, а когда хватит штатных механизмов
Не каждая задача обмена данными требует REST. Прежде чем закладывать бюджет на разработку, стоит честно проверить, не решается ли задача штатно.
Обмен товарами и заказами с 1С. Для этого в «1С-Битрикс» есть отдельный, годами отлаженный механизм обмена в формате CommerceML. Он умеет передавать номенклатуру, свойства, цены, остатки и заказы. Если задача звучит как «синхронизировать каталог и заказы с 1С», начинать надо с него, а не с самописного API. REST здесь подключают точечно, когда нужны сценарии, которых штатный обмен не покрывает: например, отдать актуальный остаток по конкретному товару в реальном времени, а не раз в час.
Приём заявок с сайта во внешнюю CRM. Здесь чаще нужен не входящий, а исходящий вызов: сайт сам отправляет данные формы в CRM. Это делается обработчиком события на стороне сайта, и полноценный REST-сервер для этого разворачивать не нужно.
А вот когда REST действительно оправдан:
- внешняя система должна забирать данные с сайта по своему расписанию: остатки, цены, статусы заказов, контент;
- у компании есть мобильное приложение или отдельный фронтенд, которому сайт служит источником данных;
- нужен личный кабинет партнёра или дилера, работающий поверх тех же данных, что и сайт;
- интеграций несколько, и вы не хотите для каждой писать отдельный скрипт со своей логикой авторизации;
- подрядчик со стороны клиента должен получить доступ к части данных, но ни в коем случае не к админке.
Последний пункт недооценивают, а он часто и есть главный аргумент. Интеграция сайта через api заодно даёт способ выдать внешнему разработчику ровно тот кусок данных, который ему нужен, с фиксированным набором прав, без учётной записи администратора и без доступа к файловой системе.
Как включить REST API на сайте: последовательность шагов
Порядок работ на боевом проекте выглядит так.
1. Проверить и установить модуль. В административной части откройте Настройки → Настройки продукта → Модули и убедитесь, что модуль REST API (rest) установлен. Если нет, установите. Затем зайдите в настройки модуля: Настройки → Настройки продукта → Настройки модулей → REST API.
2. Проверить адрес обработчика. После установки модуля запросы обслуживаются по адресу /rest/. Если этот путь по каким-то причинам занят или неудобен, компонент bitrix:rest.server можно разместить в другом каталоге: механика от этого не меняется.
3. Настроить правила ЧПУ. На большинстве проектов требуется добавить правила в urlrewrite.php: одно для адреса API-вызовов /rest/ с указанием на штатный обработчик /bitrix/services/rest/index.php, второе для вашей служебной страницы управления вебхуками. После правки PHP-файлов и urlrewrite.php обязательно сбросьте кэш сайта, иначе изменения просто не подхватятся, и вы полдня будете искать несуществующую ошибку.
4. Собрать страницу управления доступами. Это и есть та часть, которой в «Управлении сайтом» нет из коробки. Обычно создаётся страница в /local/rest/ с компонентом bitrix:rest.hook: на ней администратор может выпустить вебхук, выбрать для него области доступа (scope) и увидеть готовый URL для внешней системы.
5. Описать методы. Ради этого всё и затевалось, подробности в следующем разделе.
Отдельно про инфраструктуру: работать по HTTP такое решение не должно в принципе. Ключ доступа передаётся в запросе, и без шифрования канала он рано или поздно окажется в чужих руках. Валидный SSL-сертификат и принудительный редирект на HTTPS: обязательное условие, а не рекомендация.
Авторизация: четыре механизма и как выбрать нужный
Модуль поддерживает несколько способов проверить, что запрос пришёл от того, кому вы разрешили доступ.
Вебхуки (apauth): самый практичный вариант для интеграций «сервер с сервером». Вы выпускаете ключ, привязываете к нему набор прав и отдаёте внешней системе. Ключ передаётся прямо в запросе, поэтому HTTPS здесь критичен. Это стандартный выбор для 80% задач: обмен со складом, выгрузка в аналитику, приём данных от партнёрского сервиса.
OAuth: открытый протокол авторизации. Нужен, когда речь идёт о приложении, работающем от имени конкретного пользователя, или о тиражном решении, которое будут ставить разные клиенты. Для одной внутренней интеграции это избыточно.
Авторизация по сессии (sessionauth): применяется, когда запросы идут из браузера уже авторизованного на сайте пользователя. Типичный сценарий: динамический личный кабинет, где фронтенд обращается к API того же сайта.
Собственная проверка через событие OnRestCheckAuth: запасной вариант, когда у компании есть свой контур авторизации (например, единый корпоративный SSO) и его нужно применить и к API.
На практике мы почти всегда начинаем с вебхуков, а к OAuth переходим только тогда, когда интеграция выходит за пределы одной компании. Важнее самого выбора протокола другое правило: под каждую внешнюю систему выпускается свой ключ с минимально необходимым набором прав. Если «главный ключ на всё» знают три подрядчика, это гарантированный инцидент в будущем и невозможность понять, кто именно уронил данные.
Свои методы: scope и событие OnRestServiceBuildDescription
Механика расширения в «1С-Битрикс» устроена аккуратно. Разработчик описывает класс-обработчик, наследуемый от IRestService, и подписывается на событие OnRestServiceBuildDescription модуля rest. В обработчике возвращается массив, где объявляется своя область доступа (scope) и перечень методов внутри неё, с указанием функции, которая будет вызвана.
Практически это значит, что вы сами решаете, как выглядит ваш API. Не «отдать всё содержимое инфоблока», а, например, метод «получить остаток и цену по артикулу», который внутри уже сходит в нужный инфоблок, применит правила ценообразования для конкретного контрагента и вернёт три поля вместо трёхсот.
Такой подход даёт три вещи, ради которых стоит потратить время на проектирование:
- Права работают на уровне бизнес-смысла. Scope «остатки» можно выдать складской системе, не открывая доступ к клиентским данным.
- Внутреннюю структуру можно менять. Если завтра склад переедет в другой инфоблок или в highload-блок, внешние системы этого не заметят: контракт метода остался прежним.
- Нагрузка предсказуема. Метод, возвращающий три поля по артикулу, работает на порядки быстрее, чем выгрузка всего каталога, которую внешний сервис потом фильтрует у себя.
Отдельно стоит заранее договориться о версионировании. Самый дешёвый способ: заложить номер версии прямо в имя scope или метода. Через год, когда партнёр попросит добавить поле, вы сможете выпустить новую версию метода, не сломав интеграцию, которая уже работает у пяти других контрагентов.
Как это выглядит на реальном проекте
Приведём собирательный пример: сценарий, типичный для оптовой компании в Казахстане. Он иллюстративный, но собран из задач, которые встречаются почти в каждом подобном проекте.
Компания продаёт оборудование: сайт-каталог на «1С-Битрикс», учёт в 1С, отдел продаж работает в CRM, у дилеров есть личный кабинет на сайте. До интеграции картина была такая: остатки на сайте обновлялись выгрузкой раз в сутки, дилеры звонили менеджерам уточнять наличие, менеджеры смотрели в 1С и перезванивали. Каждый такой цикл занимал 15-20 минут рабочего времени, и это при десятках обращений в день.
Что было сделано. Штатный обмен с 1С по CommerceML оставили как есть: он хорошо справляется с номенклатурой и заказами. Поверх него подняли REST-слой с двумя scope: stock (остатки и персональные цены по артикулу) и orders (создание заказа и получение его статуса). Складская система получила вебхук с правами только на stock. Личный кабинет дилера начал запрашивать наличие в момент открытия карточки товара, а не показывать вчерашние данные. CRM получила отдельный ключ, чтобы подтягивать статус заказа в карточку сделки.
Результат, который увидел бизнес: звонки «а есть ли на складе» практически исчезли, потому что дилер видит актуальное число сам. Заказы из кабинета попадают в учёт без ручного переноса. Менеджеры перестали быть справочным бюро и вернулись к продажам. При этом ни одна из внешних систем не получила доступа к админке сайта, только к своему набору методов.
Сроки в подобных проектах обычно упираются не в код, а в согласование: что именно считать «остатком», как учитывать резервы, чья цена главная при расхождении. Техническая часть (настройка модуля, вебхуки, описание методов) занимает меньше времени, чем эти договорённости. Поэтому мы всегда начинаем с описания контракта: какие методы, какие поля, кто владелец данных, что происходит при конфликте. Если вам нужна такая интеграция вместе с доработкой самого сайта, это как раз то, чем занимается наша команда, и можно заказать разработку сайта и интеграций под ключ одним проектом, без разделения ответственности между двумя подрядчиками.
Ошибки, которые чаще всего ломают интеграцию
Инструкция не от того продукта. Самая частая. Разработчик находит статью про вебхуки Битрикс24, идёт искать в админке сайта раздел «Разработчикам» и не находит. Дальше делается вывод «в Битриксе нет REST», и проект уходит в самописные скрипты. Проверяйте, о каком продукте текст: у БУС свой путь настройки.
Забытый сброс кэша. Правки в urlrewrite.php и в PHP-файлах без сброса кэша дают эффект «всё сделал по инструкции, ничего не работает». Первое, что стоит проверить при непонятном поведении.
Один ключ на всех. Выпустили вебхук с полными правами, разослали трём подрядчикам, через год не можете ни отозвать его без остановки половины бизнеса, ни понять, чей скрипт создаёт дубли заказов.
Метод, возвращающий «всё». Соблазн сделать один универсальный метод, отдающий весь список, велик. На тестовой базе из 200 позиций он летает. На боевой из 40 000 он кладёт сервер каждый раз, когда внешняя система решает синхронизироваться. Постраничная выдача и фильтры закладываются сразу, а не после первого падения.
Отсутствие логирования. Когда через полгода партнёр говорит «мы отправили, у вас не пришло», без журнала запросов доказать что-либо невозможно. Минимальный лог входящих вызовов (какой ключ, какой метод, когда, с каким результатом) экономит недели разбирательств.
Нет плана на отказ. Внешний сервис недоступен, у него сменился адрес, истёк сертификат. Если сайт в этот момент показывает пользователю ошибку вместо кэшированных данных, страдает не подрядчик, а ваша конверсия. Поведение при недоступности смежной системы нужно продумать до запуска.
Эксплуатация: что делать после запуска
Интеграция не разовая работа, а живой механизм, у которого есть срок службы. Минимальный регламент сопровождения выглядит так.
Раз в квартал пересматривайте выданные ключи: кто их использует, нужны ли ещё, не осталось ли доступов у подрядчика, с которым вы расстались год назад. Следите за сроком SSL-сертификата: его истечение обрывает все внешние вызовы разом, и выглядит это как «сайт вроде работает, а заказы не приходят». Держите под контролем обновления продукта: любое крупное обновление ядра служит поводом прогнать интеграции по чек-листу, а лучше делать это сначала на тестовой копии сайта.
Отдельная строка регламента: документация. Не в смысле толстого тома, а в смысле одной таблицы, где перечислены все выданные ключи, кому они принадлежат, какие методы доступны и кто со стороны контрагента отвечает за интеграцию. Такой файл занимает полчаса на составление и спасает при любой смене подрядчика или увольнении разработчика: без него через год никто в компании не сможет сказать, что именно ходит к вашему сайту и зачем. Туда же имеет смысл вписать порядок эскалации: к кому обращаться, если обмен встал в пятницу вечером, и кто имеет право отозвать ключ.
Не пренебрегайте тестовой копией сайта. Если проверять новые методы на боевой базе, можно однажды создать сотню дублей заказов у реальных клиентов. Отдельный контур с копией данных нужен и для приёмки: пока подрядчик со стороны партнёра отлаживает свою часть, он должен ходить именно туда, а не в ваш продакшн.
И заведите мониторинг на стороне бизнеса, а не только на стороне сервера. Проверка вида «за последние два часа не создано ни одного заказа через API, хотя обычно их 10-15» ловит проблему быстрее, чем любые технические метрики, потому что реагирует на результат, а не на симптом.
Стоит ли начинать этот путь, если у вас пока одна интеграция и она работает? Скорее нет. REST-слой окупается там, где систем несколько, данные нужны в реальном времени и цена ручного переноса измеряется человеко-часами каждый день. Но если вы уже узнали в описании выше свою компанию, каждый месяц отсрочки стоит вам ровно столько, сколько сотрудники тратят на копирование цифр из одного окна в другое.
Частые вопросы
Нужна ли отдельная лицензия, чтобы пользоваться REST API в 1С-Битрикс?
Модуль REST API входит в состав продукта и работает с «1С-Битрикс: Управление сайтом» начиная с версии 16.6.0. Отдельно докупать его не требуется. Что действительно стоит проверить перед стартом, так это актуальность вашей лицензии на обновления: без обновлений вы останетесь на старой версии ядра со всеми её ограничениями.
Чем REST API отличается от штатного обмена с 1С?
Обмен по CommerceML представляет собой готовый механизм под конкретную задачу: номенклатура, цены, остатки, заказы, по расписанию. REST: универсальный интерфейс, который вы описываете сами под любые сценарии, включая запросы в реальном времени. Они не конкурируют: чаще всего штатный обмен остаётся основой, а REST закрывает то, чего в нём нет.
Можно ли настроить всё самостоятельно, без разработчика?
Установить модуль и открыть его настройки может администратор сайта. Но описание собственных методов, правила ЧПУ и страница управления вебхуками требуют работы с кодом и правки серверных файлов. Если в компании нет разработчика, знакомого с «1С-Битрикс», лучше не экспериментировать на боевом сайте.
Насколько это безопасно: открывать доступ к данным сайта извне?
Безопасность здесь определяется дисциплиной, а не самой технологией. Обязательный HTTPS, отдельный ключ на каждую внешнюю систему, минимальный набор прав в scope, журнал вызовов и регулярный пересмотр выданных доступов закрывают основные риски. Опасен не API, а ключ с полными правами, который лежит в переписке в мессенджере.
Сколько времени занимает такой проект?
Техническая часть (подготовка инфраструктуры и первые методы) обычно занимает несколько рабочих дней. Основное время уходит на согласование логики: какие данные считаются главными, что делать при расхождениях, как обрабатывать ошибки. Чем точнее описан контракт до начала работ, тем короче и дешевле получается проект.