Передача заказов и активности клиентов с помощью ресурса 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 передать еще один массив или объект, он останется сериализованным (экранированным). Такие данные мы не игнорируем, но в силу того, что это будет строка, работать с ней не получится.

orderUpdated

  • Обновляет заказ с указанным значением externalOrderId.

  • Если переданный заказ не существует, он все равно создается.

  • Параметры должны быть названы в соответствии с https://esputnik.com/api/ns1_order.html. Если заказ должен быть создан, то применяются требования к orderCreated.

orderDelivered

  • Обновляет статус заказа externalOrderId на значение DELIVERED.

  • Если заказ не существует, он игнорируется.

orderCancelled

Аналогично orderDelivered обновляет статус заказа на CANCELLED.

Использование v1/event для передачи данных в рекомендательную систему

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

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

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

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

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

Тип события

Описание

productViewed

просмотр карточки товара

productCategoryViewed

просмотр категории

cartUpdated

изменение содержимого корзины

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

где:

phone

"380501234567"

Тип: строка

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

email

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

product

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

Тип: объект

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

productId

"72354"

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

Тип: строка

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

quantity   

1

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

Type: int

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

price

“754”

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

Тип: строка

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

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}]"
    },
    {
      "name": "currencyCode",
      "value": "UAH"
    },
    {
      "name": "recycleStateId",
      "value": "d59c6e6d-4123-4b0e-8c32-15f0656a8c60"
    }
  ]
}

где:

phone

“380501234567”

Тип: строка

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

email

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

products

Обязательный если корзина не пустая

Тип: массив объектов

  • Данные о товарах в корзине

productId

“72354”

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

Тип: строка

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

quantity

1

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

Тип: int

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

price

“201.95”

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

Тип: строка

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

name

“Термос”

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

Тип: строка

  • Название товара

category

“Термосы”

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

Тип: объект

  • Категория товара

discount

“180”

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

Тип: строка

  • Скидочная цена за единицу товара

someProductProperty

“[abc, bca]”
Необязательный

Type: массив строк

  • Дополнительные поля могут передаваться в этом параметре, через запятую

recycleStateId

“6F9619FF-8B86-D011-B42D-00CF4FC964FF”

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

Тип: строка


 
  • Уникальный идентификатор, связывающий события корзины и покупки

  • Может быть сгенерирован из случайных цифр и латинских букв

currencyCode

“UAH”

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

Тип: строка

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

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