Передача заказов и активности клиентов с помощью ресурса v1/event
Для передачи данных о заказе используется ресурс v1/orders, который имеет ряд ограничений:
-
фиксированное число полей, регламентированных спецификацией;
-
нет возможности добавлять пользовательские поля;
-
содержимое заказов нельзя использовать для построения сегментов.
Эти ограничения может решить предлагаемый нами способ управления заказами при помощи ресурса v1/event на основе событий. Событиями можно как заменить полностью ресурс v1/orders, так и дополнить его.
Важно!
Заказ передаваемый при помощи v1/event в ответ не возвращает идентификатор созданного заказа orderId. Для его получения создать заказ можно при помощи v1/orders, а дополнять и обновлять статус при помощи v1/event.
Использование v1/event для передачи заказов
Таким образом, у вас появляется возможность:
-
Передавать больше данных, чем это ранее было возможно в методе v1/orders, с помощью дополнительных полей.
-
Подключать сегментацию по событиям и их параметрам. Например, отсортировать тех, кто покупал определенный товар в течение недели. Подробнее о таких возможностях – тут.
-
Расширять/ получать RFM-сегментацию по заказам без дополнительного подключение v1/orders.
Важно!
Для сохранения заказов в системе используется настройка сегментации событий, так как в событии должен быть идентификатор контакта. Для определения контакта в событии используются либо настроенные параметры, либо параметры по умолчанию.
Например, в настройках события можно указать идентификацию по уникальному токену. Пока не будет передан такой параметр в событии, заказ не сохранится.
Если не указать эти параметры в настройках, то будут искаться параметры по умолчанию (email, phone и т. п.).
Прислать заказ v1/event можно только для уже существующего контакта у вас в базе. Если нужно передать заказ для нового клиента, то вам нужно предварительно импортировать этот контакт в систему с помощью:
-
v1/contacts.
-
v1/orders.
Для отправки события по заказу нужно указать тип события, такой как указано ниже в таблице, в зависимости от того, нужно вам создать заказ или обновить его статус.
Тип события |
Описание обработки |
orderCreated |
Создает заказ в состоянии, указанном в массиве. |
orderUpdated |
Обновляет заказ. |
orderDelivered |
Изменяет статус заказа на DELIVERED |
orderCancelled |
Изменяет статус заказа на CANCELLED |
orderCreated
Для создания заказа необходимо назвать параметры в точности так, как в https://esputnik.com/api/ns1_order.html, и заполнить обязательные параметры. Если какой-либо из обязательных параметров пропущен, событие игнорируется и заказ не создается. Обязательные параметры помечены соответствующей надписью в приведенном списке полей.
Пример:
{
"eventTypeKey": "orderCreated",
"keyValue": "380501234567",
"params": [{
"name": "phone",
"value": "380501234567"
}, {
"name": "externalOrderId",
"value": "12345679"
}, {
"name": "externalCustomerId",
"value": "AV13760"
}, {
"name": "totalCost",
"value": "258.0"
}, {
"name": "status",
"value": "INITIALIZED"
}, {
"name": "date",
"value": "2020-05-14T10:11:00"
}, {
"name": "items",
"value": "[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]"
}]
}
Важно!
Чтобы событие сохранилось с привязкой к контакту, необходимо знать, какой параметр в событии содержит идентификатор, по которому можно найти контакт, система по умолчанию ищет следующие названия параметров события, без учета регистра: ContactId, Contact_id, Email, EmailAddress, UserEmail, ContactEmail, Phone, SMS, PhoneNumber, PushToken, ContactKey, Contact_key. Все значения, кроме email-адреса, сравниваются с учетом регистра.
Имя поля |
Описание |
status |
Может быть одним из INITIALIZED, IN_PROGRESS, DELIVERED, CANCELLED, ABANDONED_SHOPPING_CART. |
date | Формат передачи даты YYYY-MM-ddTHH:mm:ss, например: 2020-05-14T10:11:00. |
items | Продукты, входящие в заказ (не обязательно), можно создать заказ и без items, в противном случае часть полей обязательны, подробнее тут. Значения items передавать json строкой. Поддерживается вложенность до второго уровня включительно. Это значит, что если в массив items передать еще один массив или объект, он останется сериализованным (экранированным). Такие данные мы не игнорируем, но в силу того, что это будет строка, работать с ней не получится. |
📌 Обратите внимание
items используется только для передачи массива товаров в раздел заказы и его нельзя использовать для вывода в письмах. Для передачи информации о товаре в письма, необходимо использовать products, как в примере ниже
{
"eventTypeKey": "orderCreated",
"keyValue": "380501234567",
"params": [{
"name": "phone",
"value": "380501234567"
}, {
"name": "externalOrderId",
"value": "12345679"
}, {
"name": "externalCustomerId",
"value": "AV13760"
}, {
"name": "totalCost",
"value": "258.0"
}, {
"name": "status",
"value": "INITIALIZED"
}, {
"name": "date",
"value": "2020-05-14T10:11:00"
}, {
"name": "items",
"value": "[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]"
},
{
"name": "products",
"value": "{\"array\":[{\"externalItemId\":\"200600\",\"name\":\"Super Device\",\"category\":\"devices\",\"quantity\":1,\"cost\":990,\"url\":\"http:\/\/example.com\/item\/200600\",\"imageUrl\":\"http:\/\/example.com\/item\/200600\/image.png\",\"description\":\"High quality\"}]}"
}]
}
orderUpdated
-
Обновляет заказ с указанным значением externalOrderId.
-
Если переданный заказ не существует, он все равно создается.
-
Параметры должны быть названы в соответствии с https://esputnik.com/api/ns1_order.html. Если заказ должен быть создан, то применяются требования к orderCreated.
orderDelivered
-
Обновляет статус заказа externalOrderId на значение DELIVERED.
-
Если заказ не существует, он игнорируется.
orderCancelled
Аналогично orderDelivered обновляет статус заказа на CANCELLED.
Использование v1/event для передачи данных в рекомендательную систему
Если у вас настроена передача ивентов с приложения или сайта в eSputnik и параллельно настроена интеграция с рекомендательными системами (брошенные корзины, просмотры и т.д.), то можно без дополнительных действий передавать информацию сразу в оба сервиса.
Таким образом:
-
настроена сегментация ивентов
-
нет необходимости передавать данные отдельно в разные сервисы
Ниже приведены типы событий для передачи определенной информации.
Тип события |
Описание |
pageViewed |
просмотр страницы |
productViewed |
просмотр карточки товара |
productCategoryViewed |
просмотр категории |
cartUpdated |
изменение содержимого корзины |
Пример события для передачи информации о посещаемой странице пользователем, в качестве ссылки может быть указан (deeplinks & Universal links) при использовании мобильного приложения:
{
"eventTypeKey": "pageViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "380501234567"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "page",
"value": "{\"location\":\"https://example.com\"}"
}
]
}
где:
phone |
"380501234567"
Тип: строка |
|
|
"example@email.com" Тип: строка |
|
page |
Обязательный Тип: строка |
|
location |
Обязательный Тип: строка |
|
Для качественного ранжирования товаров/категорий или для отправки триггеров по брошенным просмотрам необходимо отправить запрос, в котором будет указано, какую карточку товара в данный момент просматривает пользователь, а также его цену и наличие этого товара. Для этого нужно отправить событие productViewed:
{
"eventTypeKey": "productViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "380501234567"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "product",
"value": "{\"productId\":\"WS01-L-Green\",\"price\":45.5,\"isInStock\":1,\"someProductProperty\":[\"зеленый\"]}]}"
},
{
"name": "currencyCode",
"value": "UAH"
}
]
}
где:
phone |
"380501234567"
Тип: строка |
|
|
"example@email.com" Тип: строка |
|
product |
Обязательный Тип: объект |
|
productId |
"72354" Обязательный Тип: строка |
|
quantity |
1 Обязательный Type: double |
|
price |
754.5 Обязательный Тип: double |
|
isInStock |
1 Необязательный Тип: int |
|
someProductProperty |
“[abc, bca]” Type: массив строк |
|
currencyCode |
“UAH” Необязательный Тип: строка |
|
Для триггеров:
“Просмотр сайта с посещением категории, без посещения карточки товаров.”
“Просмотр сайта без любого посещения категории/товара.”
Для этого нужно отправить событие productCategoryViewed, в котором будет указано на какой категории находится пользователь:
{
"eventTypeKey": "productCategoryViewed",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "380501234567"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "category",
"value": "{\"productCategoryId\":\"Термосы\"}"
}
]
}
где:
phone |
“380501234567”
Тип: строка |
|
|
"example@email.com" Тип: строка |
|
category |
Обязательный Тип: объект |
|
productCategoryId |
“72354” Обязательный Тип: строка |
|
Событие, отправляется в момент изменения корзины (с новым recycleStateId), например на карточке товара или странице категорий по кнопке купить. Если корзина пустая, нужно передать пустой массив products:"[]".
Пример запроса для события cartUpdated
{
"eventTypeKey": "cartUpdated",
"keyValue": "example@email.com",
"params": [
{
"name": "phone",
"value": "380501234567"
},
{
"name": "email",
"value": "example@email.com"
},
{
"name": "products",
"value": "[{\"productId\":\"WS01-L-Green\",\"quantity\":1,\"price\":45.5}]"
},
{
"name": "currencyCode",
"value": "UAH"
},
{
"name": "recycleStateId",
"value": "d59c6e6d-4123-4b0e-8c32-15f0656a8c60"
}
]
}
где:
phone |
“380501234567”
Тип: строка |
|
|
"example@email.com" Тип: строка |
|
products |
Обязательный если корзина не пустая Тип: массив объектов |
|
productId |
“72354” Обязательный Тип: строка |
|
quantity |
1 Обязательный Тип: double |
|
price |
201.95 Обязательный Тип: double |
|
name |
“Термос” Необязательный Тип: строка |
|
category |
“Термосы” Необязательный Тип: объект |
|
discount |
“180” Необязательный Тип: строка |
|
someProductProperty |
“[abc, bca]” Type: массив строк |
|
recycleStateId |
“6F9619FF-8B86-D011-B42D-00CF4FC964FF” Обязательный Тип: строка |
|
currencyCode |
“UAH” Необязательный Тип: строка |
|