API-документация

Русский

English

+7 (495) 664 22 74

Меню раздела

Smartresponder . API
Интерфейс прикладного программирования

Что такое API?

Описание API-интерфейсов

Cписок API-функций

API-callbacks

АPI - это интерфейс, который позволяет с помощью специального набора команд (функций) удаленно управлять каким-либо программным обеспечением (сервисом). Иначе говоря, API - это интерфейс прикладного программирования для интеграции одного программного обеспечения с другим (более подробно можно прочитать о том, что такое API здесь).

API сервиса Smartresponder.ru дает вам возможность управлять вашим аккаунтом (аккаунтами) для ведения почтовых рассылок извне сервиса. Это означает, что вам не нужно больше заходить в свой аккаунт, чтобы проделывать какие-то повторяющиеся операции. Вы можете управлять своим аккаунтом, например, со своего сайта.

Для чего используют API?

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

Самый простой пример - у вас на сайте происходит регистрация пользователей и вы хотите, чтобы одновременно с регистрацией происходила и подписка на вашу почтовую рассылку. API SmartResponder.ru помогает решить эту проблему легко и быстро.

Еще API используют для создания сторонних приложений. Так, например, вы можете разработать свое собственное приложение для SmartResponder.ru и управлять своими рассылками вообще не посещая наш сайт. На самом деле API предоставляет фантастические возможности и сфера применения API-интерфейсов ничем не ограничена.
Появление API-интерфейса у сервиса SmartResponder.ru поможет теперь нашим пользователям решать самые неординарные задачи, интегрируясь с нашим сервисом. А количество функций нашего API-интерфейса со временем будет только расти.

API-интерфейсы представляют собой набор скриптов, вызываемых по HTTP-протоколу методом POST (в случаях запросов, не требующих передачи входных данных, чувствительных к кодировке UTF-8, допускается вызов методом GET).

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

Защита от несанкционированного доступа обеспечивается двумя способами: более простым с точки зрения реализации на стороне клиента (передача специального ключа-пароля в запросе) и более сложным, но более безопасным (передачей с каждым запросом специальной переменной, содержащей контрольную сумму всех параметров, вычисленной по алгоритму MD5). Способ защиты выбирается в аккаунте автора в разделе персональных настроек.

Для всех входных и выходных данных API-интерфейсов используется кодировка UTF-8.

Ответ сервера может быть получен в формате XML или JSON (определяется специальной переменной в запросе). Каждый запрос на выборку может содержать следующие параметры:

format	Формат ответа. Может принимать значение "xml" или "json". По умолчанию (если переменная не передана) формат ответа - "xml".
fields	Перечисленные через запятую наименования полей, которые необходимо вернуть в результате запроса. Т.е., например, если вам необходимо получить только ID и название рассылок, достаточно указать fields=id,title в запросе к интерфейсу управления рассылками. По умолчанию возвращаются все поля записей.
fields_exclude	Перечисленные через запятую наименования полей, которые необходимо исключить из результата запроса. Т.е., например, если вам необходимо получить все поля из списка шаблонов, кроме достаточно объемных html_body и text_body, необходимо указать в запросе параметр fields_exclude=html_body,text_body.

В случае, если вы выбрали защиту от несанкционированного доступа c помощью API-ключа, вам следует с каждым запросом передавать следующий параметр:

api_key*

Ваш уникальный 32-символьный API-ключ. Узнать его вы можете в разделе "Мои настройки" в секции управления API. Для доступа к API-интерфейсу достаточно указать этот ключ, больше никаких действий со стороны клиента не требуется.

В случае, если вы хотите более надежной защиты, вам следует с каждым запросом передавать следующие параметры:

api_id*

Ваш уникальный API-идентификатор. Узнать его вы можете в разделе "Мои настройки" в секции управления API.

hash *

Контрольная сумма запроса, которая представляет собой MD5-хэш от строки вида:
"переменная_1=значение_1:переменная_2=значение_2: ... :password=ваш_API_пароль".
В запросе:
"http://api.smartresponder.ru/delivery.html?api_id=123456&action=list&hash=f094da5578bb4631451d43891fea1874"
переменная hash посчитана как MD5 строки "api_id=123456:action=list:password=hv7yd72s" (при установленном API-пароле hv7yd72s). Т.е. MD5 - это хэш от склеивания всех переменных и их значений, разделенных двоеточием с последней переменной (указываемой в самом конце склеиваемой строки) - API-паролем. Переменные при этом могут склеиваться в произвольном порядке.

ВНИМАНИЕ:
1. Кодировка получаемых и возвращаемых данных для всех API-интерфейсов - Unicode (UTF-8), поэтому передавать данные и расчитывать любые контрольные суммы необходимо только в этой кодировке.
2. В качестве переноса строк использовать только "\n", не "\r\n"!
3. Во всех значениях передаваемых клиентом переменных знак амперсанда ("&") должен быть заменен на "%26amp%3B", пробел (" ") - на "%20", знак равенства ("=") - на "%3D", вопросительный знак ("?") - на "%3F".
4. Результат выполнения MD5 хэширования должен быть в 16-ричном разряде.

Формат ответа:

<response>
 <result></result>
 <error code="" message=""/>
 <данные>
 ...
 <данные>
</response>

result	Результат исполнения запроса. 1 - запрос исполнен удачно (не возникло системных ошибок) 0 - запрос не исполнен или исполнен с ошибками
error	В случае если во сремя исполнения запроса возникли ошибки, это поле содержит код ошибки (атрибут code) и текст сообщения об ошибке (атрибут message). Если запрос исполнен без ошибок, поле error в ответе отсутствует.
данные	Набор полей, содержащих данные ответа API-интерфеса. Набор специфичен для каждого интерфейса (может отсутствовать, если интерфейс не возвращает никаких данных).

Параметры помеченные звездочкой (*) являются обязательными для передачи.

Обратные вызовы (callbacks) - это специальный блок функций API нашего сервиса, которые помогают Вам извне (например с Вашего сайта) следить в режиме реального времени за различными важными изменениями внутри Вашего авторского аккаунта на Smartresponder. Например, Вы можете постоянно считывать изменения состояний подписного листа, кто отписался или подписался и т.п.

Для работы обратных вызовов Вам необходимо указать URL скрипта со своей стороны, который будет обрабатывать запросы от нашего сервера. Адрес скрипта указывается в разделе "Настройки Вашего аккаунта" во вкладке API. После нажатия "Сохранить" произойдет GET-запрос к указанному скрипту c переменной "action=test" для успешного принятия URL нашим сервисом, Ваш скрипт должен вернуть строку "TEST:OK".

После каждого вызова Ваш скрипт должен возвращать строку, состоящую из ID запроса, кода действия (перечислены ниже), и слова "OK", разделив их сомволом двоеточия ":" (регистр символов не имеет значения). В противном случае запрос будет считаться неудачным и каждые 5 минут в течение 24 часов будет производиться попытка повторного вызова Вашего скрипта. Например, если наш сервис вызвал Ваш скрипт по URL http://somesite.com/smart_callback.html?request_id=123&action=subscriber_added..., то для подтверждения принятия нашего вызова, скрипт должен вернуть строку "123:subscriber_added:ok".

Используемая для передачи данных кодировка - UTF-8. Данные приходят POST-запросом. Каждый запрос содержит следующие обязательные переменные:

request_id	Уникальный ID запроса. Рекомендуется сохранять его со своей стороны и проверять каждый раз, чтобы исключить дублирование событий.
date_tstamp	Дата события в формате UNIX-timestamp. Часовой пояс (GMT) Москвы.
date	Дата события в формате "ДД/ММ/ГГГГ ЧЧ:ММ:CC". Часовой пояс (GMT) Москвы.
subscriber_id	ID подписчика, на который дальше можно ссылаться при операциях с API.
email	Электронный адрес подписчика
action	Код события. В зависимости от кода могут передаваться дополнительные переменные. Значения переменной action перечислены ниже.

Переменная action=subscriber_added - добавлен новый подписчик. Дополнительно передается:

name_last, name_first, name_mid	ФИО подписчика
birth_day, birth_month, birth_year	Дата рождения
city	Город подписчика
company	Компания подписчика

Переменная action=subscriber_unsubscribed - подписчик отписался. Дополнительно передается:

delivery_id

ID рассылки, от которой произошла отписка

Переменная action=subscriber_subscribed - подписка на рассылку. Дополнительно передается:

delivery_id

ID рассылки, на которую подписчик подписался

Переменная action=subscriber_deleted - подписчик удалил себя из списка автора.

Переменная action=subscriber_activated - подписчик активирован.

Дополнительные разделы:

Секреты email-маркетинга от Smartresponder!

Заработать у нас:

Зарабатывайте вместе с нами в нашей партнер- ской программе

Следите за нами:

Начать сейчас →

Нужна помощь? Спросите!