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

Остались вопросы?
С радостью ответим!
Обратный звонок
Оставьте заявку, и наш специалист свяжется с вами в рабочее время.
Отправить заявку
Консультация в чате
Ждем ваши вопросы!
Написать в чат
Электронная почта
Напишите в службу поддержки eSputnik.
Отправить email