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

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

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

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

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

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

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

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

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

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

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

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

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

Прислать заказ v1/event можно только для уже существующего контакта у вас в базе. Если нужно передать заказ для нового клиента, то вам нужно предварительно импортировать этот контакт в систему с помощью:

• v1/contacts. 

• v1/orders.

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

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\"}]"
	}]
}

📌 Обратите внимание
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 и параллельно настроена интеграция с рекомендательными системами (брошенные корзины, просмотры и т.д.), то можно без дополнительных действий передавать информацию сразу в оба сервиса.

Таким образом:

• настроена сегментация ивентов

• нет необходимости передавать данные отдельно в разные сервисы

Ниже приведены типы событий для передачи определенной информации.

Пример события для передачи информации о посещаемой странице пользователем, в качестве ссылки может быть указан (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\"}"
    }
  ]
}

где:

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

где:

Для триггеров:
“Просмотр сайта с посещением категории, без посещения карточки товаров.”
“Просмотр сайта без любого посещения категории/товара.”

Для этого нужно отправить событие productCategoryViewed, в котором будет указано на какой категории находится пользователь:

{
  "eventTypeKey": "productCategoryViewed",
  "keyValue": "example@email.com",
  "params": [
    {
      "name": "phone",
      "value": "380501234567"
    },
    {
      "name": "email",
      "value": "example@email.com"
    },
    {
      "name": "category",
      "value": "{\"productCategoryId\":\"Термосы\"}"
    }
  ]
}

где:

Событие, отправляется в момент изменения корзины (с новым 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"
    }
  ]
}

где: