Интеграция с API – ЧаВо

Где искать всю техническую документацию?

Вся техническая документация по формату данных, стандартам и кодам ошибок содержится в статье "Введение в eSputnik Rest API". Всегда актуальное описание ресурсов API и примеры кода для их вызова находятся на странице "Доступные ресурсы eSputnik Rest API".

Здесь мы постараемся дать ответы на часто задаваемые вопросы о том, как пользоваться API или как решить конкретную проблему, с более развернутыми описаниями и примерами, чем в описании методов.

Как проверить, что API работает, а параметры доступа правильные

Самый простой вариант – это получить информацию о вашем аккаунте: api/v1/account/info.

Рассмотрим на примере приложения Postman, которое предназначено для легкого тестирования API. Скачайте приложение и установите на компьютер. Чтобы история запросов сохранилась, нужно авторизоваться, но для быстрого теста можно обойтись и без регистрации в сервисе.

Для начала в параметрах во вкладке Authorization в строке Type выберите Basic Auth:

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

В строках Username и Password введите логин и пароль, которые вы используете для входа в систему eSputnik.

ввод пароля и логина eSputnik

Затем:

  • Выберите метод. В нашем случае это 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, подставлялся в тело сообщения, нужно подготовить сценарий с использованием этого письма.

Второй способ предполагает отправку сообщений сразу, без использования сценария. Для этого используйте ресурс API /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('имя параметра'). Для этого Вам необходимо:

  1. Подготовить тело запроса.

    Минимальное тело запроса имеет вид:

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

    , где

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

    keyValue – идентификатор события, может совпадать с идентификатором или email-ом контакта; 

    name – имя параметра; 

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

  2. Создать письмо с динамическим контентом, которое вы хотите отправлять (Сообщения → Сообщения → Создать Email).
    Письмо в редакторе eSputnik
    Обратите внимание! Значение в кавычках после $!data.get должно соответствовать значению name в массиве параметров params, который вы будете передавать в запросе.
     
  3. Создать сценарий, чтобы контент, передаваемый ресурсом /v1/event, подставлялся в тело сообщения (Триггеры → Сценарии → Добавить сценарий).
    создание сценария
  4. Создать событие (Триггеры → Типы событий → Добавить тип события) с ключом, который будет использован в запросе (поле 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