Типовые сценарии обмена через REST

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

Как устроен REST-обмен в Битриксе

REST в Битриксе — это набор методов, сгруппированных по скоупам: crm, catalog, sale, user и другие. Каждый метод вызывается по HTTP и возвращает JSON. Формат имени говорит сам за себя:

• *.add — создать сущность;
• *.update — изменить;
• *.get — получить одну запись по ID;
• *.list — получить список с фильтром и пагинацией;
• *.delete — удалить.

Ответ list-методов содержит поле next и total — по ним организуют постраничную выборку по 50 записей. Понимание этой азбуки экономит массу времени при проектировании обмена.

Сценарий 1: заявки с сайта в CRM

Самый частый сценарий. Форма на лендинге или внешний сервис создаёт лид или сделку в CRM. Схема простая, но есть нюансы.

1. Событие (отправка формы) вызывает входящий вебхук с методом crm.lead.add или crm.deal.add.
2. В fields передаются имя, телефон, сумма, источник и UTM-метки.
3. Множественные поля (телефон, почта) передаются массивом с VALUE и VALUE_TYPE.

Чтобы не плодить дубли при повторной отправке, перед созданием ищут контакт: crm.duplicate.findbycomm по телефону или почте. Если контакт найден — сделку привязывают к нему.

Сценарий 2: заказы между сайтом и учётной системой

Заказы — двусторонний обмен: с сайта в учётную систему уходит новый заказ, обратно приходят статусы оплаты и отгрузки. В REST заказы живут в скоупе sale.

Ключевой принцип — внешний идентификатор. Храните связь между ID заказа на сайте и в учётной системе, чтобы обратные статусы прилетали в нужный заказ, а не создавали новый. Без этого маппинга двусторонний обмен разваливается.

Сценарий 3: каталог, цены и остатки

Выгрузка каталога через REST оправдана для небольших объёмов и точечных обновлений. Большие каталоги (десятки тысяч SKU) правильнее гнать через CommerceML — REST на таких объёмах упрётся в лимиты.

• Товары — catalog.product.*, торговые предложения — catalog.product.offer.*.
• Цены — catalog.price.* с привязкой к типу цены (базовая, дилерская).
• Остатки — catalog.storeproduct.* по складам.

Цены и остатки меняются чаще всего, поэтому их синхронизируют инкрементально — только изменённые позиции. Полную выгрузку каталога держат на отдельном, редком расписании.

Batch, идемпотентность и пагинация

Три техники, без которых промышленный REST-обмен не живёт.

• Batch. Метод batch позволяет упаковать до 50 команд в один запрос и ссылаться на результат предыдущей через $result. Это резко снижает число обращений и обходит часть rate limit.
• Идемпотентность. Повтор запроса не должен создавать дубль. Достигается поиском по внешнему ключу перед add либо связкой «найти → обновить или создать».
• Пагинация. list-методы отдают по 50 записей. Для больших выборок используют параметр start и фильтрацию по ID вместо смещения — так выборка не «плывёт» при вставках.

Пример пагинации по ID: фильтр filter[>ID]=последний_ID с сортировкой по возрастанию быстрее и стабильнее, чем сквозной start на больших таблицах.

REST или CommerceML: как выбрать

Частая ошибка — тянуть весь обмен через REST, включая тяжёлый каталог. Ориентир для выбора инструмента:

Часто оптимальна связка: каталог идёт по CommerceML, а события и статусы — по REST. Так каждый инструмент работает в своей зоне эффективности.

Итог

Типовые сценарии REST-обмена сводятся к четырём: заявки в CRM, двусторонние заказы, точечные правки каталога и синхронизация цен с остатками. На каждом держатся три техники — batch, идемпотентность и правильная пагинация по внешнему ключу. А тяжёлый каталог всегда лучше отдать CommerceML.

Мы в B2Bsite проектируем обмен так, чтобы каждый инструмент работал в своей зоне: REST — для событий и заказов, CommerceML и собственный импортёр — для объёмов. В результате связка не упирается в лимиты и не плодит дубли даже под нагрузкой.