Поширені питання: Інтеграція з API

У цій статті ви знайдете відповіді на найпоширеніші питання про інтеграцію з API eSputnik.

Вся технічна документація щодо формату даних для виклику API-запитів знаходиться за посиланням.

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

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

1. Згенеруйте ключ API та скопіюйте його до буфера обміну.

2. Перейдіть на сторінку https://docs.esputnik.com/reference/getaccountinfo-1.

3. Введіть ім’я користувача та пароль, який є скопійованим ключем API, над прикладом запиту.

4. Натисніть Try it!

У відповіді ви маєте побачити ім’я користувача та назву своєї організації:

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

Для управління відпискою використовуйте метод API Add emails to unsubscribed list та Remove emails from unsubscribed list.

Тіло запиту Add emails to unsubscribed list має такий вигляд:

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

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

Тіло запиту Remove emails from unsubscribed list є таким самим: воно має містити перелік адрес, які будуть видалені з відписаних.

Розглянемо роботу з методом Remove emails from unsubscribed list:

1. Перейдіть на сторінку https://docs.esputnik.com/reference/deletefromunsubscribed-1. 

2. В BODY PARAMS натисніть ADD STRING і введіть до рядків адреси відписаних контактів.

3. Натисніть Try it!

Якщо адреси з запиту були у відписаних у вашому акаунті eSputnik, вони видаляться з цього списку.

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

Реалізувати відправлення листа з динамічним контентом можна у два способи:

• За допомогою сценарію
• За допомогою методу Send prepared message

За допомогою сценарію

Цей спосіб передбачає просте підставляння даних у повідомлення із запиту, що передається за допомогою API-методу Generate 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'), замість яких будуть підставлятися дані з запиту.

Щоб контент, який передається методом Generate event, підставлявся в тіло повідомлення, підготуйте сценарій з використанням цього повыдомлення, що запускатиметься відповідною подією. Докладніше >

За допомогою методу Send prepared message

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

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

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

де:

• recipients – масив з контактними даними одержувачів повідомлення;
• locator – одержувач, наприклад — email-адреса для email-повідомлень, номер телефону для SMS або Viber;
• jsonParam — дані у вигляді JSON для підставлення до повідомлення.

Метод дозволяє згенерувати різноманітний контент для кожного конкретного отримувача за допомогою змінних Velocity. З цією метою передавання даних організовано парами "емейл + набір параметрів". Параметри передаються у вигляді довільної 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-ресурсу Send prepared message".

Як використовувати події для тригерів?

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

Також ми рекомендуємо викорситовувати метод Generate event для передавання замовлень. Інструкції >

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

Для передавання замовлень також можна використовувати метод Add 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.

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

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

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

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

Якщо ви відправляєте одиночні повідомлення методами

• Send prepared message,
• Send email message,
• Send SMS message,
• Send Viber message,

відправлення відбувається в асинхронному режимі: після запиту до API ваше повідомлення ставиться в чергу на відправлення і через деякий час (зазвичай протягом кількох секунд) відправляється. У відповідь ви отримаєте таку структуру:

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

Для отримання статусу такого повідомлення треба викликати запит Get single message status.

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

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

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

eSputnik пропонує вбудовану функціональність для створення віджетів без необхідності додаткових налаштувань API. 

Для інтеграції форми підписки, створеної за допомогою стороннього сервісу, викличте запит методом Subscribe a contact. Мінімальне тіло запиту має такий вигляд:

{
  "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?

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

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

де

• channels — це список медіаканалів контакту; в даному прикладі передається один медіаканал — емейл;
• fields — це список додаткових полів, що передаються попарно: ідентифікатор поля + значення.

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

1. Переглянути ідентифікатори в  налаштуваннях акаунта на вкладці “Додаткові поля”.

2. Викликати запит методом Get the list of catalogs. Це метод без параметрів, що поверне вам структуру, подібну до цієї:

{
    "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 за допомогою Postman?

Postman – це популярний інструмент для тестування API. Він надає зручний інтерфейс для створення, відправлення та відстеження запитів. 

Для початку роботи з Postman завантажте та встановіть його на комп'ютер.

Тестування методу Get account info

1. Оберіть Basic Auth у параметрах, вкладка Authorization, рядок Type:

2. Авторизуйтеся:

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

3. Виберіть метод GET та введіть посилання https://esputnik.com/api/v1/account/info.

4. Натисніть кнопку Send.

У відповіді ви маєте побачити ім’я користувача та назву своєї організації:

{
    "userEmail": "api-user162065",
    "organisationName": "ExamleName"
}

Тестування методу Remove emails from unsubscribed list

1. Виберіть метод запиту POST та введіть посилання https://esputnik.com/api/v1/emails/unsubscribed/delete.

2. У розділі Body виберіть raw та формат передавання даних JSON.

3. Вкажіть тіло запиту в форматі:

{
  "emails" : [ "...", "..." ]
}

4. Натисніть Send.

Якщо адреси з запиту були у відписаних у вашому акаунті eSputnik, вони видаляться з цього списку.

Тестування методу Generate event v2

1. Виберіть метод запиту POST та введіть посилання https://esputnik.com/api/v2/event.

2. У розділі Body виберіть raw і формат передавання даних JSON.

3. Вставте код події в тіло запиту в такому форматі:

{
    "eventTypeKey": "create_contact",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "email",
            "value": "site@ukr.net"
        },
        {
            "name": "phone",
            "value": "380501234567"
        },
        {
            "name": "externalCustomerId",
            "value": "AV13760"
        },
        {
            "name": "json",
            "value":
            {
                "profileInputs":
                [
                    {
                        "profileInputId": 10001,
                        "value": "2020-11-23"
                    }
                ]
            }
        }
    ]
}

4. Натисніть Send. 

Успішно переданий запит відобразиться в історії подій в акаунті eSputnik.