REST API в 1С-Битрикс: интеграции, вебхуки и приложения

Рано или поздно любой серьёзный проект на Битриксе перестаёт быть «вещью в себе»: магазин должен отдавать заказы в учётную систему, забирать остатки со склада, синхронизировать каталог, кормить данными мобильное приложение и чат-бота, а CRM — обмениваться сделками с сайтом. Всё это держится на одном инструменте — REST API. Разберём его без мифов: что такое «битрикс rest» на самом деле, чем вебхуки битрикс24 отличаются от приложений, как устроены входящие и исходящие вебхуки и как собрать собственный REST на стороне 1С-Битрикс.

Материал — практическая выжимка из наших проектов по разработке REST API для 1С-Битрикс и интеграциям с внешними системами. Без академизма: только то, что реально нужно, чтобы спроектировать надёжный обмен и не наступить на типовые грабли.

Что такое REST API в экосистеме Битрикс

REST API (Representational State Transfer) — это способ обмена данными между системами по протоколу HTTP: одна сторона отправляет запрос на определённый адрес с параметрами, другая возвращает структурированный ответ, чаще всего в формате JSON. «Битрикс rest» — это набор таких адресов-методов, через которые внешние программы читают и меняют данные внутри платформы: сделки, заказы, товары, пользователей.

Ключевая мысль, с которой стоит начать: REST в мире Битрикса — это не одна монолитная штука, а два разных инструмента под одним брендом. Есть облачный и коробочный Битрикс24 с его богатым готовым REST, и есть 1С-Битрикс: Управление сайтом — продукт для сайтов и интернет-магазинов, у которого модель REST устроена иначе. Путаница между ними — источник половины недоразумений в задачах на интеграцию, поэтому этому различию посвящён отдельный раздел ниже.

Зачем магазину REST, если есть обмен с 1С

Классический обмен с «1С:Предприятие» через CommerceML закрывает базовый сценарий «каталог и заказы», и о нём у нас есть отдельный разбор — интеграция магазина с 1С. Но как только появляются задачи вне этого протокола — передать заказ в стороннюю CRM, забрать остатки из WMS-склада в реальном времени, отдать данные в мобильное приложение или принять заказ от маркетплейса — нужен универсальный канал. Этим каналом и становится REST: он не привязан к одному формату файла и работает в обе стороны в реальном времени.

Битрикс24 и 1С-Битрикс: где какой REST

Это самый важный раздел для понимания всего дальнейшего. Один вендор — два продукта — две модели REST.

Битрикс24 (облако и коробка) — это платформа для совместной работы и CRM. У неё «из коробки» есть огромный REST API: сотни методов для CRM, задач, чата, календаря, телефонии, дисков. Именно здесь живут привычные crm.deal.add, crm.lead.list, входящие и исходящие вебхуки, OAuth-приложения и Маркет приложений. Когда в задаче звучит «вебхуки битрикс24», «поставить в CRM сделку через API», «чат-бот в портале» — это про Битрикс24.

1С-Битрикс: Управление сайтом (БУС) — это CMS и движок интернет-магазина. Здесь нет облачного REST такого масштаба: единого готового набора «дёргай любой метод» из коробки не поставляется. Вместо этого REST на сайте обычно строят одним из способов: собственные контроллеры на D7 (\Bitrix\Main\Engine\Controller), ajax-действия, или — если задача близка к порталу — модуль rest. То есть в БУС REST чаще делаешь ты сам под конкретный сценарий, а не берёшь готовым.

Вебхуки: входящие и исходящие

Вебхук (webhook) — самый быстрый способ подключиться к REST Битрикс24 без написания полноценного приложения. Это «крючок»: специальный URL с секретным кодом, привязанный к правам конкретного пользователя. Вебхуки бывают двух видов, и путать их нельзя, потому что они решают противоположные задачи.

Входящий вебхук (incoming)

Входящий вебхук — это URL, дёрнув который снаружи, вы вызываете методы Битрикса. Данные идут внутрь: вы создаёте сделку, читаете список товаров, обновляете заказ. По сути это готовый «пульт управления» порталом для вашего скрипта. Адрес выглядит так (код условный):

https://your-portal.bitrix24.ru/rest/1/xxxxxxxxxxxx/crm.deal.add.json

Здесь 1 — идентификатор пользователя, от имени которого работает вебхук, xxxxxxxxxxx — секретный код, а crm.deal.add — вызываемый метод. Отправляете POST с параметрами — получаете JSON-ответ. Именно входящие вебхуки закрывают большинство серверных интеграций «наш скрипт дёргает портал».

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

Исходящий вебхук работает наоборот: это подписка на событие. Вы указываете список событий (например, «создана сделка», «изменён заказ») и URL-обработчик на вашей стороне. Когда событие происходит внутри Битрикса, платформа сама отправляет HTTP-запрос на ваш URL с данными о том, что случилось. Данные идут наружу, инициатор — Битрикс, а не вы.

Простой мнемонический ориентир: входящий — вы дёргаете Битрикс, исходящий — Битрикс дёргает вас. Из этого сразу следует и разница в надёжности: во входящем ретраями управляете вы, а в исходящем нужно принять и корректно ответить на запрос платформы, иначе доставка события может не состояться.

Авторизация: вебхук-код и OAuth 2.0

Любой доступ к REST должен быть авторизован — иначе кто угодно читал бы и менял ваши данные. В экосистеме Битрикс есть два основных механизма, и выбор между ними определяет весь характер интеграции.

Авторизация по вебхук-коду

Самый простой способ: секретный код прямо в URL вебхука. Кто знает адрес — тот и имеет доступ в пределах прав того пользователя и того набора разрешений (scope), что заданы при создании вебхука. Плюсы — минимум кода, мгновенный старт, идеально для внутренней серверной интеграции. Минусы — код фактически «вечный» пароль: его нельзя показывать в браузере, коммитить в репозиторий или передавать в клиентское приложение. Утёк код — считайте, отдали ключи от портала.

Авторизация через OAuth 2.0

OAuth 2.0 — механизм для приложений. Здесь нет «вечного пароля»: пользователь один раз разрешает приложению доступ, после чего приложение получает пару токенов — короткоживущий access_token (им подписываются вызовы) и refresh_token (им обновляется access, когда тот истёк). Доступ ограничен явным набором прав (scope), токены можно отзывать, а одно приложение может обслуживать много порталов. Это правильный путь для тиражируемых, публичных и клиентских интеграций.

Приложения и локальные приложения

Если вебхук — это «ключ для своего скрипта», то приложение — это полноценный «жилец» портала, который работает по OAuth и может иметь интерфейс. Приложения бывают трёх типовых видов.

• Локальное приложение (local app). Создаётся прямо в портале и работает только с ним. Отличный компромисс между вебхуком и публичным приложением: у него уже есть OAuth-авторизация, scope и возможность встроить свой интерфейс во вкладку, но не нужно проходить модерацию Маркета. Идеально для внутренних решений компании.
• Тиражируемое приложение для Маркета. Публикуется в Маркете приложений Битрикс24 и может устанавливаться на любой портал. Требует полноценного OAuth-сервера на вашей стороне, обработки установки/удаления и продумывания массового сценария.
• Серверное приложение (без интерфейса). Работает как фоновый интегратор: получает токены, ходит в REST, шлёт данные во внешние системы, но не показывает пользователю страниц.

Поток OAuth для приложения на верхнем уровне выглядит так: приложение отправляет пользователя на страницу авторизации портала, пользователь подтверждает доступ, портал возвращает код, приложение меняет код на пару токенов, а дальше вызывает REST с access_token и по мере необходимости обновляет его через refresh_token.

Вебхук или приложение: сравнение

На старте почти каждой интеграции стоит развилка: обойтись вебхуком или писать приложение. Правильный выбор экономит недели работы, а ошибочный — приводит к переделке. Ориентируйтесь на таблицу.

Практическое правило: если это разовый серверный обмен между вашими же системами — берите вебхук и не усложняйте. Если вы делаете продукт, который поставите нескольким клиентам, или нужен интерфейс в портале — сразу закладывайте приложение на OAuth. Промежуточный вариант «внутреннее решение с интерфейсом, но без Маркета» отлично закрывается локальным приложением.

Основные группы методов REST

Методы REST в Битрикс24 сгруппированы по модулям, и имя метода почти всегда читается как «модуль.сущность.действие». Знание основных групп помогает быстро находить нужное и оценивать объём интеграции. Для интернет-магазина особенно важны группы каталога и заказов.

Отдельно отметим группы catalog.* и sale.* — это «магазинная» часть REST. Через них забирают и обновляют товары, читают и меняют заказы, работают с ценами и складами. Если задача звучит как «синхронизировать каталог» или «отдать заказы» — заглядывать нужно именно сюда. У каждого метода есть парные «сёстры»: *.add (создать), *.update (изменить), *.get (прочитать одну сущность), *.list (список с фильтром и пагинацией), *.delete (удалить).

Формат запроса и ответа

Запрос к REST — это HTTP-обращение к URL метода с параметрами. Параметры можно передавать в строке запроса (GET) или в теле (POST) — для операций записи всегда используют POST. Ответ приходит в JSON и, помимо самих данных в поле result, содержит служебную информацию о времени выполнения и, при постраничном чтении, указатель следующей страницы.

Пример вызова через входящий вебхук — создание сделки в CRM (значения условные):

POST /rest/1/xxxxxxxx/crm.deal.add.json

fields[TITLE]=Заказ с сайта №10245
fields[TYPE_ID]=SALE
fields[STAGE_ID]=NEW
fields[CURRENCY_ID]=RUB
fields[OPPORTUNITY]=15990

Успешный ответ в упрощённом виде:

{
  "result": 234,
  "time": {
    "start": 1751360000.12,
    "finish": 1751360000.34,
    "duration": 0.22
  }
}

Здесь result — идентификатор созданной сделки, а блок time показывает длительность операции. При ошибке структура иная — вместо result приходит описание проблемы:

{
  "error": "INVALID_CREDENTIALS",
  "error_description": "Invalid request credentials"
}

Правило: всегда проверяйте наличие поля error в ответе, а не только HTTP-код. REST может вернуть код 200 и при этом сообщить об ошибке в теле — например, о нехватке прав или неверном параметре. Разбор ответа без проверки error — источник «тихих» багов, когда интеграция считает несозданную сущность созданной.

Пагинация: start и next

Методы списка (*.list) не отдают тысячи записей за один вызов — они возвращают их страницами, обычно по 50 элементов. Управляет постраничным чтением параметр start и поле ответа next.

Логика такая: первый запрос идёт со start=0. В ответе, помимо данных, приходит поле next со значением смещения для следующей страницы и поле total с общим числом записей. Пока в ответе есть next, вы повторяете запрос, подставляя его значение в start, пока страницы не закончатся.

GET /rest/1/xxxxxxxx/crm.deal.list.json?start=0
→ { "result": [ ... 50 сделок ... ], "next": 50, "total": 173 }

GET /rest/1/xxxxxxxx/crm.deal.list.json?start=50
→ { "result": [ ... 50 сделок ... ], "next": 100, "total": 173 }

GET /rest/1/xxxxxxxx/crm.deal.list.json?start=100
→ { "result": [ ... 50 сделок ... ], "next": 150, "total": 173 }

GET /rest/1/xxxxxxxx/crm.deal.list.json?start=150
→ { "result": [ ... 23 сделки ... ] }   // next отсутствует — конец

Батч-запросы: 50 команд в одном

Каждый сетевой запрос стоит времени: установка соединения, задержка сети, ожидание ответа. Когда команд много, эти издержки складываются в секунды. Решение — батч (метод batch): он упаковывает до 50 команд REST в один HTTP-запрос и возвращает результаты всех команд разом.

Батч не только экономит сетевые обходы, но и умеет связывать команды между собой: результат одной команды можно подставить в параметры следующей через ссылку вида $result[имя_команды]. Это позволяет, например, создать сделку и тут же привязать к ней товарные позиции в одном запросе, не дожидаясь ответа между шагами.

POST /rest/1/xxxxxxxx/batch.json

halt=0
cmd[new_deal]=crm.deal.add?fields[TITLE]=Заказ №10245&fields[OPPORTUNITY]=15990
cmd[set_rows]=crm.deal.productrows.set?id=$result[new_deal]&rows[0][PRODUCT_NAME]=Товар&rows[0][PRICE]=15990

Разберём ключевые параметры батча:

• cmd — массив команд, у каждой есть имя (в примере new_deal, set_rows) и вызов метода со своими параметрами.
• $result[имя] — ссылка на результат ранее выполненной команды. Так идентификатор новой сделки попадает в команду добавления позиций.
• halt — поведение при ошибке: halt=1 прерывает выполнение батча на первой ошибке, halt=0 продолжает остальные команды.

Ответ батча содержит результаты и ошибки по каждой команде отдельно, поэтому разбирать его нужно покомандно, а не как единый success/fail. Батч — главный инструмент масштабирования: если ваша интеграция шлёт сотни одиночных вызовов, почти всегда их можно свернуть в пачки по 50 и снизить и время, и давление на лимиты.

Ограничения частоты запросов

REST — общий ресурс, и чтобы одна интеграция не «положила» портал, действует ограничение частоты обращений. Если слать запросы слишком часто, часть из них начнёт отклоняться с ошибкой превышения лимита. Дополнительно у операций есть «стоимость»: тяжёлые методы расходуют больше «бюджета», чем лёгкие, и это учитывается механизмом контроля нагрузки.

Мы намеренно не называем конкретных «магических» чисел: точные пороги зависят от тарифа, версии и режима работы платформы и со временем меняются. Проектировать надёжную интеграцию нужно не под конкретную цифру, а под сам факт наличия лимитов:

• Группируйте вызовы в батчи. 50 команд в одном запросе — это и меньше обходов, и мягче нагрузка на лимит.
• Выдерживайте паузы. В массовых выгрузках вставляйте небольшие задержки между пачками, а не «долбите» подряд.
• Ловите ответ о превышении лимита. Обрабатывайте соответствующую ошибку и не считайте её фатальной — это сигнал «повтори позже».
• Повторяйте с нарастающей задержкой. При превышении лимита увеличивайте паузу перед повтором (экспоненциальный backoff), а не повторяйте мгновенно.
• Разносите тяжёлые задачи во времени. Массовую синхронизацию каталога планируйте на часы низкой нагрузки, а не в пик.

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

В распределённом обмене ошибки — норма, а не исключение: сеть моргнула, приёмник перезагрузился, сработал лимит, истёк токен. Разница между хрупкой и надёжной интеграцией — в том, как она реагирует на эти ситуации. Ошибки делятся на две категории, и обрабатывать их нужно по-разному.

Правильная стратегия ретраев — экспоненциальная задержка с ограничением попыток: первый повтор через секунду, второй через две-четыре, дальше больше, но не бесконечно. После исчерпания попыток запрос уходит в «мёртвую очередь» на ручной разбор, а не молча теряется. Обязателен и журнал обмена: что отправили, что получили, сколько было попыток — без него отладка боевой интеграции превращается в гадание.

1. Классифицируйте ответ. По коду и полю error определите, ошибка временная или постоянная.
2. Для временных — ретрай с backoff. Увеличивайте паузу между попытками, ограничьте их число (например, 5–7).
3. Для авторизационных — обновите токен. Получите новый access по refresh и повторите исходный вызов один раз.
4. Для постоянных — не повторяйте. Зафиксируйте в журнале и уведомьте ответственного: повтор ничего не изменит.
5. Ведите журнал. Сохраняйте запрос, ответ, число попыток и статус, чтобы обмен был прозрачным.

Идемпотентность обмена

Идемпотентность — свойство операции, при котором повторное выполнение даёт тот же результат, что и однократное. В контексте REST это значит: если вы дважды отправили «создать заказ №10245», в системе должен появиться один заказ, а не два. Без идемпотентности любые ретраи опасны — они плодят дубли.

Почему это критично именно в обмене? Потому что вы никогда не уверены, дошёл ли запрос. Приёмник мог создать сущность и не успеть ответить — соединение оборвалось. Ретрай отправит запрос снова, и если защиты нет, появится дубль. Классические симптомы отсутствия идемпотентности — «задвоенные заказы», «две одинаковые сделки», «товар добавился дважды».

Как обеспечивают идемпотентность на практике:

• Внешний ключ (external id). Передавайте свой стабильный идентификатор (номер заказа с сайта) и на приёмнике проверяйте: если сущность с таким ключом уже есть — обновите её, а не создавайте новую (upsert).
• Ключ идемпотентности запроса. Присваивайте каждому обмену уникальный идентификатор и запоминайте обработанные, чтобы повтор с тем же ключом не выполнялся дважды.
• Проверка перед созданием. Перед *.add делайте *.list/*.get по признаку уникальности — но помните, что это дороже и не защищает от гонок так надёжно, как внешний ключ.

Свой REST на 1С-Битрикс: контроллеры D7

Вернёмся к 1С-Битрикс: Управление сайтом. Когда магазину нужен собственный API — чтобы кормить мобильное приложение, принимать заказы от внешней системы или отдавать данные партнёру — его собирают на штатном механизме ядра D7: контроллерах \Bitrix\Main\Engine\Controller и ajax-действиях. Это «свой REST» без сторонних библиотек и без разворачивания OAuth-сервера.

Идея простая: вы описываете класс-контроллер с методами-действиями (actions), объявляете для них правила доступа, и получаете JSON-эндпоинт, который вызывается по стандартному ajax-роутингу Битрикса. Схематично контроллер выглядит так (код упрощён и приведён как иллюстрация структуры):

namespace Vendor\Shop\Controller;

use Bitrix\Main\Engine\Controller;
use Bitrix\Main\Engine\ActionFilter;

class Orders extends Controller
{
    // Правила доступа для действий: например, требуем авторизацию/подпись
    public function configureActions()
    {
        return [
            'list' => [
                'prefilters' => [ new ActionFilter\HttpMethod(['GET']) ],
            ],
        ];
    }

    // GET .../ajax.php?c=vendor:shop.orders&action=list
    public function listAction($since = null)
    {
        // выбрать новые заказы через D7 (\Bitrix\Sale\Order)
        // вернуть массив — ядро само отдаст его как JSON
        return [
            'orders' => [
                ['id' => 10245, 'sum' => 15990, 'status' => 'N'],
            ],
        ];
    }
}

Что здесь важно с точки зрения архитектуры REST на сайте:

• Действия возвращают данные, а не HTML. Метод *Action возвращает массив — ядро сериализует его в JSON и оборачивает в стандартную структуру ответа. Это и есть ваш REST-ответ.
• Доступ через префильтры. В configureActions вы задаёте фильтры: разрешённый HTTP-метод, проверку авторизации, ограничение по типам вызова. Сюда же вешают собственную проверку токена или подписи.
• Роутинг стандартный. Действия вызываются через ajax-контроллер ядра с указанием класса и действия — не нужно самому разбирать URL.
• D7 под капотом. Внутри действия вы работаете штатными API: \Bitrix\Sale\Order, \Bitrix\Catalog, ORM инфоблоков — то есть теми же средствами, что и остальной код проекта.

Для авторизации такого API не нужен полноценный OAuth: достаточно проверять токен в заголовке или подпись запроса в префильтре и работать строго по HTTPS. Это тот случай, когда «свой REST» решает задачу проще и прозрачнее, чем попытка натянуть на сайт модель Битрикс24. Такие вещи мы делаем в рамках highload-проектов на Битрикс, где нагрузка и объёмы требуют аккуратной архитектуры API.

Типовые сценарии интернет-магазина

Теория оживает на конкретных задачах. Разберём пять самых частых сценариев, ради которых магазину на Битриксе нужен REST, и подскажем, какой инструмент под каждый брать.

1. Передать заказ в стороннюю систему

Магазин оформил заказ — его нужно отдать в CRM, ERP или службу доставки. Два подхода: исходящий вебхук/событие «создан заказ», которое шлёт данные наружу, либо собственный REST-эндпоинт, который внешняя система опрашивает. На практике комбинируют: событие-триггер уведомляет «есть новый заказ», а защищённый метод отдаёт детали. Обязательны идемпотентность по номеру заказа и ретраи, чтобы заказ не задвоился и не потерялся.

2. Забрать остатки со склада

Актуальные остатки часто живут во внешней складской системе (WMS). Магазин периодически запрашивает их по REST и обновляет наличие товаров. Здесь важны пагинация (остатков могут быть десятки тысяч), батчи для массового обновления и разумная частота, чтобы не упереться в лимиты. Обновление наличия лучше делать дельтой (только изменившееся), а не полной перезаписью каждый раз.

3. Синхронизировать каталог

Если каталог ведётся во внешней PIM-системе, его нужно регулярно подтягивать: новые товары, изменения цен, характеристик, статусов. Через REST это делают инкрементально — забирают только то, что изменилось с прошлой синхронизации (по метке времени или версии). Массовые операции сворачивают в батчи и планируют на часы низкой нагрузки. Базовый обмен ассортиментом с учётной системой при этом остаётся на CommerceML — про него отдельно в статье об интеграции магазина с 1С.

4. Кормить данными мобильное приложение

Мобильное приложение магазина — классический потребитель REST. Ему нужны каталог, карточки товаров, корзина, оформление заказа, личный кабинет. Здесь почти всегда делают собственный REST на стороне 1С-Битрикс (контроллеры D7): приложение ходит в ваши эндпоинты по токену, а вы контролируете формат, версионирование и права. Публичный REST для клиентского приложения обязан работать по HTTPS и с короткоживущими токенами.

5. Подключить чат-бота

Чат-бот (в чате портала или во внешнем мессенджере) обменивается сообщениями через REST и события: принимает входящие сообщения через исходящие вебхуки/события, отвечает через методы отправки сообщений. Для ботов Битрикс24 это группа imbot.*; для внешних мессенджеров — свой слой на стороне сайта. Ключевое требование — быстрый ответ на событие, иначе платформа сочтёт обработчик недоступным.

Магазин как хаб интеграций

Когда сценариев становится много, магазин на Битриксе превращается в центральный хаб: он и отдаёт данные наружу, и принимает их, и оркестрирует обмен между внешними системами. Держать в голове эту картину полезно — она подсказывает, где заложить общие механизмы (журнал, очередь, ретраи), а не изобретать их заново для каждой интеграции.

В центре — магазин (заказы, каталог, пользователи). Вокруг — CRM, учётная система 1С, склад, платёжные и доставочные сервисы, маркетплейсы, мобильное приложение, чат-бот. REST — это «шина», по которой они общаются. Чем больше спиц у такого колеса, тем важнее единые правила: общий формат ошибок, единый журнал обмена, централизованная обработка лимитов и ретраев.

Безопасность REST-интеграций

REST открывает доступ к данным и операциям — значит, к нему применимы все базовые требования безопасности, и пренебрегать ими нельзя. Собрали ключевые меры, которые должны быть в каждой интеграции.

• Не «светите» вебхук. Код входящего вебхука — это пароль. Ему не место в клиентском JavaScript, в публичном репозитории, в письмах и мессенджерах. Храните секреты на сервере и в защищённом хранилище, а не в коде.
• Минимальные права (scope). Давайте вебхуку или приложению ровно те права, что нужны сценарию, и не больше. Если интеграция только читает каталог — не выдавайте ей доступ к CRM и пользователям.
• Только HTTPS. Весь обмен — по шифрованному каналу. По открытому HTTP токены и данные можно перехватить.
• Подпись входящих запросов. Для своих эндпоинтов и обработчиков исходящих вебхуков проверяйте подпись/токен, чтобы отличить настоящий запрос от подделки. Обработчик, который принимает что угодно, — открытая дверь.
• Ротация и отзыв. Токены приложений должны обновляться и отзываться, а вебхуки — пересоздаваться при подозрении на утечку. Предусмотрите процедуру «сменить ключи» заранее.
• Валидация входных данных. Никогда не доверяйте тому, что пришло снаружи: проверяйте типы, диапазоны, права на конкретную сущность. Внешний вызов не должен уметь прочитать чужой заказ, подставив чужой ID.

Подключение первой интеграции по шагам

Сведём всё в практический маршрут. Возьмём типовую задачу «передавать заказы с сайта во внешнюю систему» и пройдём её от постановки до боевого запуска.

1. Определите систему и модель. Битрикс24 или 1С-Битрикс? Вебхук, приложение или свой REST? От этого зависит всё остальное. Для внутреннего серверного обмена чаще берут вебхук или свой эндпоинт на D7.
2. Составьте список методов и прав. Выпишите конкретные методы под сценарий и требуемый scope. Создайте вебхук/приложение ровно с этими правами.
3. Настройте канал. Для «толчка наружу» — исходящий вебхук/событие на нужное действие; для «забирают у нас» — защищённый метод отдачи данных. Пропишите HTTPS и проверку подписи.
4. Заложите идемпотентность. Передавайте внешний ключ (номер заказа) и на приёмнике делайте upsert, чтобы повтор не создавал дубль.
5. Добавьте ретраи и очередь. Отправляйте не в момент действия пользователя, а фоново из очереди, с экспоненциальными повторами и лимитом попыток.
6. Сверните массовое в батчи. Если операций много — группируйте до 50 команд в один запрос и выдерживайте паузы под лимиты.
7. Включите журнал обмена. Логируйте запросы, ответы, попытки и статусы — это ваш главный инструмент отладки на бою.
8. Протестируйте на реальных данных и краевых случаях. Проверьте недоступность приёмника, истёкший токен, превышение лимита, повторную доставку — интеграция должна их пережить без потерь и дублей.

Частые ошибки

Грабли, на которые чаще всего наступают в REST-интеграциях Битрикса:

• Путают Битрикс24 и 1С-Битрикс. Ищут «готовый REST с crm.*» в магазине на БУС или пытаются на сайте развернуть модель портала. Сначала определите систему.
• «Светят» вебхук-код. Кладут постоянный код в клиентский код или репозиторий. Утечка = полный доступ к порталу.
• Игнорируют поле error. Проверяют только HTTP-код 200 и считают операцию успешной, хотя в теле ответа ошибка. Появляются «тихие» баги.
• Шлют по одному вместо батча. Сотни одиночных вызовов вместо пачек по 50 — медленно и упирается в лимиты.
• Не обрабатывают лимиты. При превышении лимита повторяют мгновенно и в цикле, получая блокировку вместо паузы.
• Нет идемпотентности. Ретраи без внешнего ключа плодят задвоенные заказы и сделки.
• Отправляют синхронно в момент действия. Обмен идёт прямо при оформлении заказа; приёмник тормозит — тормозит и оформление у покупателя.
• Забывают про пагинацию. Ждут все записи одним вызовом и не читают next, теряя часть данных за первой страницей.
• Выдают лишние права. Вебхук с полным доступом «на всякий случай» — расширенная поверхность атаки при утечке.
• Нет журнала обмена. На бою нечем понять, что ушло, что упало и сколько было попыток.

Чек-лист REST-интеграции

Короткий список для приёмки интеграции перед запуском:

• Определена система (Битрикс24 или 1С-Битрикс) и модель (вебхук / приложение / свой REST).
• Выданы минимальные права (scope) под конкретный сценарий, лишнего нет.
• Секреты и токены хранятся на сервере, не попадают в клиент и репозиторий.
• Весь обмен идёт по HTTPS; входящие запросы проверяются по подписи/токену.
• Ответы разбираются с проверкой поля error, а не только HTTP-кода.
• Списки читаются с пагинацией через start/next до конца.
• Массовые операции свёрнуты в батчи (до 50 команд), выдержаны паузы под лимиты.
• Реализованы ретраи с экспоненциальной задержкой и лимитом попыток.
• Обеспечена идемпотентность по внешнему ключу (upsert вместо слепого add).
• Обмен асинхронный: события идут через очередь и фоновый процесс.
• Ведётся журнал обмена: запрос, ответ, число попыток, статус.
• Проверены краевые случаи: недоступность приёмника, истёкший токен, лимит, повторная доставка.

Вывод

REST API в Битриксе — это не одна технология, а набор инструментов под разные задачи, и половина успеха интеграции закладывается ещё до кода: нужно правильно выбрать систему (Битрикс24 или 1С-Битрикс) и модель доступа (вебхук, приложение или свой REST на контроллерах D7). Входящий вебхук — чтобы дёргать методы; исходящий — чтобы принимать события; OAuth и приложения — для тиражируемых решений; собственный REST на D7 — когда сайту нужен свой API под мобильное приложение, чат-бот или обмен с внешней системой.

Дальше всё решает инженерная аккуратность: батчи вместо потока одиночных вызовов, пагинация до конца списка, уважение к лимитам, ретраи с задержкой, идемпотентность против дублей и журнал обмена для прозрачности. Сделайте эти вещи системно — и REST превратит магазин на 1С-Битрикс в надёжный хаб интеграций, который спокойно переживает и пики нагрузки, и временную недоступность соседних систем. А если нужна помощь с проектированием и разработкой такого API — это как раз наша услуга по REST для 1С-Битрикс, смежные материалы ищите в рубрике разработка и архитектура.