Использование переменных маркета в сообщениях
Переменные
В маркете доступны четыре переменные:
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" |
Работа с пользовательскими полями
Для фильтрации по пользовательским полям доступно два синтаксиса:
Универсальный синтаксис (рекомендуется)
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 > Продукт > Позиция заказа