Передача заказов API-ресурсом Generate event

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

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

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

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

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

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

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

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

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

• Add/update a contact.

• Add orders.

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

Примеры запроса:

• Массив без экранирования

"params": [
        {
            "name": "array",
            "value": [{"field1": "value1"}]
        }
	]

• Массив с экранированием

"params": [
		{
            "name": "escapedArray",
            "value": "[{\"field1\": \"value111\"}]"
        }
		]

•  Объект без экранирования

"params": [
		{
            "name": "object",
            "value": {"field2": "value2"}
		}
	]

• Объект с экранированием

"params": [
		{
            "name": "escapedObject",
            "value": "{\"field2\": \"value222\"}"
        }
	]

• Сложный объект с вложенностью

"params": [
		{
            "name": "complexObject",
            "value": {"json1": {"innerField1":"innerValue1"}}
        }
	]

orderCreated

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

• ${eventKey}  — ключ уникальности события, передаётся в поле externalOrderId. Используется как идентификатор заказа;
• ${orderId}  — ID события в системе; параметр нужен для работы сценария.

В качестве идентификатора контакта должен использоваться один из следующих параметров:

• ${externalCustomerId}  — внеший ID контакта;
• ${email}  — адрес электронной почты контакта;
• ${phone}  — номер телефона контакта.

Чтобы подставить значения параметров в сообщения, передавайте поля с параметрами события в виде массива.

• Обязательные поля в массиве orders: externalOrderId, totalCost, status, date, externalCustomerId / email / phone. 
• Обязательные поля в массиве items: (externalItemId, name, quantity, cost, url, imageUrl).

Пример:

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

orderUpdated

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

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

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

orderDelivered

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

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

orderCancelled

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

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