Использование переменных маркета в сообщениях

Переменные

В маркете доступны четыре переменные:

• products — функция выбирает продукты.

{products("<filter>" 10 "manufacturer_name" "desc")}

• sku — функция выбирает SKU.

{sku("<filter>" 10 "manufacturer_name" "desc")}

• orders — функция выбирает заказы из списка заказов профиля.

{orders("<filter>" 10 "status" "asc")}

• order — функция выбирает один заказ из списка заказов профиля.

{order("<filter>")}

Аргументы функции

("<filter>" 10 "manufacturer_name" "desc")

Аргумент	Обязательный	Описание
"<filter>"	Да	Фильтр — это строка условий. Позволяет выбрать продукты, SKU, заказы или позиции заказов, соответствующие заданным условиям. Например, можно выбрать продукты одного производителя или заказы, превышающие конкретную сумму. Подробную информацию смотрите ниже.
10	Да	Лимит. Сколько элементов массива необходимо перебрать. Максимальное значение — 30. Например, если указать значение 10, то фильтр выберет первые десять элементов из массива.
"manufacturer_name"	Нет	Сортировка объектов по указанному полю. По умолчанию — без сортировки.
"desc"	Нет	Направление сортировки. asc — по возрастанию (сортировка по умолчанию) desc — по убыванию

Фильтр

Фильтр состоит из полей и операторов. Поля есть у каждого объекта в маркете. Например, у продуктов и SKU есть поле name (наименование товара), а у заказов есть поле total_price (общая стоимость заказа). В фильтре вы указываете поле и значение, которому оно должно соответствовать. Если поле объекта соответствует значению, то этот объект будет выбран и его данные можно будет подставить в шаблон.

Пример фильтра

Добавим в шаблон переменную "Заказы":

{orders (("order.total_price == '1000 RUB') && (order.custom_fields.field == 'lead._region')" 10 "id" "desc")}

Выделенная часть переменной является фильтром. Разберем его по частям:

• order.total_price == '1000 RUB' — условие выберет все заказы, стоимость которых равна 1000 рублей.

• order.custom_fields.field == 'lead._region' — условие выберет заказы с дополнительным полем "field". Вместо "field" можно указать любое дополнительное (пользовательское) поле. Указанное равенство означает то, что значение поля "field" должно совпадать со значением региона в профиле клиента ("lead._region").

• Оператор && указывает на то, что оба условия должны быть выполнены.

• Число 10 означает количество выводимых объектов, "id" указывает на поле фильтрации, а "desc" — на сортировку по убыванию.

Ниже приведены поля и операторы, доступные в фильтре.

Операторы и функции в фильтре

Оператор	Описание	Пример	Что будет выбрано
>	больше	order.delivery_cost > '300 RUB'	Заказы со стоимостью доставки больше 300 рублей
>=	больше или равно	order.delivery_cost >= '300 RUB'	Заказы со стоимостью доставки 300 рублей или больше
<	меньше	sku.count < '10'	SKU, которых осталось меньше 10 штук для продажи
<=	меньше или равно	sku.count <= '10'	Количество SKU для продажи равно 10 или больше
==	равно	order.status == '1' order.custom_fields('дата') == '2024-12-25'	Заказы со статусом "новый" Заказы с датой 25 декабря 2024
!=	не равно	product.manufacturer_name != 'Apple'	Продукты, производителем которых не является Apple
&&	И (оба условия соответствуют)	product.manufacturer_name == 'Apple' && product.price < '200 USD'	Продукты производителя Apple со стоимостью больше $200
||	ИЛИ (одно из условий соответствует)	sku.manufacturer_name == 'MSI' || sku.manufacturer_name == 'Acer'	SKU с производителем MSI или Acer
in('<field_name>', 'value1', 'value2'...'valueN')	Значение поля (<field_name>) совпадает с одним из указанных значений ('value1', 'value2')	in(product.external_id,'1','2','3')	Продукты с идентификатором равным 1, 2 или 3
contains('<field_name>', 'value1', 'value2'...'valueN')	Один из элементов массива совпадает с одним из указанных значений. <field_name> — массив 'value1', 'value2' — значения, совпадение с которыми проверяется. Используется, если поле является массивом, т.е. содержит несколько элементов (например: категории, изображения, дополнительные поля).	contains(product.categories,'smartphone')	Продукты с категорией "smartphone"
len('<field_name>', <оператор>, <число> )	Проверяет длину массива. Сравнивает количество элементов в массиве с указанным числом. <field_name> — поле-массив (например, product.pictures) <оператор> — оператор сравнения (>, >=, <, <=, ==, !=) <число> — целое число для сравнения.	len(product.pictures, !=, 0)	Продукты, у которых количество картинок не равно нулю (т.е. есть хотя бы одна картинка)

Работа с пользовательскими полями

Для фильтрации по пользовательским полям доступно два синтаксиса:

Универсальный синтаксис (рекомендуется)

product.custom_fields('external_id')

к сведению

Мы рекомендуем использовать универсальный синтаксис product.custom_fields('external_id'), потому что он поддерживает любые типы идентификаторов — как числовые, так и строковые, включая специальные символы. Этот вариант гарантирует корректную работу фильтрации независимо от формата external_id вашего пользовательского поля.

Примеры:

{for $product in products("product.custom_fields('123') == 'красный'")}
{for $product in products("in(product.custom_fields('color'), 'red', 'blue')")}
{for $product in products("sku.custom_fields('45') > '100'")}

Строковый синтаксис (ограниченный)

product.custom_fields.field_name

к сведению

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

Пример:

{for $product in products("product.custom_fields.brand == 'Apple'")}

Список доступных полей в фильтрах

Продукты

Префикс — product.

Поле	Описание
product.external_id	Идентификатор продукта
product.name	Название продукта
product.manufacturer_name	Название производителя
product.url	URL страницы продукта на сайте магазина
product.pictures	URL-ссылка на картинку продукта
product.count	Количество продуктов, доступное для продажи
product.is_available	Есть ли продукт в наличии у магазина
product.delivery	Возможность курьерской доставки (по всем регионам, в которые доставляет магазин)
product.barcode	Список штрихкодов продукта от производителя
product.categories	Идентификатор категории продукта
product.custom_fields.<external_id поля>	Идентификатор дополнительного поля. Для числовых ID используйте custom_fields('123')

SKU

Префикс — sku.

Поле	Описание
sku.external_id	Идентификатор SKU
sku.name	Название SKU
sku.manufacturer_name	Название производителя
sku.url	URL страницы SKU на сайте магазина
sku.pictures	URL-ссылка на картинку SKU
sku.count	Количество SKU, доступное для продажи
sku.is_available	Есть ли SKU в наличии у магазина
sku.delivery	Возможность курьерской доставки (по всем регионам, в которые доставляет магазин)
sku.barcode	Список штрихкодов SKU от производителя
sku.categories	Идентификатор категории SKU
sku.custom_fields.<external_id поля>	Идентификатор дополнительного поля. Для числовых ID используйте custom_fields('123')

Заказы

Префикс — order.

Поле	Описание
order.external_id	Идентификатор заказа
order.status	Идентификатор статуса заказа 1 — новый 2 — доставлен 3 — оплачен 4 — отменен 5 — частичный возврат
order.delivery_cost	Стоимость доставки
order.total_price	Общая стоимость заказа. Складывается из суммы каждой позиции в заказе и стоимости доставки.
order.custom_fields.<external_id поля>	Идентификатор дополнительного поля. Для числовых ID используйте custom_fields('123')
order.real_create_time	Время создание заказа
order.real_update_time	Время обновления заказа
order.region_external_id	Идентификатор региона

Сортировка по пользовательским полям

Иногда требуется выполнить сортировку объектов по значениям пользовательских полей (объект custom_fields).
Пользовательские поля хранятся в базе в виде JSON-строки, поэтому для доступа к полю внутри JSON при сортировке можно использовать оператор ->.

Пример обращения к ключу:

custom_fields -> 'priority'

Использование в параметре сортировки функции (на примере products):

{for $index $el = products("contains(product.categories,'smartphone')" 3 "custom_fields -> 'priority'" "desc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

В этом примере список продуктов предварительно фильтруется по категории smartphone, затем сортируется по значению ключа priority внутри custom_fields по убыванию, и выводятся первые 3 результата.

к сведению

Важно

• Оператор -> используется только в параметре сортировки для обращения к ключу JSON.
• Для фильтрации по пользовательским полям применяется точечная нотация из раздела "Фильтр", например: order.custom_fields.field == 'value'.
• Оператор -> не является оператором маркета — это оператор базы данных (PostgreSQL), к которой выполняется запрос, поэтому такой способ сортировки следует рассматривать как обходное решение.

Как использовать переменные маркета

Любая переменная в маркете представляет собой массив. Например, переменная products будет содержать массив всех продуктов, загруженных в платформу, а переменная orders — массив заказов одного профиля. Чтобы перебрать массив, воспользуйтесь циклом с переменными.

Перебор массива продуктов (products)

Выводит в письме 5 продуктов от Apple:

Возможно, Вам будут интересны эти товары:
{for $index $el = products("product.manufacturer_name == 'Apple'" 5 "external_id" "desc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

7 самых дешевых смартфонов:

Лучшие цены на смартфоны для Вас и Ваших близких:
{for $index $el = products("product.categories == 'smartphone'" 7 "price" "asc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

Товары с доставкой:

Доставим до двери:
{for $index $el = products("product.delivery == true" 10 "name" "desc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

Перебор массива SKU (sku)

Смартфоны до 20000:

Смартфоны, которые Вам понравятся:
{for $index $el = sku("contains(sku.categories,'smartphone') && sku.price < '20000 RUB'" 3 "price" "asc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

IPhone с объемом памяти больше 128 ГБ:

Памяти хватит на всё:
{for $index $el = sku("contains(sku.name,'IPhone') && sku.custom_fields.memory >= '128'" 10 "name" "desc")}
{$el.name} — {$el.price}
{else}
if empty array
{end}

Перебор массива всех заказов (orders)

Заказы, прибывшие в пункт выдачи:

Заказы ждут Вас в пункте выдачи:
{for $index $el = orders("order.status == '2'" 10 "external_id" "desc")}
Заказ № {$el.external_id}
К оплате: {$el.total_price}
{else}
if empty array
{end}

Список новых заказов:

Новые заказы за последнюю неделю:
{for $index $el = orders("order.status == '1'" 20 "external_id" "desc")}
Заказ № {$el.external_id}
К оплате: {$el.total_price}
{else}
if empty array
{end}

Перебор позиций в заказе с id = '0001' (order + lines)

{for $index $el = order("order.external_id == '0001'")}
 {if $index equal "lines"}
  {for $i $line = $el}
    Название позиции: {$line.name}
    Цена позиции: {$line.final_price_of_line}
  {end}
 {end}

 {if $index equal "delivery_cost"}
   Стоимость доставки: {$el}
 {end}
 {if $index equal "total_price"}
   К оплате: {$el}
 {end}

{else}
if empty array
{end}

Список доступных полей для подстановки в шаблон

Продукты и SKU (products/sku)

Поле для подстановки	Описание
external_id	Идентификатор товара.
name	Название товара
manufacturer_name	Наименование производителя
url	URL страницы товара на сайте магазина
pictures	Список URL-ссылок на изображения товара (массив)
count	Количество товаров, доступное для продажи
available	Есть ли товар в наличии у магазина
delivery	Возможность курьерской доставки (по всем регионам, в которые доставляет магазин)
barcode	Список штрихкодов продукта от производителя (массив)
categories	Список идентификаторов категорий товара (массив)
custom_fields.<external_id поля>	Идентификатор дополнительного поля. Для числовых ID и специальных символов используйте синтаксис custom_fields('external_id')
price	Актуальная цена продукта
old_price	Старая цена продукта
regional_data.<region_external_id>.count	Количество товаров, доступное для продажи в указанном регионе. regional_data — это данные о продукте, которые могут различаться в зависимости от региона (в формате массива). <region_external_id> — идентификатор региона.
regional_data.<region_external_id>.delivery	Возможность курьерской доставки по указанному региону
regional_data.<region_external_id>.available	Есть ли товар в наличии в указанном регионе
regional_data.<region_external_id>.price	Цена товара в указанном регионе

Заказы (orders)

Поле для подстановки	Описание
external_id	Идентификатор заказа
status	Идентификатор статуса заказа
delivery_cost	Стоимость доставки
total_price	Общая стоимость заказа. Складывается из суммы каждой позиции в заказе и стоимости доставки.
custom_fields.<external_id поля>	Идентификатор дополнительного поля. Для числовых ID и специальных символов используйте синтаксис custom_fields('external_id')
create_time	Время создание заказа
update_time	Время обновления заказа
region.external_id	Идентификатор региона
lines	Позиции заказа (массив). Только для функции order.

Позиции заказа (lines)

Поле для подстановки	Описание
id	Идентификатор позиции
external_id	Дополнительный идентификатор позиции
custom_status_external_id	Идентификатор статуса позиции заказа
base_price_per_item	Базовая цена
final_price_of_line	Конечная цена
count	Количество товара в позиции
custom_fields.<external_id поля>	Дополнительные поля позиции заказа. Идентификатор дополнительного поля в позиции заказа. Для числовых ID и специальных символов используйте синтаксис custom_fields('external_id')
product_external_id	Идентификатор продукта в позиции
name	Название позиции
manufacturer_name	Наименование производителя товара, указанного в позиции
url	URL страницы товара, указанного в позиции, на сайте магазина
pictures	Список URL-ссылок на изображения товара, указанного в позиции (массив)
balance	Остаток товара
available	Есть ли товар, указанный в позиции, в наличии у магазина
delivery	Возможность курьерской доставки позиции заказа
barcodes	Список штрихкодов товара, указанного в позиции (массив)
categories	Список идентификаторов категорий товара, указанного в позиции (массив)

к сведению

Приоритет переопределения пользовательских полей:
(определяет значение каких полей будет применятся в первую очередь)

SKU > Продукт > Позиция заказа