API

Для разработчиков

API (Application Programming Interface) — это интерфейс программирования. Набор готовых функций и программного кода, предоставляемых приложением. Используется программистами для интеграции сервиса со сторонними приложениями.

Документация

My

Секция отвечает за глобальные настройки пользователя, персональные данные.

В разработке...

Mailer

Секция отвечает за управление подписчиками, создание макетов, отправку писем.

Подробнее

Marketing

Секция отвечает за Конструктор Landing Page, подключение платежных систем и товары.

В разработке...

Общие положения

Описание

REST API сервиса Estismail определяет набор функций для осуществления взаимодействия по протоколу HTTP. Все ответы по умолчанию приходят в виде JSON структур. Так же возможно получать ответы в формате XML.

Авторизация

Процесс авторизации происходит с помощью персонального ключа API key, который передается с каждым запросом к API через HTTP — заголовок X-Estis-Auth. Для получения данного ключа перейдите в меню "Мой кабинет" раздел "Мои настройки" на вкладку API и нажмите кнопку «Сгенерировать».

Основной URL

Взаимодействие осуществляется с помощью HTTP запросов с параметрами в кодировке UTF-8 к URL: https://v1.estismail.com/[section]/[resource].
Обязательным является использование HTTPS соединения.

Используемые HTTP — методы:

Метод Описание
get Получение ресурса.
post Создание ресурса.
put Обновление ресурса.
delete Удаление ресурса.

Основные методы API:

Имя метода Описание
index Получение полного списка элементов ресурса.
view Получение одного элемента списка ресурсов.
add Добавление нового элемента в ресурс.
edit Редактирование элемента ресурса.
delete Удаление элемента ресурса.

Некоторые ресурсы не обязательно содержат полный набор методов. Если в определённом ресурсе метод не реализован, будет возвращена ошибка 405 Not Allowed. Подробное описание методов смотрите в спецификации конкретного ресурса.

Стандартные опциональные параметры

Методы index и view(только параметр fields) каждого из ресурсов предоставляют набор стандартных параметров для удобной выборки данных, к которым относятся:

limit - используется для задания количества отображаемых элементов. Значение по умолчанию: 10. Диапазон значений: 1 - 100. Если передан limit, выходящий за диапазон допустимых значений, устанавливается значение по умолчанию.

page - номер страницы. Если передан неправильный номер страницы, устанавливается значение по умолчанию = 1.

fields - строка в формате json, содержащая массив полей ["key1","key2", ...], которые будут выбраны для конкретного ресурса.

filter - строка в формате json, содержащая обьект вида {"key1":"value1","key2":"value2", ...}, где keyN - название N-го поля, valueN - значение N-го поля, по которым будут отфильтрованы выбираемые данные. Фильтрация проводится по точному схождению переданных значений с данными в системе.

sort_field - строка, которая содержит поле, по которому будет проводиться сортировка. Значение по умолчанию: id.

sort_direction - предоставляет возможность задать способ сортировки выбираемых данных. Доступные параметры: 1 - по возрастанию, -1 - по убыванию. Значение по умолчанию: по возрастанию.

Допустимые поля и их значения для каждого из параметров смотрите в спецификации конкретного ресурса.

Возможные статусы ответов HTTP — запросов

Код ответа Описание
Успешные
200 OK Успешный запрос. При успешном выполнении методов index и view.
201 Created В результате успешного выполнения запроса был создан новый ресурс. Используется в методе add при успешном запросе.
204 No Content Сервер успешно обработал запрос, но в ответе были переданы только заголовки без тела сообщения. Используется в методах edit и delete при успешном запросе.
Ошибки клиента
400 Bad Request Сервер обнаружил в запросе клиента синтаксическую ошибку. Неправильно переданы параметры или переданных параметров недостаточно для успешной обработки.
401Unauthorized Для доступа к запрашиваемому ресурсу требуется аутентификация. Отсутствует или неправильный HTTP-заголовок X-Estis-Auth.
404 Not Found Сервер понял запрос, но не нашёл соответствующего ресурса по указанному URI.
405 Not Allowed Указанный клиентом метод нельзя применить к текущему ресурсу.

Пример обращения к API на PHP

Пример получения списка групп подписчиков, где $apiKey - Ваш API key.


$apiKey = 'sdfhdsgfhjsgdbjhvshfkywjhgfksdjfhbkjds';
$resourceUrl = 'https://v1.estismail.com/mailer/lists';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $resourceUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
	'X-Estis-Auth: '.$apiKey
));
$response = curl_exec($ch);
curl_close($ch);