Интеграция интернет-магазина с Битрикс24: заказы, клиенты и статусы

Интеграция интернет-магазина с Битрикс24 строится вокруг заказа, покупателя, товарных позиций, оплат, отгрузок и состояний исполнения. Начинать нужно не с вебхука или REST-метода, а с карты данных: где возникает значение, в каком объекте оно хранится и какая система может его изменять.

Интернет-заказ не обязан становиться сделкой. В Битрикс24 есть самостоятельный объект заказа с корзиной, оплатами, отгрузками и статусами. Сделка или смарт-процесс нужны только в выбранной бизнес-схеме: например, когда заказ проходит воронку, согласование или отдельный сервисный маршрут.

Что определить до разработки

Передача данных в CRM не означает, что нужно копировать в неё все поля сайта. Для каждого значения следует определить:

• объект-получатель;
• источник данных;
• правило создания и обновления;
• внешний идентификатор;
• действие при повторном событии;
• ответственного за спорные случаи.

Заказ в Битрикс24 может содержать сведения о клиенте, товарах или услугах, количестве, стоимости и статусе выполнения. Отдельно учитываются корзина, оплаты, отгрузки и свойства заказа. Поэтому одна карточка сделки не всегда подходит для хранения всей информации о покупке.

Если требуется определить CRM-маршрут, роли сотрудников и состав объектов, подходит внедрение CRM. Для разработки обмена с внешними системами важно заранее спроектировать интеграцию Битрикс24.

Какие системы участвуют в обработке заказа

В цепочке заказа могут участвовать сайт, Битрикс24, 1С, платёжный сервис и служба доставки. Они не становятся единой системой автоматически. У каждого поля должен быть понятный владелец.

Система или объект	Что в ней возникает	Что зафиксировать
Сайт интернет-магазина	Оформление, корзина, данные покупателя, выбранные оплата и доставка	Внешний ID, передаваемые поля, момент отправки
Заказ Битрикс24	Корзина, свойства, оплаты, отгрузки, статусы	Нужен ли отдельный заказ и что обновляется извне
Сделка Битрикс24	Воронка, работа менеджера, CRM-действия	Причина создания сделки и состав её полей
Смарт-процесс	Пользовательский маршрут	Тип, стадии, поля, права, роботы
1С	Обмен заказами с CMS, учётные статусы	Какие заказы выгружаются и какие статусы допустимы
Платёжный или логистический сервис	Возможные события конкретной интеграции: оплата, доставка, отмена или частичная отгрузка	Идентификатор заказа, правила повторов и обработки ошибок

В «1С-Битрикс: Управление сайтом» у заказа отдельно отражаются текущий статус, оплата, разрешение доставки, отмена и отгрузка. В REST API Битрикс24 также разделены заказ, корзина, оплата и отгрузка.

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

Карта интеграции должна содержать не только список полей формы заказа. Для каждого значения нужно указать объект-получатель: контакт, компания, заказ, корзина, оплата, отгрузка, сделка или смарт-процесс. Затем фиксируются источник, правило обновления и внешний идентификатор.

Какие данные передавать в Битрикс24

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

Обычно рассматривают:

• внешний идентификатор заказа;
• дату и время создания;
• состав корзины;
• валюту и тип плательщика;
• данные покупателя;
• свойства заказа;
• оплату и её состояние;
• отгрузку, состав и состояние;
• статусы, используемые в процессе.

В REST-сценарии интернет-магазина Битрикс24 товары или услуги сначала добавляют в корзину, затем создают заказ с данными клиента, валютой и составом корзины. Добавить товар в заказ без стадии корзины нельзя. Это правило относится к описанному REST-сценарию, а не к любому способу оформления заказа на внешнем сайте.

Свойства заказа стоит отделять от постоянных данных клиента. Адрес доставки или выбранное время могут относиться к конкретной покупке. В документации среди примеров свойств названы «Станция метро» и «Дата и время доставки», но это не обязательный набор для каждого магазина.

Заказ, сделка или смарт-процесс

Выбор объекта зависит от того, что происходит после оформления покупки.

Вариант	Когда применять	Что проверить
Заказ интернет-магазина	Нужно учитывать покупку, корзину, оплаты, отгрузки и свойства	Состав данных, связь с клиентом, правила обновления
Сделка	Заказ проходит CRM-воронку и работу менеджера	Причину создания, стадии, товарные строки, автоматизацию
Смарт-процесс	Требуется отдельный пользовательский маршрут	Тип сущности, обязательные поля, права и роботы

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

Универсальный метод crm.item.add создаёт системные и пользовательские объекты CRM, включая сделки, контакты, компании и смарт-процессы. Набор полей зависит от типа сущности. При создании проверяются права, обязательные и зависимые от стадии поля, корректность значений. Могут назначаться значения по умолчанию и запускаться роботы. Некорректное поле в массиве fields игнорируется.

Нельзя переносить одинаковую схему полей между контактом, сделкой и смарт-процессом без проверки конкретного объекта. Также не стоит механически дублировать один заказ во всех сущностях. Дополнительный объект нужен только при понятной задаче.

Товарные позиции и состав заказа

Товарная часть требует отдельного решения: какая система передаёт цену, количество, скидку, налог и единицу измерения. В товарной позиции сделки могут использоваться идентификатор и название товара, цена, количество, скидка, налог и единица измерения.

Если передаётся PRODUCT_ID, название и единица измерения могут быть получены из товара каталога. Однако наличие полей не означает, что в конкретном обмене необходимо передавать их все. Правила расчёта сумм, скидок и налогов определяются проектной схемой.

Метод crm.deal.productrows.set создаёт или обновляет товарные позиции сделки, но помечен как устаревший. Позиции, которые уже есть в сделке, но отсутствуют в переданном массиве, удаляются. Поэтому его нельзя использовать как безопасное частичное обновление без предварительного получения и формирования полного состава строк.

Для новых решений следует ориентироваться на crm.item.productrow.* и проверять актуальность методов перед реализацией.

Как связать заказ с клиентом

Перед созданием контакта, лида или компании можно искать совпадения по телефону и email через crm.duplicate.findbycomm. Метод ищет лиды, контакты и компании по типам коммуникации PHONE и EMAIL.

В одном запросе можно передать не более 20 значений. Поиск не учитывает добавочный номер телефона. Если по одному типу объектов найдено 20 или более дублей, результаты по следующим типам могут не вернуться.

Практический порядок обработки:

1. Нормализовать телефон и email по правилам проекта.
2. Выполнить поиск по телефону, email или обоим типам коммуникации.
3. Разобрать совпадения отдельно для лидов, контактов и компаний.
4. Если карточка одна и правило связи однозначно, привязать к ней заказ или CRM-объект.
5. Если найдено несколько карточек, не объединять их автоматически только по результату поиска.
6. Сохранить внешний ID заказа и результат обработки.
7. При повторном событии сначала проверить, не создан ли объект ранее.

Совпадение по телефону или email не подтверждает личность клиента. Один номер может использоваться несколькими людьми, а общий email — несколькими сотрудниками. Для неоднозначного результата нужен отдельный сценарий: дополнительная проверка, передача записи сотруднику или создание объекта без автоматического слияния.

Поиск совпадений помогает выбрать сценарий обработки, но не является основанием для автоматического объединения CRM-карточек. Правило связи клиента нужно описать до запуска обмена.

Внешний ID и повторная обработка

Внешний идентификатор заказа нужен для связи объектов и проверки повторной обработки. Одно уведомление может прийти несколько раз, обработчик может завершиться ошибкой после создания объекта, а внешний сервис может повторно отправить одно состояние.

Без правила идемпотентности повторное событие способно создать второй заказ, сделку, оплату или отгрузку. Поэтому во внешнем обмене следует хранить внешний ID и журналировать результат обработки.

Минимальный набор состояний журнала:

• создано;
• обновлено;
• пропущено как повтор;
• ожидает повтора;
• требует разбора;
• завершилось ошибкой.

Для каждого события полезно хранить идентификатор исходной системы, время получения, целевой объект и причину ошибки. Это проектное требование к надёжности обмена, а не заявленная функция отдельного REST-метода.

Оплата, отгрузка и статусы

Оплата, отгрузка и статус заказа — разные сущности и состояния. Их не следует сводить к одному полю «Статус».

Оплата содержит информацию о платёжной системе, статусе и дате оплаты, а также идентификаторе плательщика. Оплату можно связать с позициями корзины при частичной оплате и с конкретной отгрузкой.

Отгрузка позволяет учитывать, какие товары отправлены, в каком количестве и когда. У одного заказа может быть несколько независимых отгрузок. У каждой могут быть свои служба доставки, статус и состав товаров.

Если заказ исполняется частями, для каждой отправки можно использовать свойства отгрузки. Официальный пример описывает передачу адреса как свойства отдельных отправок, когда товары направляются по разным адресам.

Таблица показывает варианты проектной схемы. Фактический источник каждого события определяют по конкретной интеграции.

Событие	Возможный источник в проектной схеме	Какой объект меняется	Что проверить
Заказ оформлен	Сайт интернет-магазина	Заказ сайта и объект Битрикс24 по выбранной схеме	Внешний ID, клиент, корзина
Оплата подтверждена	Платёжный или иной согласованный контур	Оплата	ID платежа, сумма, дата, повтор
Товар передан в доставку	Один из согласованных контуров: склад, сайт или логистический сервис	Отгрузка	Состав, количество, служба доставки
Доставка завершена	Согласованный логистический контур	Статус отгрузки или согласованное поле	Связь с конкретной отгрузкой
Менеджер согласовал действие	Битрикс24	Сделка или смарт-процесс	Не подменяет оплату и доставку

В «1С-Битрикс: Управление сайтом» статусы могут иметь тип «Заказ» или «Доставка», уникальный код, сортировку, название, описание, цвет и права доступа. Их нельзя автоматически приравнивать к стадиям сделок Битрикс24 или к статусам внешней службы доставки.

Когда подключать 1С

1С участвует в цепочке, когда требуется обмен заказами между CMS и учётной системой. Наличие 1С само по себе не определяет, какие данные она должна считать главными. Это отдельно согласуется для заказов, статусов, цен, остатков и клиентов.

В «1С-Битрикс: Управление сайтом» можно выбрать сайт для выгрузки, передавать только оплаченные заказы или только заказы с разрешённой доставкой, задать начальный статус выгрузки и разрешить изменение статусов сайта по данным из 1С.

Если включено изменение статусов по данным из 1С, сайт меняет статус после обмена в соответствии с полученной информацией. Это не означает мгновенную синхронизацию: частота и фактическая схема зависят от настроек и реализации.

Для отдельных контуров могут потребоваться интеграция Битрикс24 с 1С и интеграция сайта с 1С. Штатный обмен CMS с 1С и REST-обмен Битрикс24 с внешними системами решают разные задачи, хотя могут работать в одной цепочке.

Штатная интеграция интернет-магазина CMS с CRM требует адреса CRM и учётных данных администратора. При ручной настройке пользователю нужен полный доступ к модулю «Интернет-магазин» и доступ не ниже чтения к модулю «Торговый каталог». В документации указано, что функция недоступна в редакциях «Стандарт» и «Старт» «1С-Битрикс: Управление сайтом». Это ограничение относится к CMS, а не к тарифам Битрикс24.

REST API, вебхуки и события

Входящий вебхук вызывает REST-методы от имени сотрудника, который его создал. Его возможности ограничены правами сотрудника и выбранными scope. Часть методов недоступна через входящий вебхук, поскольку требует контекста приложения.

Исходящий вебхук отправляет событие Битрикс24 на URL обработчика. Сервер обработчика должен быть доступен извне. Для облачного Битрикс24 дополнительная настройка доступности не требуется, а для коробочной версии её нужно настраивать на сервере или хостинге.

URL входящего вебхука содержит секретный код, который даёт доступ к методам в пределах выданных прав. Его нельзя публиковать в клиентском коде, примерах, комментариях, открытых репозиториях или материалах для клиентов. У входящего вебхука может быть срок действия; после его окончания запросы завершатся ошибкой авторизации.

Для сделок предусмотрены события создания, изменения, удаления и смены воронки. Они позволяют приложениям реагировать на изменения практически в реальном времени. Однако событие передаёт только идентификатор сделки в data.FIELDS.ID. Полные данные нужно отдельно получать через crm.deal.get.

Смена воронки отслеживается отдельным событием onCrmDealMoveToCategory, а не onCrmDealUpdate. Подписка на onCrmDealAdd, onCrmDealUpdate и onCrmDealDelete доступна через исходящий вебхук либо приложение с event.bind. Подписка на onCrmDealMoveToCategory доступна только через приложение с event.bind.

Лимиты и обработка ошибок

В облачном Битрикс24 REST-запрос должен завершиться не позднее 60 секунд, иначе он прерывается по таймауту. На длительность влияют объём данных, сложность фильтров, вложенные вызовы batch и автоматизация, запускаемая методом.

В коробочной версии время выполнения зависит от настроек сервера. Для крупных операций документация рекомендует делить данные на запросы, использовать постраничную выборку и выносить длительные сценарии во внешнюю очередь или фоновую обработку.

Метод batch позволяет передать до 50 вызовов в одном HTTP-запросе, но не отменяет ограничений по ресурсоёмкости. REST API не предназначен для массового интенсивного обмена большими данными.

При превышении порога интенсивности запрос может быть заблокирован с HTTP-статусом 503 и кодом QUERY_LIMIT_EXCEEDED. Пороговые параметры, состав методов, права и статус устаревания нужно перепроверять перед запуском конкретной интеграции.

Рабочая схема обработки ошибок включает:

1. Использование внешнего ID заказа или технического ID события.
2. Проверку, был ли объект создан или обновлён ранее.
3. Журналирование результата каждой попытки.
4. Повторную обработку с ограничением числа попыток.
5. Фиксацию причины ошибки.
6. Передачу неразобранной записи ответственному сотруднику.
7. Использование очереди для длительных и массовых операций.

Проверка нового и повторного заказа

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

Проверочный сценарий:

1. Оформить тестовый заказ с новым телефоном и email.
2. Проверить создание заказа на сайте и наличие внешнего идентификатора.
3. Запустить передачу в Битрикс24.
4. Убедиться, что создан согласованный объект: заказ, сделка, смарт-процесс или набор связанных объектов.
5. Сверить корзину: товары, количество, цену и согласованные поля.
6. Проверить создание или связь карточки клиента.
7. Передать то же событие повторно с тем же внешним ID.
8. Убедиться, что второй объект не появился.
9. Проверить запись журнала повторной обработки.
10. Передать изменение оплаты и проверить объект оплаты.
11. Передать изменение отгрузки и проверить нужную отправку.
12. Проверить ошибочный сценарий: недоступный обработчик, некорректное поле или лимит.
13. Убедиться, что повтор не повреждает созданные данные.

Если используются товарные строки сделки, нужно проверять не только добавление. При применении crm.deal.productrows.set неполный массив способен удалить отсутствующие позиции. Для новых решений состав товарной части следует строить с учётом актуальных методов crm.item.productrow.*.

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

• [ ] Для каждого типа данных определён объект: заказ, контакт, компания, сделка, смарт-процесс, оплата или отгрузка.
• [ ] Указан внешний идентификатор заказа и правила его хранения.
• [ ] Для каждого поля определён источник: сайт, Битрикс24, 1С, платёжный или логистический сервис.
• [ ] Зафиксировано, какие поля разрешено обновлять из каждого контура.
• [ ] Составлена таблица соответствий статусов заказа, оплаты, отгрузки и CRM-маршрута.
• [ ] Указано, когда создаётся сделка и когда заказ остаётся самостоятельным объектом.
• [ ] Описан поиск клиента по телефону и email.
• [ ] Зафиксировано действие при нескольких совпадениях.
• [ ] Согласован состав товарных позиций и источник цены, скидки, налога и единицы измерения.
• [ ] Описаны частичная оплата и несколько отгрузок, если они есть в процессе.
• [ ] Проверены права вебхука или приложения и место хранения секретов.
• [ ] Предусмотрены очередь, журналирование, повторная обработка и разбор ошибок.
• [ ] Подготовлены сценарии нового заказа, повторного события, спорного совпадения и частичного исполнения.
• [ ] Проверены ограничения конкретного портала и используемых REST-методов.

FAQ

Нужно ли создавать сделку для каждого заказа интернет-магазина?

Нет. В Битрикс24 есть самостоятельный объект заказа с корзиной, оплатами и отгрузками. Сделка нужна, если заказ должен проходить CRM-воронку и работу менеджера.

Можно ли считать оплату статусом заказа?

Нет. Оплата — отдельный объект со своим статусом и датой оплаты. Статус заказа, статус оплаты и статус отгрузки нужно описывать раздельно.

Как не создавать дубль клиента?

До создания CRM-карточки можно искать совпадения по телефону и email через crm.duplicate.findbycomm. При нескольких совпадениях нужен отдельный сценарий разбора: поиск не подтверждает личность клиента.

Можно ли передавать часть товарных позиций в сделку?

Нужно учитывать используемый метод. Устаревший crm.deal.productrows.set удаляет позиции, которых нет в переданном массиве. Для частичных изменений следует проверять актуальные методы crm.item.productrow.*.

Будет ли обмен работать в реальном времени?

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

Можно ли использовать вебхук для любой интеграции?

Нет. Входящий вебхук действует от имени создавшего его сотрудника, ограничен правами и scope. Часть методов требует контекста приложения. Секретный URL вебхука нельзя публиковать.

Зачем нужна очередь, если есть batch?

batch объединяет до 50 REST-вызовов в одном HTTP-запросе, но не отменяет лимиты интенсивности и ресурсоёмкости. Очередь нужна для длительных операций, контролируемых повторов и журналирования.

Резюме

Интеграция интернет-магазина с Битрикс24 начинается с модели данных. Заказ, клиент, товарные позиции, оплата, отгрузка и CRM-маршрут должны быть разделены по смыслу. Для каждого элемента нужны объект-получатель, внешний ID, источник изменений и сценарий повторной обработки.

Если стандартных объектов недостаточно для выбранного процесса, потребуется разработка и доработка Битрикс24. До начала работ важно описать реальные действия сотрудников, события обмена и порядок обработки ошибок.