Интеграция с API – частые вопросы

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

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

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

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

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

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

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

Чтобы авторизоваться, нужно:

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

Затем:

• Выберите метод. В нашем случае это GET.
• Введите ресурс. В нашем случае это Get account info.

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

Так будет выглядеть запрос для получения информации о вашем аккаунте:

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

Для управления отпиской используйте ресурс API Add emails to unsubscribed list или Remove emails from unsubscribed list.
Важно! Вы отписываете не конкретный контакт, а только email пользователя, другие медиаканалы (SMS, Viber, push) остаются доступны. Если в организации электронный адрес используют несколько контактов, то все они перестануть получать массовые рассылки после отписки.

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

Тело запроса выглядит так:

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

emails – это список адресов, которые будут помечены как отписавшиеся.

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

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

Рассмотрим ресурс Add emails to unsubscribed list на примере в Postman:

1. Задайте конфигурации:
   • Выберите метод запроса POST
   • Введите ресурс Add emails to 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, подставлялся в тело сообщения, нужно подготовить сценарий с использованием этого письма.

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

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

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

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

   , где

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

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

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

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

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