Справочник объектов автоматизации

Объекты автоматизации — это структуры данных, которые RetailCRM передаёт в контекст триггеров, PipeLang-выражений и Twig-шаблонов. Зная их поля и вложенность, вы точно обращаетесь к нужным данным заказа и клиента и не тратите время на догадки.

Контекст события

Автоматизация всегда работает в контексте события: создан заказ, сменился статус, зарегистрировался клиент. Событие определяет, какие объекты доступны. Чаще всего это order и customer, но состав контекста меняется.

• События заказа — доступен order и через него вложенный клиент order.customer;
• События клиента — доступен customer, но не обязательно конкретный заказ;
• Служебные данные — сведения о самом событии: что изменилось и когда.

Контекст формируется в момент срабатывания и отражает состояние данных на этот момент. Если триггер реагирует на смену статуса, ему доступно и новое, и предыдущее значение поля — это позволяет строить правила вида "сработать только при переходе из статуса A в статус B". Понимание того, какие данные и в какой момент попадают в контекст, избавляет от самой частой ошибки автоматизации — обращения к полю, которого на этом шаге ещё или уже нет.

Объект order

Заказ — центральный объект автоматизации. Его поля повторяют структуру, знакомую по API v5, поэтому справочник методов и справочник объектов дополняют друг друга.

Обращение к полю идёт через точку: order.delivery.code вернёт код способа доставки, а order.status — текущий статус. Вложенность может быть глубокой: адрес доставки лежит в order.delivery.address, а стоимость — в order.delivery.cost. Финансовые поля стоит различать: totalSumm — итог по заказу, тогда как сумма только товаров считается по позициям. Статус приходит символьным кодом, а не человекочитаемым названием, поэтому в условиях сравнивают именно код, например order.status == "assembling". Такой же принцип действует для способа оплаты и типа заказа — везде используются коды из настроек справочников.

Позиции заказа items

Поле order.items — массив позиций. Каждая позиция описывает конкретный товар в заказе и вложенный торговый оффер.

• item.quantity — количество;
• item.initialPrice — цена за единицу;
• item.offer.name — название товарного предложения;
• item.offer.article — артикул;
• item.offer.externalId — идентификатор во внешней системе.

В Twig позиции перебирают циклом {% for item in order.items %}, в PipeLang к массиву применяют функции: order.items | length вернёт число позиций, а order.items | sum: "totalSumm" — суммарную стоимость товаров.

Объект customer

Клиент доступен напрямую как customer в событиях клиента и как order.customer внутри заказа. Его основные поля:

Телефон — это массив, поэтому первый номер получают так: customer.phones | first. Обращение к вложенному полю телефона зависит от структуры и уточняется на конкретных данных.

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

Пользовательские поля

Пользовательские поля создаются в настройках RetailCRM и доступны через объект customFields и заказа, и клиента. Ключ — это символьный код поля, заданный при создании.

Например, поле лояльности с кодом loyalty_level читается как order.customFields.loyalty_level. Поскольку значение может быть не заполнено, в выражениях его подстраховывают:

order.customFields.loyalty_level | default: "base"

Единый доступ из PipeLang и Twig

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

Если сомневаетесь в наличии или структуре поля, сверьтесь со справочником методов API v5 — модель данных автоматизации и API совпадает по составу сущностей.

Итог

Справочник объектов — фундамент любой автоматизации в RetailCRM. Понимание структуры order, customer, вложенных items и пользовательских полей позволяет писать точные условия триггеров и корректные шаблоны без метода проб и ошибок.

Когда автоматизация упирается во внешние данные, сложную бизнес-логику или обмен с учётными системами, мы проектируем интеграционную архитектуру и разрабатываем API-решения, где модель данных RetailCRM аккуратно связана с вашими системами.