ЧаВо: Интеграция с 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.