Передача замовлень 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.

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

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

Система зіставляє подію з контактом за налаштованими параметрами ідентифікації. Якщо власних параметрів не задано, використовуються стандартні назви параметрів: contactId, externalCustomerId, email і phone.

Щоб передати замовлення для контакту, якого ще немає в базі, використовуйте externalCustomerId.

Якщо контакту ще немає в базі та відомі лише його email або номер телефону, спочатку додайте контакт до бази, а потім передайте замовлення.

Події обробляються асинхронно, тому замовлення та новий контакт, якщо він створюється, можуть з'явитися в системі не одразу після запиту.

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

orderCreated

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

• ${eventKey} — ключ унікальності замовлення. Передається в поле externalOrderId. Використовується як ідентифікатор замовлення;
• ${orderId} — ID замовлення в системі; параметр потрібний для роботи сценарію.

Як ідентифікатор контакту повинен використовуватися один із таких параметрів:

• ${externalCustomerId} — зовнішній ID контакту;
• ${email} — email-адреса контакту;
• ${phone} — номер телефону контакту.

Щоб підставити значення параметрів у повідомлення, передавайте поля з параметрами події у вигляді масиву.

Інформація про замовлення у параметрах події передається у вигляді масиву params з обов’язковими полями:

• externalOrderId;
• totalCost;
• status;
• date;
• currency.

Хоча currency не завжди перевірявся в старих інтеграціях, зараз він обов'язковий — без нього запит відхиляється з помилкою currency must be specified.

Дата замовлення та дата реєстрації

У замовлення є дві дати, які можуть відрізнятися:

• дата замовлення — значення поля date із запиту;
• дата реєстрації замовлення — момент, коли система отримала подію.

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

Додатково можна вказати перелік товарів у масиві items. У цьому випадку для кожного елемента масиву обов’язково мають бути вказані такі поля:

• externalItemId;
• quantity.

Склад замовлення формує параметр items. Параметр products зберігається разом із подією як додатковий, і замовлення створюється з порожнім списком товарів.

Дата замовлення і дата події, якою воно надійшло, — різні значення, і на картці замовлення показані обидві. Дата події — це завжди час, коли подія потрапила в систему: повторна передача тієї самої події оновлює замовлення, але цю дату не змінює.

У повідомленні, яке запускає подія замовлення, дані про товар підставляються із самого замовлення: товарний фід не використовується, доки в повідомленні немає блоку, що звертається до джерела даних. Поле, яке в замовленні порожнє, лишиться порожнім і в повідомленні. Щоб показати значення, для якого в замовленні немає власного поля, наприклад артикул, передайте його в полі товару description.

Після прив'язки до контакту замовлення з'являється в розділі Замовлення.

Приклад тіла запиту:

{
  "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",
    "marketId": "Lviv_center_2",
    "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"
      }
    ]
  }
}

orderUpdated

Якщо повторно надіслати подію з тим самим externalOrderId, але зі зміненими параметрами замовлення, нові дані замінять дані попереднього запиту.

Якщо ви переходите на передавання замовлень подією, спершу оновіть історичні замовлення, а вже потім вмикайте сценарії — інакше по оновлених замовленнях підуть повідомлення.

Чому кількість замовлень не збігається з кількістю подій

У розділі Замовлення зберігається один запис на кожен externalOrderId, а в історії подій — кожна отримана системою подія. Повторне надсилання замовлення з тим самим externalOrderId оновлює наявний запис і додає ще одну подію, тому подій зазвичай більше, ніж замовлень.

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

orderDelivered

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

orderCancelled

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

Оновити вже надіслані події (наприклад, щоб додати дані для сегментації) можна, повторно надіславши Generate event v3 з тим самим externalOrderId — нові дані замінять попередні. Оновіть дані до того, як увімкнете відповідний сценарій, щоб саме оновлення не спричинило відправку повідомлень.

Оновлення історичних подій

Якщо нові поля потрібні для сегментації або сценаріїв, передайте історію повторно — як історичні події / оновлення замовлень із тими самими ідентифікаторами замовлень.

Перш ніж вмикати активні сценарії, переконайтеся, що повторне завантаження не спричинить небажаних спрацювань.