Заказ с сайта прилетел в Битрикс24. Менеджер видит карточку, склад видит задачу, бухгалтерия ждёт оплату. А через месяц выясняется, что одна и та же покупка заведена трижды: как сделка, как контакт с опечаткой и как анонимный заказ без телефона. Знакомая картина для тех, кто строил обмен «в лоб».
Разбираем, как устроена интеграция интернет-магазина с Битрикс24, чтобы такого не случалось.
Заказ — не сделка
Главное, что стоит принять до написания кода: интернет-заказ не обязан становиться сделкой. В Битрикс24 есть самостоятельный объект заказа с корзиной, оплатами, отгрузками и статусами. Этого достаточно, чтобы учитывать покупку.
Сделка нужна в другом случае — когда заказ должен проходить CRM-воронку: менеджер дозванивается, согласует замену, проводит по стадиям. Есть и третий путь — смарт-процесс, когда ни логика заказа, ни логика сделки не подходят, и процесс требует собственного маршрута.
Выбор объекта — проектное решение. Его принимают до разработки, а не после первых дублей.
Карта данных вместо вебхука
Типичная ошибка — начать с технологии: «прикрутим входящий вебхук и будем слать данные». Правильнее начать с карты данных. Для каждого значения из формы заказа отвечают на вопросы:
- в каком объекте оно хранится: контакт, компания, заказ, сделка, смарт-процесс, оплата, отгрузка;
- кто его владелец — сайт, Битрикс24, 1С, платёжный или логистический сервис;
- можно ли его обновлять извне и кто выигрывает при конфликте;
- что делать, если значение пришло повторно.
Поля «на всякий случай» — источник грязи. Сотрудник видит значение, меняет его, а следующий обмен молча возвращает старое. Через месяц никто не верит системе.
Оплата, отгрузка, статус — три разные сущности
«Заказ оплачен» и «товар передан в доставку» — это разные события. Первое меняет объект оплаты, второе — отгрузку. У одного заказа может быть несколько отгрузок с разными службами доставки и составами. Частичная оплата привязывается к позициям корзины.
Сводить всё это к одному полю «Статус» — значит потерять данные. В «1С-Битрикс: Управление сайтом» статусы бывают типов «Заказ» и «Доставка», у них есть коды, сортировка и права. Их нельзя механически приравнивать к стадиям сделок — это разные модели.
Как не плодить дублей клиентов
Перед созданием контакта или компании стоит искать совпадения. Метод crm.duplicate.findbycomm ищет лиды, контакты и компании по телефону и email. Ограничения важно знать заранее: не более 20 значений в запросе, добавочный номер не учитывается, а при 20+ дублях по одному типу остальные типы могут не вернуться.
Но совпадение по телефону не подтверждает личность. Один номер могут использовать несколько человек, общий email — несколько сотрудников. Поэтому правило связи описывают до запуска обмена: что делать при однозначном совпадении, при нескольких, при отсутствии. Автоматическое слияние по результату поиска — путь к потере истории.
Внешний ID и идемпотентность
Внешний идентификатор заказа — фундамент надёжности. Одно уведомление может прийти несколько раз: вебхук повторил, обработчик упал после создания объекта, внешний сервис переотправил состояние. Без проверки «уже обрабатывали» повтор создаст второй заказ, вторую сделку, вторую оплату.
Рабочий минимум — журнал с состояниями: создано, обновлено, пропущено как повтор, ожидает повтора, требует разбора, завершилось ошибкой. Плюс ограничение числа повторов и передача неразобранных записей ответственному.
Товарные позиции и API-нюансы
Состав заказа в REST-сценарии строится через корзину: сначала товары добавляются в корзину, потом создаётся заказ. Обходить стадию корзины в этом сценарии нельзя.
Второй нюанс — устаревший crm.deal.productrows.set. Он удаляет из сделки позиции, которых нет в переданном массиве. Передать «только изменившиеся строки» не выйдет — сделка потеряет остальное. Для новых решений смотрят на семейство crm.item.productrow.* и проверяют актуальность методов перед реализацией.
Универсальный crm.item.add создаёт системные и пользовательские CRM-объекты, но набор полей зависит от типа сущности. Некорректное поле в fields просто игнорируется — ошибки вы не увидите, данные не запишутся.
Лимиты, о которых болит голова
- Облачный REST-запрос должен уложиться в 60 секунд, иначе обрыв по таймауту.
-
batchобъединяет до 50 вызовов, но лимиты ресурсоёмкости не отменяет. - При превышении интенсивности — HTTP 503 с кодом
QUERY_LIMIT_EXCEEDED. - Входящий вебхук действует от имени сотрудника, ограничен правами и scope; часть методов требует контекста приложения.
- Секретный URL вебхука нельзя публиковать нигде — ни в клиентском коде, ни в примерах.
Длительные и массовые операции выносят во внешнюю очередь с постраничной выборкой.
Чек-лист перед запуском
- Для каждого типа данных выбран объект-получатель.
- Назначен внешний ID заказа и правила его хранения.
- Для каждого поля зафиксирован источник и владелец.
- Описано, когда заказ остаётся заказом, а когда рождается сделка.
- Написан сценарий поиска клиента и действие при нескольких совпадениях.
- Согласованы частичные оплаты и несколько отгрузок, если они есть.
- Проверены права вебхука или приложения и место хранения секретов.
- Подготовлены сценарии: новый заказ, повторное событие, спорное совпадение, частичное исполнение, ошибочный вебхук.
Интеграция магазина с Битрикс24 начинается с модели данных, а не с кода. Заказ, клиент, товарные позиции, оплата, отгрузка и CRM-маршрут разводят по смыслу — и каждый обмен становится предсказуемым.
Top comments (0)