Передача замовлень 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 можна лише для контакту, що вже є у вашій базі. Якщо потрібно передати замовлення для нового контакту, спочатку імпортуйте цей контакт до системи за допомогою одного з ресурсів:

• Add/update a contact,
• Add orders.

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

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",
    "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
• Email, EmailAddress, UserEmail, ContactEmail
• Phone, SMS, PhoneNumber
• PushToken
• ContactKey, Contactkey

Всі значення, крім email-адреси, зіставляються з урахуванням регістру.

orderUpdated

• Оновлює замовлення зі вказаним значенням externalOrderId.
• Якщо переданого замовлення немає в системі, воно все одно створюється.
• Параметри повинні мати назву, яка вказана в документації. Якщо замовлення потрібно створити, то застосовуються вимоги до orderCreated.

orderDelivered

• Змінює статус замовлення externalOrderId на значення DELIVERED.
• Якщо замовлення не існує, воно ігнорується.

📘

Примітка

Для формування RFM-таблиці та візуалізації доходу від розсилок на вкладці Звіти використовуються тільки замовлення зі статусом DELIVERED.

Виключення становлять замовлення, отримані з мобільного SDK, — в такому випадку за замовчуванням у візуалізації доходу враховуються статуси INITIALIZED та  DELIVERED. За необхідністю врахування статусів INITIALIZED можна відключити — для цього зверніться у нашу службу підтримки [email protected]

orderCancelled

• Змінює статус замовлення externalOrderId на значення CANCELLED.
• Якщо замовлення не існує, воно ігнорується.