Передача замовлень за допомогою ресурсу v1/event | Підтримка eSputnik

Email

Омніканальність

Автоматизація

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

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

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

Ці обмеження відсутні у способі керування замовленнями за допомогою методу Create events на основі подій. Цей метод можна використовувати замість Add orders або на додаток до нього.

Важливо!

Замовлення, що передається за допомогою Create events, у відповідь не повертає ідентифікатор створеного замовлення - orderId. Щоб отримати його, створіть замовлення за допомогою Add orders, після чого доповнюйте та оновлюйте статус замовлення за допомогою Create events.

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

Використовуючи метод Create events для передачі подій, ви можете:

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

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

Важливо!

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

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

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

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

Тип події

Опис

orderCreated

Створює замовлення зі статусом, який зазначений в масиві: INITIALIZED, IN_PROGRESS, DELIVERED, CANCELLED, ABANDONED_SHOPPING_CART.

orderUpdated

Оновлює замовлення.

orderDelivered

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

orderCancelled

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

orderCreated

Для створення замовлення необхідно вказати назву параметрів саме ту, яку зазначено в документації, і заповнити обов'язкові параметри. Якщо пропустити будь-який з обов'язкових параметрів, подія проігнорується і замовлення не буде створено. Обов'язкові параметри мають спеціальну позначку "required":

Oбов'язкові поля

Приклад:

{
	"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\"}]"
	}]
}

Важливо!

Щоб подія збереглася з прив'язкою до контакту, необхідно знати, який параметр містить ідентифікатор для пошуку контакту. За замовчуванням система здійснює пошук таких параметрів, без урахування регістру: 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": "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\"}]"
    },
     {
        "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

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

Використання Create events для передачі даних у рекомендаційну систему

Якщо у вас налаштована як передача подій з програми або сайту в eSputnik, так і інтеграція з рекомендаційними системами (кинуті кошики, перегляди тощо), то використовуючи метод Create events можна без додаткових налаштувань передавати інформацію одразу в обидва сервіси.

Таким чином маємо:

  • настроєну сегментацію подій,
  • відсутність потреби передавати дані окремо до різних сервісів.

Нижче наведено типи подій для передачі певної інформації.

Тип події Опис
pageViewed Перегляд сторінки.
productViewed Перегляд картки товару.
productCategoryViewed Перегляд категорії.
cartUpdated Зміна вмісту кошика.

Приклад події для передачі інформації у вигляді посилання про відвідувану користувачем сторінку може бути вказаний (deeplinks & Universal links) при використанні мобільного додатку:

{
  "eventTypeKey": "pageViewed",
  "keyValue": "example@email.com",
  "params": [
    {
      "name": "phone",
      "value": "380501234567"
    },
    {
      "name": "email",
      "value": "example@email.com"
    },
    {
      "name": "page",
      "value": "{\"location\":\"https://example.com\"}"
    }
  ]
}

де:

phone "380501234567"
Тип: рядок
Номер телефону у міжнародному форматі.
email "example@email.com"
Тип: рядок
Email користувача.
page Обов'язковий
Тип: рядок
Адреса сторінки.
location Обов'язковий
Тип: рядок
URL сторінки або deeplink

Для якісного ранжування товарів/категорій або для відправлення тригерів за покинутими переглядами необхідно надіслати запит, в якому буде зазначено, яку картку товару наразі переглядає користувач, а також ціну та наявність цього товару. Для цього потрібно надіслати подію productViewed:

{
  "eventTypeKey": "productViewed",
  "keyValue": "example@email.com",
  "params": [
    {
      "name": "phone",
      "value": "380501234567"
    },
    {
      "name": "email",
      "value": "example@email.com"
    },
    {
      "name": "product",
      "value": "{\"productId\":\"WS01-L-Green\",\"price\":45.5,\"isInStock\":1,\"someProductProperty\":[\"зеленый\"]}]}"
    }
  ]
}

де:

phone "380501234567"
Тип: string
Номер телефону у міжнародному форматі.
email "example@email.com"
Тип: string
Email користувача.
product Обов'язковий
Тип: object
Дані товару.
productId "72354"
Обов'язковий
Тип: string
Ідентифікатор товару.
quantity 1
Обов'язковий
Type: double
Кількість товарів.
price 754.5
Обов'язковий
Тип: double
Ціна за одиницю товару.
isInStock 1
Необов'язковий
Тип: int
Відповідає за наявність товару.
Може приймати два значення:
"0" - немає в наявності
"1" - в наявності.
someProductProperty "[abc, bca]"
Необов'язковий
Type: array of strings
Додаткові поля можуть передаватися в цьому параметрі розділені комою.

Для тригерів:

  • "Перегляд сайту з відвідуванням категорії, без відвідування картки товарів."
  • “Перегляд сайту без відвідування категорії/товару.”

Для цього потрібно надіслати подію productCategoryViewed, в якій буде вказано в якій категорії знаходиться користувач:

{
  "eventTypeKey": "productCategoryViewed",
  "keyValue": "example@email.com",
  "params": [
    {
      "name": "phone",
      "value": "380501234567"
    },
    {
      "name": "email",
      "value": "example@email.com"
    },
    {
      "name": "category",
      "value": "{\"productCategoryId\":\"Термосы\"}"
    }
  ]
}

де:

phone "380501234567"
Тип: string
Номер телефону у міжнародному форматі.
email "example@email.com"
Тип: string
Email користувача.
category Обов'язковий
Тип: object
Опис категорії.
productCategoryId "72354"
Обов'язковий
Тип: string
ID категорії.

Подія відправляється в момент зміни вмісту кошика (з новим recycleStateId), наприклад, на картці товару або на сторінці категорій у разі натискання на кнопку "Купити". Якщо кошик порожній, необхідно передати порожній масив products:"[]".

Приклад запиту для події cartUpdated:

{
  "eventTypeKey": "cartUpdated",
  "keyValue": "example@email.com",
  "params": [
    {
      "name": "phone",
      "value": "380501234567"
    },
    {
      "name": "email",
      "value": "example@email.com"
    },
    {
      "name": "products",
      "value": "[{\"productId\":\"WS01-L-Green\",\"quantity\":1,\"price\":45.5}]"
    },
    {
      "name": "recycleStateId",
      "value": "d59c6e6d-4123-4b0e-8c32-15f0656a8c60"
    }
  ]
}

де:

phone "380501234567"
Тип: string
Номер телефону у міжнародному форматі.
email "example@email.com"
Тип: string
Email користувача.
products Обов'язковий, якщо кошик не пустий
Тип: array of objects
Дані про товари в кошику.
productId "72354"
Обов'язковий
Тип: string
Ідентифікатор товару.
quantity 1
Обов'язковий
Тип: double
Кількість товарів.
price 201.95
Обов'язковий
Тип: double
Ціна за одиницю товару
name "Термос"
Необов'язковий
Тип: string
Назва товару.
category "Термоси"
Необов'язковий
Тип: object
Категорія товару
descount "180"
Необов'язковий
Тип: string
Ціна зі знижкою за одиницю товару.
someProductProperty "[abc, bca]"
Необов'язковий
Type: array of strings
У цьому параметрі можуть передаватися додаткові поля, вказані через кому.
recycleStateId “6F9619FF-8B86-D011-B42D-00CF4FC964FF”
Обов'язковий
Тип: string
Унікальний ідентифікатор, що пов'язує події кошика та покупки. Його можна згенерувати з використанням випадкових цифр та латинських літер.
Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email