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

Описание API

API Falconsender открывает огромный ряд возможностей
для интеграции нашего сервиса с вашим сайтом.

API. Что это?

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

API сервиса Falconsender позволяет управлять вашим аккаунтом автора, не заходя в него, то есть удалённо. Управление аккаунтом может происходить, например, с вашего сайта. Это очень удобно.

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

API доступно только авторам, использующим платные тарифы.

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

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

format	Формат ответа сервера - `XML` (по умолчанию) или `JSON` (если в запросе указана специальная переменная).
fields	Наименования полей, указанные через запятую, которые могут быть получены в результате запроса. Например, вам необходимо получить лишь ID и названия рассылок, нужно будет указать `fields=id,title` в запросе к соответствующему интерфейсу и т.д. По умолчанию возвращаются все наименования полей.
fields_exclude	Наименования полей, указанные через запятую, которые должны быть исключены из результата запроса. Например, вам необходимо получить все поля из интерфейса списка шаблонов за исключением `html_body` и `text_body`, тогда нужно будет указать `fields_exclude=html_body,text_body`.

Аутентификация

В качестве аутентификации используется уникальный 32-символьный API-ключ.

api_key*

Уникальный 32-символьный API-ключ. Получить данный ключ можно в настройках аккаунта автора в разделе "API". Чтобы получить доступ ко всем API-интерфейсам необходим только данный ключ.

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

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

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

Общие сведения

Рассылки

Файлы

Шаблоны писем

Управление списком подписчиков

Подписка на рассылку, отправка письма

Управление списком групп

Список групп

Управление статистикой

API. Что это?

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

format	Формат ответа сервера - `XML` (по умолчанию) или `JSON` (если в запросе указана специальная переменная).
fields	Наименования полей, указанные через запятую, которые могут быть получены в результате запроса. Например, вам необходимо получить лишь ID и названия рассылок, нужно будет указать `fields=id,title` в запросе к соответствующему интерфейсу и т.д. По умолчанию возвращаются все наименования полей.
fields_exclude	Наименования полей, указанные через запятую, которые должны быть исключены из результата запроса. Например, вам необходимо получить все поля из интерфейса списка шаблонов за исключением `html_body` и `text_body`, тогда нужно будет указать `fields_exclude=html_body,text_body`.

Аутентификация

В качестве аутентификации используется уникальный 32-символьный API-ключ.

api_key*

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

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

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

API-callbacks

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

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

Созданный вами скрипт после каждого вызова должен возвращать строку, включающую в себя ID запроса, код действия и слова "ОК", разделены эти данные должны быть двоеточием (:). Важно учесть, что в любом противном случае запрос будет расценен как неудачный, и в течение 24 часов каждые 5 минут будет выполняться попытка повторного вызовы вашего скрипта.

Предположим, Falconsender вызвал соданный вами скрипт по URL http://yoursite/falcon_callback.html?request_id=12345&action=subscriber_added... , в таком случае для подтверждения скрипт должен вернуть строку "12345:subscriber_added:ok".

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

Обязательные переменные, содержащиеся в каждом запросе:

request_id	Уникальный ID запроса. Уникальный ID запроса. Желательно сохранять его на своей стороне и всегда проверять, чтобы не дублировать события.
date_tstamp	Дата события в формате UNIX-времени. Часовой пояс (GMT) Москвы.
date	Дата события в формате "`ДД/ММ/ГГГГ ЧЧ:ММ:CC`". Часовой пояс (GMT) Москвы.
subscriber_id	ID подписчика
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 - подписчик активирован, без дополнительных переменных.