Руководство: как отправить письмо подтверждения заказа

Этот гайд покажет алгоритм работы в маркете Altcraft Platform.

В качестве примера представим, что у нас есть интернет-магазин смартфонов. Покупатель заходит на сайт, добавляет товар в корзину и оформляет заказ. Наша задача — отправить ему письмо подверждения заказа, где будет указан номер заказа и сумма к оплате.

В инструкции описаны следующие шаги:

Создание канала продаж и точек контакта
Импорт данных о продуктах и SKU с помощью yml файла
Настройка API-запроса для добавления данных заказа в маркет
Создание шаблона и подстановка данных заказа с помощью переменных
Настройка триггерной рассылки

Шаг 1. Настройка канала продаж

Работа в маркете начинается с создания канала продаж. Канал определяет базу профилей и точки контакта.

База профилей — это покупатели, которые делают заказы в определенном канале. Необходимо импортировать их данные в новую или существующую базу. Для этого воспользуйтесь импортом из файла или через API.

Точка контакта — это площадка или инструмент, с помощью которого вы продаете клиенту товары или услуги (сайт, магазин, постамат, отдельный терминал, соцсеть, call-центр и др.). Точка контакта связывает канал продаж и заказ.

Чтобы создать канал, в главном меню перейдите в раздел Маркет —> Настройки. На вкладке Каналы продаж создайте новый канал. Укажите:

название канала
дополнительный идентификатор
базу профилей
тип канала: онлайн или ритейл

Далее сохраните канал и снова перейдите в его настройку. Создайте точки контакта.

Обратите внимание, каждая точка может быть привязана только к одному каналу. Идентификатор точки контакта будет использоваться в API-запросе для импорта заказа.

Шаг 2. Загрузка в платформу данных о товарах

Товары в Маркете представлены двумя сущностями: продукты и SKU.

подсказка

Продукт — это товар или услуга для продажи. SKU — это модификатор продукта, т.е. группа товаров, которая выделяется в одном продукте по некоторым параметрам (цвет, размер, вес, модель, комплектация и т.д.).

SKU привязывается к определенному продукту и не может существовать без него. Например, Apple iPhone 12 — это продукт, а Apple iPhone 12 128GB и Apple iPhone 12 256GB — это его SKU.

Добавить данные о товарах в платформу можно тремя способами:

Давайте импортируем товары из файла. Для этого вам необходимо подготовить файл в формате yml.

подсказка

Если возникнут вопросы по импорту, читайте подробную инструкцию.

Ниже показаны примеры yml-файлов:

Продукт

Файл с таким содержимым добавит в маркет два продукта: Apple iPhone 12 и Xiaomi 12X.

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2017-02-05 17:22">
    <shop>
    <name>BestSeller</name>
    <company>Tne Best inc.</company>
    <url>http://best.seller.ru</url>
    <categories>
      <category id="10">Смартфоны</category>
      <category id="101" parentId="10">Apple</category>
      <category id="102" parentId="10">Xiaomi</category>
    </categories>
    <offers>
      <offer id="iphone12" available="true">
        <name>Apple iPhone 12</name>
        <vendor>Apple</vendor>
        <url>http://best.seller.ru/product_page.asp?pid=12348</url>
        <price>83990</price>
        <oldprice>89990</oldprice>
        <currencyId>RUB</currencyId>
        <categoryId>101</categoryId>
        <picture>https://example.com/img/apple_phone.png</picture>
        <delivery>true</delivery>
        <manufacturer_warranty>true</manufacturer_warranty>
        <barcode>0156789012</barcode>
	  </offer>
      <offer id="xiaomi12" available="true">
		<name>Xiaomi 12X</name>
        <vendor>Xiaomi</vendor>
        <url>http://best.seller.ru/product_page.asp?pid=12345</url>
        <price>62990</price>
        <oldprice>69990</oldprice>
        <currencyId>RUB</currencyId>
        <categoryId>102</categoryId>
        <picture>https://example.com/img/xiaomi_phone.png</picture>
        <delivery>true</delivery>
        <manufacturer_warranty>true</manufacturer_warranty>
        <barcode>0123456789379</barcode>
	  </offer>
    </offers>
  </shop>
</yml_catalog>

SKU

Файл добавит два SKU для продукта Apple iPhone 12: Apple iPhone 12 128GB и Apple iPhone 12 256GB.

<?xml version="1.0" encoding="UTF-8"?>
<yml_catalog date="2017-02-05 17:22">
    <shop>
    <name>BestSeller</name>
    <company>Tne Best inc.</company>
    <url>http://best.seller.ru</url>
    <offers>
      <offer id="apple12_128gb" group_id="iphone12" available="true">
        <name>Apple iPhone 12 128GB</name>
        <vendor>Apple</vendor>
        <url>http://best.seller.ru/product_page.asp?pid=12358</url>
        <price>71990</price>
        <oldprice>72990</oldprice>
        <currencyId>RUB</currencyId>
        <categoryId>101</categoryId>
        <picture>https://example.com/img/apple_phone_128.png</picture>
        <delivery>true</delivery>
        <manufacturer_warranty>true</manufacturer_warranty>
        <barcode>0156789012</barcode>
	  </offer>
      <offer id="apple12_256gb" group_id="iphone12" available="true">
		<name>Apple iPhone 12 256GB</name>
        <vendor>Apple</vendor>
        <url>http://best.seller.ru/product_page.asp?pid=12359</url>
        <price>83990</price>
        <oldprice>89990</oldprice>
        <currencyId>RUB</currencyId>
        <categoryId>102</categoryId>
        <picture>https://example.com/img/apple_phone_256.png</picture>
        <delivery>true</delivery>
        <manufacturer_warranty>true</manufacturer_warranty>
        <barcode>0156789012</barcode>
	  </offer>
    </offers>
  </shop>
</yml_catalog>

подсказка

Список всех продуктов и SKU хранится в элементе offers. Один продукт или SKU записывается в отдельном элементе offer.

Для элемента offer указывается атрибут id , уникальный для каждого товара.

Cтруктура yml файла для продукта и SKU практически не отличается. Единственное отличие — при импорте SKU для элемента offer указывается не только id, но также group_id – идентификатор продукта.

Обратите внимание, SKU – это различные вариации одного продукта, поэтому значение атрибута group_id должно быть одинаковым для всех SKU одного продукта.

Чтобы импортировать файл со списком продуктов, перейдите в раздел Маркет —> Продукты. Нажмите на иконку в верхней панели, а затем выберите, что именно хотите импортировать — продукт.

Кликните на область загрузки и выберите файл на своем устройстве:

Запустите процесс импорта, нажав кнопку "Импортировать" в верхней панели.

Затем импортируйте SKU, повторив все действия, описанные в этом пункте.

Шаг 3. Настройка API запроса на добавление заказа

Когда посетитель интернет-магазина оформит заказ, необходимо отправить API-запрос в платформу с данными о заказе.

URL-адрес

Метод: POST

https://example.com/api/v1.1/market/orders/import

Параметры запроса

Параметр	Тип	Пример	Обязательный	Описание
token	string	"abcdefghijklmnqrstuvwxyz"	Да	API-токен. Убедитесь, что для токена доступны роли, позволяющие работать с маркетом.
data	array of objects	[ { ... } ]	Да	Данные о заказе. Подробнее.
Объект data
external_id	string	"1234001"	Да	Идентификатор заказа
matching	string	"email"		Режим поиска подписчика. По умолчанию – email. Для каждого типа матчинга в теле запроса необходимо передавать определенные поля. Подробнее об этих полях можно узнать здесь.
endpoint	string	"website"	Да	Идентификатор точки продажи
status	string	"new" "delivered" "paid" "canceled" "part_refunded"	Да	Идентификатор статуса заказа
total_price	string	"71990"	Да	Общая стоимость заказа. Складывается из суммы каждой позиции в заказе и стоимости доставки.
currency	string	"RUB"	Да	Валюта, в которой указана стоимость заказа.
create_time	string	"2022-04-29T12:48:23Z"	Нет	Время создания заказа
update_time	string	"2022-04-29T12:48:23Z"	Нет	Время обновления заказа
lines	array	[ { ... } ]	Да	Данные о позициях заказа. Минимум одна позиция.
Объект lines
external_id	string	"line_01"	Да	Идентификатор позиции
product	string	"iphone12"	Не должен присутствовать в запросе, если задан `sku`	Идентификатор продукта
sku	string	"apple12_128gb"	Не должен присутствовать в запросе, если задан `product`	Идентификатор SKU
base_price_per_item	string	"71990"	Да	Базовая цена
min_price_per_item	string	"71990"	Да	Минимальная цена
final_price_per_item	string	"71990"	Да	Конечная цена
count	int	1	Да	Количество товара в позиции

Пример запроса

{
  "token": "abcdefghijklmnqrstuvwxyz",
  "data": [
    {
      "external_id": "1234001",
      "matching": "email",
      "email": "johndoe@example.com",
      "endpoint": "website",
      "status": "new",
      "total_price": "71990",
      "create_time": "2022-04-29T12:48:23Z",
      "update_time": "2022-04-29T12:48:23Z",
      "currency": "RUB",
      "lines": [
        {
          "external_id": "line_01",
          "product": "iphone12",
          "base_price_per_item": "71990",
          "min_price_per_item": "71990",
          "final_price_per_item": "71990",
          "count": 1
        }
      ]
    }
  ]
}

Пример ответа

{
  "error": 0,
  "error_text": "",
  "result": [
    {
      "error": 0,
      "external_id": "1234000"
    }
  ]
}

Возвращаемые параметры

Параметр	Тип	Описание
error	int	Код ошибки
error_text	string	Текст ошибки
result	array	Идентификаторы заказов, которые были успешно импортированы

Шаг 4. Создание шаблона сообщения

Перейдите в раздел Шаблоны. Добавьте новый шаблон для email канала.

Чтобы использовать информацию о заказе в рассылке, необходимо добавить переменные маркета в шаблон письма. Для этого в редакторе нажмите </>. В списке выберите "Маркет" и вставьте переменную "Заказы".

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

Нам надо добавить в письмо только информацию о последнем заказе со статусом "Новый". Для этого потребуется изменить аргументы функции:

{orders("order.status == '1'" 1 "create_time" "desc")}

Функция состоит из четырех аргументов:

Аргумент	Пример	Описание
Фильтр	`"order.status == '1'"`	Функция выберет только те заказы, которые соответствуют условию "статус заказа новый".
Лимит	`1`	Функция выберет только первый элемент в списке заказов.
Поле для сортировки	`"create_time"`	Выбранные элементы будут отсортированы по полю "create_time" (время создания заказа).
Направление сортировки	`"desc"` `"asc"`	Элементы будут отсортированы по убыванию значения в поле "create_time".

Функция orders получит массив заказов. В данном случае это будет массив с одним элементом. Используйте цикл, чтобы перебрать массив.

В шаблоне письма подставьте 2 переменные:

$el.external_id — дополнительный идентификатор заказа.
$el.total_price — общая сумма заказа.

{for $index $el = orders("order.status == '1'" 1 "create_time" "desc")}
  Спасибо! Ваш заказ №{$el.external_id} подтвержден.
  К оплате: {$el.total_price}
{else}
  if empty array
{end}

подсказка

Подробнее о работе с переменными маркета написано в этой статье. Там вы найдете информацию о полях, которые можно использовать в фильтре или подставлять в шаблон.

Шаг 5. Настройка триггерной рассылки

Откройте раздел Рассылки → Триггеры. Создайте новую рассылку. Не забудьте её активировать.

Выберите email-канал и добавьте нужный шаблон сообщения. На вкладке Триггер укажите:

Тип события: "При изменении заказа" —> "Добавление заказа". Триггер сработает, как только в маркет будет добавлен новый заказ.
Канал продаж: в этом канале должна быть указана база профилей, где находятся данные покупателей вашего интернет-магазина.
Статус заказа: "Новый". Триггер сработает, если в маркет будет добавлен заказ со статусом "новый".

Нажмите Готово и сохраните рассылку.

подсказка

Чтобы протестировать работу триггера, вы можете добавить заказ вручную.

Шаг 1. Настройка канала продаж​

Шаг 2. Загрузка в платформу данных о товарах​

Продукт​

SKU​

Шаг 3. Настройка API запроса на добавление заказа​

URL-адрес​

Параметры запроса​

Пример запроса​

Пример ответа​

Возвращаемые параметры​

Шаг 4. Создание шаблона сообщения​

Шаг 5. Настройка триггерной рассылки​

Шаг 1. Настройка канала продаж

Шаг 2. Загрузка в платформу данных о товарах

Продукт

SKU

Шаг 3. Настройка API запроса на добавление заказа

URL-адрес

Параметры запроса

Пример запроса

Пример ответа

Возвращаемые параметры

Шаг 4. Создание шаблона сообщения

Шаг 5. Настройка триггерной рассылки