Передавання замовлень API-ресурсом Add orders

Для передавання замовлень необхідно налаштувати виклик спеціального API-ресурсу Add orders. У запиті можна передати до 1000 замовлень.

Кожного разу, коли ви передаєте замовлення API-ресурсом, у системі створюється подія, яка може запускати сценарій. Для кожного статусу замовлення створюється відповідний тип події, що дозволяє вам налаштувати окремі тригери.

Видалення та об'єднання замовлень

Видалити чи об'єднати замовлення неможливо. Тому дублікат, переданий з іншим externalOrderId, залишиться в акаунті й спотворюватиме RFM-аналіз та рекомендаційні алгоритми. Щоб виправити замовлення, передайте його ще раз із тим самим externalOrderId.

До якого контакту прив'язується замовлення

Коли замовлення з певним externalCustomerId надходить уперше, система зберігає прив'язку до контакту окремо від зовнішнього ID самого контакту. Наступні замовлення з тим самим externalCustomerId потраплять до того самого контакту, навіть якщо це значення вже належить іншому, і email чи телефон у новому замовленні цього не змінять.

Назви подій

Назви подій складаються з двох частин: зі слова order і статусу замовлення, наприклад: orderINITIALIZED, orderIN_PROGRESS, orderDELIVERED, orderCANCELLED, orderABANDONED_SHOPPING_CART.

Щоб переглянути створені події, перейдіть до розділу Тригери → Історія подій:

Параметри подій

Кожна подія містить обов'язкові параметри та може містити додаткові параметри:

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

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

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

Не плутайте externalCustomerId з externalOrderId: externalCustomerId — це ідентифікатор контакту у вашій системі, а не ідентифікатор замовлення. Для унікальності самого замовлення використовується externalOrderId.

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

• Обов'язкові поля у масиві orders: externalOrderId, totalCost, status, date, currency.
• Обов'язкові поля у масиві items: externalItemId, quantity.

Значення externalItemId обмежене 50 символами. Довше значення не зберігається, і замовлення не створюється.

Суми в totalCost та items.cost передавайте числами з крапкою як десятковим роздільником.

Ціна переданих у замовленні товарів повинна співпадати з значенням totalCost (загальна сума замовлення). Якщо клієнт купляє товар зі знижкою, вона повинна враховуватись у полі items.cost для кожного товару. Це важливо і для сегментації: умова за сумою замовлень підсумовує вартість позицій замовлення, а не бере значення totalCost. Якщо ці числа не збігаються, група будується за сумою позицій.

Масив з товарами items можна не передавати, якщо в листах дані щодо товарів вам не потрібні або ви передаєте замовлення тільки для RFM-аналізу.

Дивіться повний перелік полів замовлення з описами>

Якщо в замовленні передається необов'язковий параметр marketId, система зберігає його разом із замовленням і автоматично оновлює поле Market ID у картці контакту.

Формат для дати: YYYY-MM-DD, формат для дати з часом: YYYY-MM-DDThh:mm:ss±hh:mm.

• Параметр події date має передаватися у форматі ISO 8601 із зазначенням зміщення часового поясу відносно UTC. Наприклад: 2025-01-05T13:00:00+02:00, де +02:00 означає, що місцевий час випереджає UTC на 2 години.
• Враховуйте, що в деяких країнах застосовується перехід між літнім і зимовим часом.

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

{
  "orders": [
    {
      "externalOrderId": "100500",
      "externalCustomerId": "12345",
      "totalCost": 1000,
      "status": "INITIALIZED",
      "date": "2017-03-08T09:30:00+02:00",
      "email": "[email protected]",
      "phone": "380942583691",
      "firstName": "John",
      "lastName": "Smith",
      "currency": "USD",
      "shipping": 10,
      "discount": 0,
      "deliveryMethod": "express",
      "paymentMethod": "cash",
      "deliveryAddress": "First str. 1",
      "marketId": "Lviv_center_2",
      "items": [
        {
          "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"
        }
      ]
    }
  ]
}

Вдала відповідь на запит міститиме статус 200. У тілі відповіді також передається перелік замовлень, які неможливо додати або оновити.

Можливі причини помилки:

• Одне або кілька обов'язкових полів порожні або невірний формат значень.
• Усі наступні необов'язкові поля порожні: externalCustomerId, email, phone. Для створення замовлення необхідна наявність хоча б одного з них.

❗️

Важливо

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

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

За замовленнями зі статусом DELIVERED можна налаштувати сегментацію з такими умовами: середній чек, кількість продажів та дата останнього продажу.

ABANDONED_SHOPPING_CART — статус для покинутих кошиків. Використовуйте цей статус, якщо ви самі займаєтесь визначенням покинутих кошиків. При використанні веб-трекінгу налаштовувати API для покинутих кошиків не потрібно.

Для оновлення статусу або інших даних замовлення передавайте оновлене замовлення з тим самим externalOrderId. За цим параметром у системі визначається унікальність замовлень. Нового запису при цьому не створюється — оновлюється наявне замовлення, і оновлені дані враховуються сегментацією.

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

Це різні значення, які можуть не збігатися:

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

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

Перевірка параметрів подій

Щоб перевірити правильність передачі замовлення, перейдіть до розділу: Тригери — Замовлення вашого облікового запису eSputnik. Натисніть ID замовлення, і перегляньте всі поля у форматі JSON.

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

• Для кожного унікального контакту передавайте унікальний externalCustomerId в замовленні, з номером телефону і поштою, які будуть збігатися в замовленні та картці контакту.
• Якщо раніше вже було замовлення з таким externalCustomerId, то система відразу записує нове замовлення тому ж контакту. Якщо такого externalCustomerId не було раніше, то відбудеться перевірка за номером телефону та поштою.

Розділ Замовлення зберігає фіксований набір полів. Додаткове поле, яке ви передаєте в події, — наприклад бренд або код магазину, — там не з'явиться, але лишається доступним для сегментації за параметрами події: вона читає дані події, а не запис замовлення.

Створення сценаріїв для тригерних розсилок

1. Перейдіть до розділу Тригери → Сценарії. Натисніть кнопку Новий сценарій.

2. Вкажіть назву сценарію (Замовлення доставлено, Замовлення в процесі тощо).
3. Додайте до сценарію такі блоки:

• Блок Отримати замовлення. За допомогою цього блоку система витягне всі дані щодо замовлення й передасть у лист;
• Блок відправлення повідомлення. Виберіть повідомлення, яке ви заздалегідь створили для цього сценарію.

Дані про товари в листі за замовленням (назви, посилання, зображення) підставляються із самого замовлення, а не з товарного фіду: якщо поле в замовленні порожнє, воно буде порожнім і в листі. Звернутися до фіду за довільним ID товару (наприклад, із кастомного поля контакту) не можна — фід використовується лише алгоритмами трекінгу та рекомендацій.

Замість одного повідомлення можна зробити серію. Наприклад, через 1-2 тижні після повідомлення про доставлене замовлення відправити прохання про відгук.

Більше про налаштування умов запуску та зупинки сценарію >

Чому ідентифікатор замовлення може збігатися з ID контакту

Якщо замовлення надходить без externalCustomerId та без іншого ідентифікатора покупця, система може визначити покупця за даними вебтрекінгу й використати внутрішній ID контакту як ідентифікатор покупця в замовленні. Це очікувана резервна поведінка. Щоб у даних замовлення зберігався ваш ідентифікатор, завжди передавайте externalCustomerId явно.