Передача заказов и активности клиентов с помощью ресурса v1/event 

Для передачи данных о заказе используется ресурс v1/orders, который имеет ряд ограничений:

  • фиксированное число полей, регламентированных спецификацией;

  • нет возможности добавлять пользовательские поля;

  • содержимое заказов нельзя использовать для построения сегментов.

Ресурс /v1/orders

Эти ограничения может решить предлагаемый нами способ управления заказами при помощи ресурса v1/event на основе событий. Событиями можно как заменить полностью ресурс v1/orders, так и дополнить его.

Важно!

Заказ передаваемый при помощи v1/event в ответ не возвращает идентификатор созданного заказа orderId. Для его получения создать заказ можно при помощи v1/orders, а дополнять и обновлять статус при помощи v1/event.

Использование v1/event для передачи заказов

Таким образом, у вас появляется возможность:

  • Передавать больше данных, чем это ранее было возможно в методе v1/orders, с помощью дополнительных полей.

  • Подключать сегментацию по событиям и их параметрам. Например, отсортировать тех, кто покупал определенный товар в течение недели. Подробнее о таких возможностях – тут.

  • Расширять/ получать RFM-сегментацию по заказам без дополнительного подключение v1/orders. 

Важно!

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

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

Если не указать эти параметры в настройках, то будут искаться параметры по умолчанию (email, phone и т. п.).

Передача событий в eSputnik

Прислать заказ 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"

Тип: строка

  • Номер телефона в международном формате

email

"example@email.com"
Тип: строка
  • Email пользователя

page

Обязательный

Тип: строка

  • location

location

Обязательный

Тип: строка

  • URL страницы или deeplink

Для качественного ранжирования товаров/категорий или для отправки триггеров по брошенным просмотрам необходимо отправить запрос, в котором будет указано, какую карточку товара в данный момент просматривает  пользователь, а также его цену и наличие этого товара. Для этого нужно отправить событие 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"

Тип: строка

  • Номер телефона в международном формате

email

"example@email.com"
Тип: строка
  • Email пользователя

product

Обязательный

Тип: объект

  • Данные товара

productId

"72354"

Обязательный

Тип: строка

  • Идентификатор товара

quantity   

1

Обязательный

Type: double

  • Количество товаров

price

754.5

Обязательный

Тип: double

  • Цена за единицу товара

isInStock

1

Необязательный

Тип: int

  • Отвечает за наличие товара

  • Параметр может принимать два значения:

    • “0” - товар не в наличии

    • “1” - товар в наличии

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”

Тип: строка

  • Номер телефона в международном формате

email

"example@email.com"
Тип: строка
  • Email пользователя

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”

Тип: строка

  • Номер телефона в международном формате

email

"example@email.com"
Тип: строка
  • Email пользователя

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”

Необязательный

Тип: строка

  • Обозначение денежной валюты

Остались вопросы?
Специалисты обязательно ответят и помогут решить вашу проблему!
Обратный звонок
Оставьте заявку – и наш специалист свяжется с вами в рабочее время.
Отправить заявку
Консультация в чате
Готовы к вашим вопросам!
Написать в чат
Электронная почта
Напишите в службу поддержки eSputnik.
Отправить email