Інтеграція з API — найчастіші питання

Де шукати всю технічну документацію?

Уся технічна документація щодо формату даних, стандартів та кодів помилок міститься в статті "Вступ до eSputnik Rest API". Завжди актуальний опис ресурсів API та приклади коду для їхнього виклику подані на сторінці "Доступні ресурси eSputnik Rest API".

Тут ми спробуємо відповісти на найбільш поширені питання про те, як користуватися API або вирішити конкретну проблему, з більш розгорнутими описами та прикладами, ніж в описі методів.

Як перевірити, що API працює, а параметри доступу правильні

Найпростіший варіант — це отримати інформацію про ваш акаунт: api/v1/account/info.

Розглянемо на прикладі додатка Postman, призначеного для простого тестування API. Скачайте додаток і встановіть на комп'ютер. Щоб історія запитів збереглася, треба авторизуватися, але для швидкого тесту можна обійтися і без реєстрації в сервісі.

Перш за все оберіть Basic Auth у параметрах, вкладка Authorization, рядок Type:

Авторизація в Postman

Щоб авторизуватися, потрібно:

  • ввести будь-яке значення для поля Username,
  • ввести значення вашого API-ключа в поле Password.

Postman

Після чого:

  • Виберіть метод. У нашому випадку це GET.
    Введіть ресурс. У нашому випадку це /api/v1/account/info.

Виберіть метод, введіть ресурс

  • Натисніть кнопку Send для відправлення запиту.

кнопка Send

Так виглядатиме запит для отримання інформації про ваш акаунт:

запит для отримання інформації

Як відписати контакт, якщо відписку здійснено в особистому кабінеті користувача на сайті?

Для управління відпискою використовуйте ресурс API /v1/emails/unsubscribed/add або delete.

Важливо!

Ви відписуєте не конкретний контакт, а лише email користувача, тоді як інші медіаканали (SMS, Viber, push) залишаються доступними. Якщо в організації електронну адресу використовують кілька контактів, то всі вони перестануть отримувати масові розсилки після відписки.

1. Для додавання емейла до списку відписаних існує такий метод: /api/v1/emails/unsubscribed/add.

Тіло запиту має такий вигляд:

{
  "emails" : [ "test1@mail.com", "test2@mail.com" ]
}

emails це список адрес, що будуть позначені як відписані.

2. Для видалення емейла зі списку відписаних використовується /api/v1/emails/unsubscribed/delete.

Тіло запиту є таким самим, як у розглянутому вище ресурсі: ви вводите перелік адрес, які будуть видалені з відписаних.

Розглянемо ресурс /api/v1/emails/unsubscribed/add  на прикладі в Postman:

  1. Задайте конфігурації:
  2. У розділі Body виберіть raw та формат передачі даних JSON (application/json):
    формат передачі даних
  3. Вкажіть тіло запиту в форматі:

    {
      "emails" : [ "...", ... ]
    }
  4. Натисніть Send для відправлення запиту:
    емейли для відписки

Як використовувати динамічний контент у листах?

Реалізувати відправлення листа з динамічним контентом можна у два способи. Перший спосіб передбачає просту підстановку даних у тіло листа із запиту, що передається за допомогою API ресурсу v1/event. Масив params може містити довільну кількість об'єктів такого вигляду:
...

{
"name": "назва поля",
"value": "значення поля"
}

...

Для підстановки даних треба скористатися velocity.
Наприклад, передано такий запит:

{
    "eventTypeKey": "testEvent",
    "keyValue": "example@email.com",
    "params": [{
        "name": "discount",
        "value": "5%"
        },{
        "name": "link",
        "value": "https://example.site.com/items_for_sale"
        }
]
}

У повідомленні необхідно використовувати записи,що виглядають як$!data.get('discount') та $!data.get('link'), де будуть динамічно підставлятися персональні значення знижки й посилання, передані в запиті.

Щоб контент, який передається ресурсом /v1/event, підставлявся в тіло повідомлення, треба підготувати сценарій з використанням цього листа.

Другий спосіб передбачає відправлення повідомлень одразу, без використання сценарію. Для цього використовуйте ресурс /v1/message/{id}/smartsend, де {id} — ідентифікатор листа, до якого будуть підставлятися дані при відправленні одержувачу.

Тіло запиту в мінімальному вигляді:

{
  "recipients" : [ {
    "locator" : "...",
    "jsonParam" : "..."
  } ]
}

recipients – масив адрес одержувачів повідомлення.

locator – одержувач. Наприклад, email-адреса для email-повідомлень, номер телефону для SMS або Viber.

jsonParam — дані у вигляді json для підстановки в лист.

Метод дозволяє згенерувати різноманітний контент для кожного конкретного отримувача. Із цією метою передачу даних організовано парами "емейл + набір параметрів". Параметри передаються у вигляді довільної json-структури, до всіх полів якої в тілі листа можна звернутися так: $data.get('field_name').

Є можливість:

  • Задати умову відображення будь-якого блоку html-коду: #if($data.get('field_name').equals('0')) ... #end.
  • Організувати цикл за елементами масиву: #foreach($item in $data.get('items')) ... $item.get('name') ... $item.get('price') ... #end.
  • Здійснювати в тілі листа арифметичні операції зі значеннями полів. Зверніть увагу, що подвійні лапки всередині json-структури з параметрами мають екрануватися: "jsonParam" :  "{\"field1\":\"value1\", ... }".

Більш детально про ресурс написано в статті "Використання API ресурсу smartsend".

Як використовувати event-и для тригерів, наприклад "Ваше замовлення оформлене"

За допомогою API дуже зручно відправляти тригери, використовуючи метод API /v1/event. Усі зовнішні дані, що надходять у повідомлення, потрапляють до об'єкта data. Щоб вивести потрібний параметр, прописуємо $!data.get('ім'я параметра'). Для цього вам необхідно:

Підготувати тіло запиту.

Мінімальне тіло запиту має вигляд:

{
    "eventTypeKey": "...",
    "keyValue": "...",
    "params": [{
        "name": "...",
        "value": "..."
        }, ... ]
}

, де

eventTypeKey – идентификатор-ключ типа события. Если в системе нет типа события с таким ключом, то он создастся автоматически;

eventTypeKey — ідентифікатор-ключ типу події. Якщо в системі немає типу події з таким ключем, то він створюється автоматично;

keyValue — ідентифікатор події, може збігатися з ідентифікатором або email-ом контакту;

name — ім'я параметра;

params — список параметрів.

  1. Створити лист з динамічним контентом, який ви бажаєте відправляти (Повідомлення → Повідомлення → Створити Email).
    Лист в редакторі eSputnik
    Зверніть увагу! Значення в лапках після $!data.get має відповідати значенню name в масиві параметрів params, який ви передаватимете в запиті.
  2. Створити сценарій, щоб контент, який передається ресурсом /v1/event, підставлявся в тіло повідомлення (Тригери → Сценарії → Додати сценарій).
    Створення сценарію
  3. Створити подію (Тригери → Типи подій → Додати тип події) з ключем, що буде використаний у запиті (поле eventTypeKey), і прив'язати до події сценарій, створений на попередньому етапі.

Тип події

Заздалегідь створювати подію в акаунті не обов'язково.

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

Для тестування треба викликати запит у Postman.

  1. Задайте конфігурації:
    • Виберіть метод запиту POST
    • Введіть ресурс /api/v1/event
  2. У розділі Body виберіть raw і формат передачі даних JSON (application/json).
  3. Укажіть тіло запиту в форматі:

Вигляд запросу в Postman 

Після натискання кнопки Send запит буде відправлений, і протягом хвилини ми отримаємо лист такого вигляду:

Лист в редакторі

Після успішного відправлення запиту ви можете перевірити правильність виконання:

1) передачі події в систему: Тригери → Історія подій;

Історія подій

2) відправлення листа: Розсилки → Поодинокі;

Одиничні звіти

3) отримання листа із правильно підставленими елементами: Лист у вхідних.

Як передавати замовлення за API?

Для передачі замовлень треба використовувати ресурс /v1/orders. У запиті можна передати від 1 до 1000 замовлень. Щоб підставляти в листи товари, у замовленнях слід передавати масив items із даними цих товарів. Формат запиту й опис усіх полів доступні тут. Якщо дані товарів у листах не потрібні або ви передаєте замовлення тільки для RFM-аналізу, масив можна не передавати.
Приклад тіла запиту:

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

Для замовлень можна використовувати кілька статусів:

  • Для щойно створеного замовлення використовуйте статус INITIALIZED.
  • Для замовлення в процесі доставки – IN_PROGRESS.
  • Для сплаченого та доставленого замовлення – DELIVERED.
  • Для скасованих замовлень – CANCELLED.


Важливо! Для формування RFM використовуються тільки замовлення в статусі DELIVERED.

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

Перевірити, чи потрапило замовлення до системи й чи коректно передані поля, можна в особистому кабінеті в розділі Тригери → Замовлення. Клікнувши ID замовлення, ви побачите всі поля в форматі JSON.

Перелік замовлень

Дізнайтеся, як динамічно використовувати інформацію про замовлення в листах та створювати тригерні розсилки >>

Як отримати статус відправленого повідомлення через API?

Якщо ви відправляєте одиночні повідомлення ресурсами /v1/message/{id}/smartsend, /v1/message/email, /v1/message/sms, /v1/message/viber, то відправлення відбувається в асинхронному режимі. А саме: після запиту до API ваше повідомлення ставиться в чергу на відправлення і через деякий час (зазвичай протягом кількох секунд) відправляється. У відповідь на кожен із цих запитів ви отримаєте таку структуру:

{
    "id": "0",
    "results": {
        "id": "0",
        "locator": "test@mail.com",
        "status": "OK",
        "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"
    }
}

Після чого для отримання статусу цього повідомлення, а також будь-якого повідомлення, відправленого через будь-який канал, треба викликати GET-запит /api/v1/message/status.

Параметр ids — це список ідентифікаторів requestId, розділених комою. Ви отримаєте таку відповідь:

{
    "results": {
        "status": "DELIVERED",
        "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",
        "failed": "false",
        "delivered": "true"
    }
}

Детальніше про дані з цієї відповіді та зокрема про статуси повідомлення можна прочитати тут: "статуси".

Як інтегрувати форму підписки через API?

Для інтеграції форми підписки необхідно викликати ресурс /v1/contact/subscribe. Мінімальне тіло запиту має такий вигляд:

{
  "contact" : {
    "channels" : [ {
      "type" : "email",
      "value" : "test@mail.com"
    } ]
  }
}

Таким чином, у системі з'явиться один контакт з email-ом.

Щоб задати ім'я контакту, треба додати до тіла запиту поле firstName в об'єкті contact:

{
  "contact" : {
    "firstName" : "...",
    "channels" : [ {
      "type" : "email",
      "value" : "test@mail.com"
    } ]
  }
}

Щоб указати, до яких груп потрапить контакт, що підписався, слід додати до запиту поле groups — масив рядкових значень назв груп. Якщо якісь групи не існують у системі, вони будуть створені автоматично:

{
  "contact" : {
    "firstName" : "...",
    "channels" : [ {
      "type" : "email",
      "value" : "test@mail.com"
    } ]
  },
  "groups" : [ "Subscribers" ]
}

Після виклику цього ресурсу в системі автоматично генерується одна з двох подій: subscribeFromAPI — у разі створення нового контакту; і subscribeUpdateFromAPI — якщо такий контакт уже існує. Ці події ви можете побачити в розділі Тригери → Історія подій.

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

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

Щоб переконатися, що новий контакт створено, ви можете знайти його: перейти до Контакти → Усі контакти, після чого ввести в рядок пошуку потрібний емейл.

пошук контактів

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

непідтверджений контакт

На такі адреси неможливо відправити розсилку, вони можуть отримувати тільки листи для підтвердження підписки та інші транзакційні повідомлення, наприклад лист про покинутий кошик або підтвердження оформленого замовлення.

Як передати значення додаткових полів контакту через API?

Розглянемо оновлення додаткових полів на прикладі ресурсу /v1/contacts створення/оновлення контактів. Мінімальне тіло цього запиту з додатковими полями має такий вигляд:

{
  "contacts": [{
    "channels": [{
      "type": "email",
      "value": "test@mail.com"
    }],
    "fields": [{
       "id": 15868,
       "value": "ж"
    }]
  }],
  "customFieldsIDs": [12345]
}

channels — це список медіа-каналів контакту; в даному прикладі передається один медіаканал — емейл

fields — це список додаткових полів, що передаються попарно: ідентифікатор поля + значення

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

Перший — переглянути ідентифікатори в Меню акаунта → Налаштування → Додаткові поля.

додаткові поля

Другий — викликати ресурс /v1/addressbooks.  Це GET-метод без параметрів, що поверне вам структуру, подібну до цієї:

{
    "addressBook": {
        "addressBookId": "7200",
        "name": "Основной",
        "fieldGroups": {
            "name": "Personal",
            "fields": [
                {
                    "id": "15867",
                    "name": "День рождения",
                    "description": {
                        "type": "date",
                        "required": "false",
                        "readonly": "false"
                    }
                },
                {
                    "id": "15868",
                    "name": "Пол",
                    "description": {
                        "type": "combobox",
                        "allowedValues": {
                            "possibleValues": [
                                "м",
                                "ж"
                            ]
                        },
                        "required": "false",
                        "readonly": "false"
                    }
                }
            ]
        }
    }
}

Список fields — це, власне, і є список усіх ваших додаткових полів. Окрім іншої інформації, кожен об'єкт цього списку містить ідентифікатор поля, який ви маєте використовувати під час передачі його значення.

Протестуйте API на реальних розсилках

Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email