Передавання замовлень за допомогою ресурсу v1/event

Для передачі даних про замовлення в системі eSputnik використовується ресурс v1/orders, що має низку обмежень:

фіксовану кількість полів, регламентованих специфікацією;
неможливість додавати власні поля;
вміст замовлень не можна використовувати для створення сегментів.

Ви можете уникнути їх за допомогою ресурсу v1/event для керування замовленнями через події. Використовуйте його, щоб замінити або доповнити ресурс v1/orders.

Важливо!

При передачі замовлення за допомогою v1/event у відповідь не повертається ідентифікатор створеного замовлення orderId. Для його отримання створити замовлення можна за допомогою v1/orders, а доповнювати і оновлювати статус за допомогою v1/event.

Використання v1/event для передачі замовлень

Завдяки v1/event ви матимете змогу:

передавати більше даних, ніж методом v1/orders, за допомогою додаткових полів;
підключати сегментацію за подіями та їхніми параметрами. Наприклад, відсортувати контакти, які придбали певний товар протягом тижня;
розширювати/отримувати RFM-сегментацію за замовленнями без додаткового залучення v1/orders.

сегментація за подіями

Важливо!

Щоб зберегти замовлення в системі, потрібно налаштувати сегментацію за подіями, оскільки подія містить ідентифікатор контакта. Для визначення контакта в події використовуються або налаштовані параметри, або параметри за замовчуванням.

налаштування відповідності

Надіслати замовлення v1/event можна лише для контакта, що вже є у вашій базі. Якщо потрібно передати замовлення для нового контакта, спочатку імпортуйте цей контакт до системи за допомогою v1/contacts або v1/orders.

Щоб надіслати замовлення, потрібно вказати тип події. Виберіть тип із таблиці нижче залежно від статусу замовлення.

Тип події	Опис
orderCreated	Створює замовлення зі статусом, який зазначено в масиві.
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": "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 слід передавати у вигляді рядка 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": "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

Змінює статус замовлення на значення CANCELLED.