Передавання замовлень за допомогою ресурсу 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, він залишиться серіалізованим (екранованим). Такі дані не ігноруються, але ви не зможете їх використовувати, оскільки вони передаються у рядку. |
orderUpdated
- Оновлює замовлення зі вказаним значенням externalOrderId.
- Якщо переданого замовлення немає в системі, воно все одно створюється.
- Параметри повинні називатися, як зазначено тут. Якщо замовлення потрібно створити, то застосовуються вимоги до orderCreated.
orderDelivered
- Змінює статус замовлення externalOrderId на значення DELIVERED.
- Якщо замовлення не існує, воно ігнорується.
orderCancelled
Змінює статус замовлення на значення CANCELED.