Интеграция с API

Общая документация

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

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

Часто задаваемые вопросы

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

Самый простой метод API — это получить текущую версию: https://esputnik.com/api/v1/version. При переходе по ссылке, вас спросит username и пароль необходимый для аутентификации. Если введенные параметры доступа правильные, то вы получите ответ похожий на этот:

{"version":"1.0-r20150908","protocolVersion":"1.0"}

 

Как быстро протестировать или вызвать метод API

Есть очень удобный плагин для Chrome:  Postman расширение для Chrome. Вы можете поставить его и тестировать запросы в очень удобном редакторе. Вот как это выглядит для простого запроса получения версии:


Нажав на кнопку Send, Вас попросит указать параметры доступа, укажите те, которые Вам были выданы для работы с API. Еще лучше их указать в параметрах Basic Auth

 

 

Как отписать контакта, если отписка прошла в личном кабинете пользователя на сайте?

Для управления отпиской используйте метод API /v1/emails/unsubscribed/add или delete. Вообще, отписывается не контакт, а email, и письма не будут отправляться не только этому контакту, но и любому другому в организации с этим же email.

Отписка контакта в Postman

1. Для добавления емейла в список отписавшихся существует следующий метод: https://esputnik.com/api/v1/emails/unsubscribed/add
Тело запроса выглядит так:
 
{
  "emails" : [ "test1@mail.com", "test2@mail.com" ]
}
 
emails - это список адресов, которые будут помечены, как отписавшиеся.
 
2. Для удаления емейла из списка отписавшихся используется этот метод: https://esputnik.com/api/v1/emails/unsubscribed/delete
Тело запроса аналогичное предыдущему рассмотренному методу - список адресов, которые будут удалены из отписавшихся.

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

С помощью API очень удобно отправлять триггера, используя метод API /v1/event. Для этого Вам необходимо:

1) создать письмо, которое Вы хотите отправлять;

Письмо в редакторе eSputnik

Обратите внимание! Значение в кавычках после $!data.get должно соответствовать значению name в массиве параметров params, который мы позже передадим в запросе.

2) создать сценарий с помощью Редактора сценариев;

Редактор сценариев

3) создать событие (Триггеры - Типы событий - Добавить тип события) с ключом, который будет использован в запросе (поле "eventTypeKey"), и привязать к событию сценарий(см. п. 2);

Добавить тип события

4) вызвать запрос в Postman;

Вид запроса в Postman

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

{

    "eventTypeKey": "...",

    "keyValue": "...",

    "params": {

        "name": "..."

        "value": "...",

        }, ... ]

}

 

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

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

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

После нажатия на кнопку "Send" запрос будет отправлен и, в течение минуты мы получим письмо, вида: 

 

После успешной отправки запроса, Вы можете проверить правильность выполнения: 

 

1) наличие записи в Триггеры - История событий;

2) наличие письма в Рассылки - Одиночные;

3) письмо должно прийти на почтовый ящик.

 

Как получить статус отправленного сообщения через API?

Если вы отправляете одиночные сообщения методами  /v1/message/{id}/send, /v1/message/{id}/smartsend, /v1/message/email или /v1/message/sms, то отправка происходит в асинхронном режиме. А именно, после запроса к API ваше сообщение ставится в очередь на отправку и через некоторое время (обычно в течение нескольких секунд) отправляется. В ответ на каждый из этих запросов вы получите подобную структуру:

{

    "id": "0",

    "results": {

        "id": "0",

        "locator": "test@mail.com",

        "status": "OK",

        "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e"

    }

}

Затем, чтобы получить статус этого сообщения, необходимо вызвать GET-запрос https://esputnik.com/api/v1/message/email/status?ids=3ff28330-f8ef-4636-92ac-86345c16995e (либо /v1/message/sms/status для одиночного sms-сообщения).

Параметр ids - это список идентификаторов requestId, разделённых запятой. В ответ вы получите такой ответ:

{

    "results": {

        "status": "DELIVERED",

        "requestId": "3ff28330-f8ef-4636-92ac-86345c16995e",

        "failed": "false",

        "delivered": "true"

    }

}

Подробнее о данных из этого ответа и в частности о статусах сообщения можно прочитать здесь: https://esputnik.com/api/ns0_instantMessageStatusDto.html.

 

Как использовать динамический контент в письмах?

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

1) Метод API /v1/message/{id}/send

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

{

  "groupId" : ...,

  "recipients" : [ "..." ],

  "params" : [ {

    "key" : "...",

    "value" : "..."

  } ]

}

groupId - идентификатор группы для отправки сообщения

recipients - массив адресов получателей сообщения

Из этих двух параметров обязательно нужно указать хотя бы один.

params - массив из пар "ключ + значение". Ключи вставляются в тело письма в таком виде: %TEMPLATE.xxx%. Затем передаётся значение: {"key":"xxx", "value":"<table><tr><td>test</td></tr></table>"}. При отправке все ключи в теле письма заменяются на их значения из params, либо удаляются, если значение для конкретного ключа не передано.

2) Метод API /v1/message/{id}/smartsend

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

{

  "recipients" : [ {

    "locator" : "...",

    "jsonParam" : "..."

  } ]

}

В отличии от первого метода, где все адресаты получают один и тот же контент письма, в этом методе есть возможность сгенерировать разный контент для каждого конкретного получателя. Для этого передача данных организована в виде пар "емейл + набор параметров". Параметры передаются в виде произвольной 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?

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

{

  "contact" : {

    "channels" : [ {

      "type" : "email",

      "value" : "test@mail.com"

    } ]

  }

}

Таким образом в списке медиа-каналов контакта присутствует один емейл-адрес.

Чтобы задать имя контакта, необходимо добавить в тело запроса поле 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": 12345,
       "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 - это и есть список всех ваших дополнительных полей. Кроме прочей информации, каждый объект этого списка содержит идентификатор поля, который вам нужно использовать при передаче его значения.