Передача заказов 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"}]
        }
	]
JSON
COPY

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

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

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

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

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

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

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

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

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"
                }
            ]
        }
    ]
}
JSON
COPY
MORE

orderUpdated

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

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

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

orderDelivered

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

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

orderCancelled

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

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