Передача замовлень API-ресурсом Generate event
Для передачі даних про замовлення в системі eSputnik використовується ресурс Add orders, що має низку обмежень:
- фіксовану кількість полів, регламентованих специфікацією,
- неможливість додавати власні поля,
- вміст замовлень не можна використовувати для створення сегментів.
Ці обмеження відсутні у способі керування замовленнями за допомогою методу Generate event на основі подій. Цей метод можна використовувати замість Add orders
або на додаток до нього.
ВажливоЗамовлення, що передається за допомогою
Generate event
, у відповідь не повертає ідентифікатор створеного замовлення - orderId. Щоб отримати його, створіть замовлення за допомогоюAdd orders
, після чого доповнюйте та оновлюйте статус замовлення за допомогоюGenerate event
.
Використання Generate event для передачі замовлень
Використовуючи метод Generate event
для передачі подій, ви можете:
- Передавати більше даних, ніж у методі
Add orders
, використовуючи додаткові поля. - Підключати сегментацію за подіями та їх параметрами. Наприклад, відсортувати клієнтів, які купували певний товар упродовж тижня. Докладніше про такі можливості читайте у статті Як використовувати сегментацію за подіями.
- Розширювати/отримувати RFM-сегментацію на замовлення без додаткового підключення
Add orders
.

ВажливоЩоб подія збереглася з прив'язкою до контакта, необхідно знати, який параметр у події містить ідентифікатор, за яким можна знайти контакт. А також яке саме поле контакта використовується в якості ідентифікатора.
Якщо ідентифікатор контакта не заданий у події, система за замовчуванням шукає наступні імена параметрів події в зазначеному на вкладці Події порядку. На цій же вкладці ви можете задати кастомний параметр для прив'язки події до контакту.

Надіслати замовлення Generate event
можна лише для контакту, що вже є у вашій базі. Якщо потрібно передати замовлення для нового контакту, спочатку імпортуйте цей контакт до системи за допомогою одного з ресурсів:
Щоб надіслати замовлення, потрібно вказати тип події. Виберіть тип із таблиці нижче залежно від статусу замовлення.
Тип події | Опис |
---|---|
orderCreated | Створює замовлення зі статусом, який зазначений в масиві: INITIALIZED , IN_PROGRESS , DELIVERED , CANCELLED , ABANDONED_SHOPPING_CART . |
orderUpdated | Оновлює замовлення. |
orderDelivered | Змінює статус замовлення на DELIVERED . |
orderCancelled | Змінює статус замовлення на CANCELLED . |
orderCreated
Для створення замовлення необхідно вказати назву параметрів саме ту, яку зазначено в документації, і заповнити обов'язкові параметри. Якщо пропустити будь-який з обов'язкових параметрів, подія проігнорується і замовлення не буде створено.
${eventKey}
— ключ унікальності замовлення. Передається в поле externalOrderId. Використовується як ідентифікатор замовлення;${orderId}
— ID замовлення в системі; параметр потрібний для роботи сценарію.
Як ідентифікатор контакту повинен використовуватися один із таких параметрів:
${externalCustomerId}
— зовнішній ID контакту;${email}
— email-адреса контакту;${phone}
— номер телефону контакту.
Щоб підставити значення параметрів у повідомлення, передавайте поля з параметрами події у вигляді масиву.
Інформація про замовлення у параметрах події передається у вигляді масиву params
з обов’язковими полями:
- externalOrderId;
- totalCost;
- status;
- date.
Додатково можна вказати перелік товарів у масиві items
. У цьому випадку для кожного елемента масиву
обов’язково мають бути вказані такі поля:
- externalItemId;
- quantity.
ПриміткаЦіна переданих у замовленні товарів повинна співпадати з значенням
totalCost
(загальна сума замовлення). Якщо клієнт купляє товар зі знижкою, вона повинна враховуватись у поліitems.cost
для кожного товару.
Приклад тіла запиту:
{
"eventTypeKey": "orderCreated",
"keyValue": "380501234567",
"params": {
"phone": "380501234567",
"externalOrderId": "12345679",
"externalCustomerId": "AV13760",
"totalCost": 258,
"status": "INITIALIZED",
"date": "2020-05-14T10:11:00+02:00",
"currency": "UAH",
"items": [
{
"externalItemId": "200600",
"name": "Super Device",
"category": "devices",
"quantity": 2,
"cost": 129,
"url": "http://example.com/item/200600",
"imageUrl": "http://example.com/item/200600/image.png",
"description": "High quality"
}
]
}
}
ВажливоЩоб подія збереглася з прив'язкою до контакту, необхідно знати, який параметр містить ідентифікатор для пошуку контакту. За замовчуванням система здійснює пошук таких параметрів, без урахування регістру:
ContactId
,Contactid
EmailAddress
,UserEmail
,ContactEmail
Phone
,SMS
,PhoneNumber
PushToken
ContactKey
,Contactkey
Всі значення, крім email-адреси, зіставляються з урахуванням регістру.
Назва поля | Опис |
---|---|
status | Може бути одним з наступних: INITIALIZED , INPROGRESS , DELIVERED , CANCELLED , ABANDONEDSHOPPINGCART . |
date | Формат передавання дати YYYY-MM-DDThh:mm:ss±hh:mm . Наприклад: 2020-05-14T10:11:00+02:00 , де +02:00 зміщення часового поясу відносно UTC. Враховуйте, що деякі країни використовують перехід між літнім і зимовим часом. |
items | Товари, що входять до замовлення (необов'язково, але при використанні частина полів є обов’язковою). Значення items слід передавати у вигляді рядка JSON. Підтримується вкладеність до другого рівня включно. Це означає, що якщо ви передасте ще один масив або об’єкт у масив items , він залишиться серіалізованим (екранованим). Такі дані не ігноруються, але ви не зможете їх використовувати, оскільки вони передаються у рядку. |
orderUpdated
- Оновлює замовлення зі вказаним значенням
externalOrderId
. - Якщо переданого замовлення немає в системі, воно все одно створюється.
- Параметри повинні мати назву, яка вказана в документації. Якщо замовлення потрібно створити, то застосовуються вимоги до
orderCreated
.
orderDelivered
- Змінює статус замовлення
externalOrderId
на значенняDELIVERED
. - Якщо замовлення не існує, воно ігнорується.
ПриміткаДля формування RFM-таблиці та візуалізації доходу від розсилок на вкладці Звіти використовуються тільки замовлення зі статусом
DELIVERED
.Виключення становлять замовлення, отримані з мобільного SDK, — в такому випадку за замовчуванням у візуалізації доходу враховуються статуси
INITIALIZED
таDELIVERED
. За необхідністю врахування статусівINITIALIZED
можна відключити — для цього зверніться у нашу службу підтримки [email protected]
orderCancelled
- Змінює статус замовлення
externalOrderId
на значенняCANCELLED
. - Якщо замовлення не існує, воно ігнорується.
Updated 13 days ago