Передача заказов с помощью ресурса v1/event | Поддержка eSputnik

Отслеживание событий и поведения

Email

Омниканальность

Автоматизация

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

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

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

Эти ограничения отсутствуют в способе управления заказами при помощи метода Create events на основе событий. Это метод можно использовать вместо метода Add orders или в дополнение к нему.

Важно!

Заказ передаваемый при помощи Create events в ответ не возвращает идентификатор созданного заказа - orderId. Чтобы получить его, создайте заказ при помощи Add orders, после чего дополняйте и обновляйте статус заказа при помощи Create event.

Использование метода Create events для передачи заказов

Используя метод Create event для передачи событий, вы можете:

  • Передавать больше данных, чем в методе Add orders, используя дополнительные поля.

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

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

Важно!

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

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

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

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

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

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

Тип события

Описание обработки

orderCreated

Создает заказ с одним из статусов, указанном в массиве: INITIALIZED, IN_PROGRESS, DELIVERED, CANCELLED, ABANDONED_SHOPPING_CART.

orderUpdated

Обновляет заказ.

orderDelivered

Изменяет статус заказа на DELIVERED.

orderCancelled

Изменяет статус заказа на CANCELLED.

orderCreated

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

Обязательные поля для передачи данных

Пример:

{
	"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": "currency",
		"value": "UAH"
	}, {
		"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, в соответствии со стандартом ISO 8601. Пример: 2020-05-14T10:11:00.
items Товары, входящие в заказ (необязательное поле). Если данное поле используется, то необходимо указывать обязательные поля для метода orderItem. Значения 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": "currency",
"value": "UAH"
}, {
"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.

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

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

orderDelivered

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

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

orderCancelled

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

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

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

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

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

  • настроена сегментация событий,

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

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

Тип события

Описание

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

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

Тип: строка

  • 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\":[\"зеленый\"]}]}"
    }
  ]
}

где:

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: массив строк

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

Для триггеров:

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

Для этого нужно отправить событие 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": "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”

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

Тип: строка


 

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

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

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