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

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

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

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

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

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

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

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

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

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

Після чого:

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

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

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

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

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

1. Для додавання емейла до списку відписаних існує такий метод: Add emails to unsubscribed list.

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

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

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

2. Для видалення емейла зі списку відписаних використовується Remove emails from unsubscribed list.

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

Розглянемо ресурс Remove emails from unsubscribed list на прикладі в Postman:

1. Задайте конфігурації:
   • Виберіть метод запиту POST
   • Введіть ресурс Remove emails from unsubscribed list
     
2. У розділі Body виберіть raw та формат передачі даних JSON (application/json):
   
3. Вкажіть тіло запиту в форматі:
   
   {
     "emails" : [ "...", ... ]
   }
4. Натисніть Send для відправлення запиту:
   

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

Реалізувати відправлення листа з динамічним контентом можна у два способи. Перший спосіб передбачає просту підстановку даних у тіло листа із запиту, що передається за допомогою 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, де {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 Generate event. Усі зовнішні дані, що надходять у повідомлення, потрапляють до об'єкта data. Щоб вивести потрібний параметр, прописуємо $!data.get('ім'я параметра'). Для цього вам необхідно:

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

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

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

де

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

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

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

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

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

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

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

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

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

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

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

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

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

Як передавати замовлення за 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.

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

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

Перевірити, чи потрапило замовлення до системи й чи коректно передані поля, можна в особистому кабінеті в розділі Тригери → Замовлення. Клікнувши ID замовлення, ви побачите всі поля в форматі 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-запит Get single message status.

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

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

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

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

Для інтеграції форми підписки необхідно викликати ресурс Subscribe 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 — це список додаткових полів, що передаються попарно: ідентифікатор поля + значення

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

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

Другий — викликати ресурс Get catalog list.  Це 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 — це, власне, і є список усіх ваших додаткових полів. Окрім іншої інформації, кожен об'єкт цього списку містить ідентифікатор поля, який ви маєте використовувати під час передачі його значення.