Документация (REST API)

Push-рассылки

Коды ошибок и их описание

Вступление

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

Библиотеки API и примеры использования

Описание

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

Основной URL

Все ссылки на запросы к API в данной документации включают обязательный основной URL:
//api.sendmps.com

Авторизация

Процесс авторизации возможен при наличии персонального ключа, которым в дальнейшем должен быть подписан каждый запрос к API.

Необходимые для получения ключа параметры можно найти в настройках личного кабинета
//sendmps.com/settings на вкладке API.

Используются параметры:

grant_type должен быть равен client_credentials
client_id ваш ID (API)
client_secret ваш секрет (API)

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

//api.sendmps.com/oauth/access_token

Полученный ключ действителен в течение 1 часа и не требует повторного запроса при каждой операции. По истечении срока действия ключа (1 час) необходимо отправить повторный запрос на получение ключа.

Пример ответа:

{
  "access_token": "tf4si1lydyptapyhxugjig72jlrd5hpijl5oigmc",
  "token_type": "bearer",
  "expires_in": 3600
}

Пример ключа:

authorization: bearer tf4si1lydyptapyhxugjig72jlrd5hpijl5oigmc

Push-рассылки

Получить список отправленных push кампаний

Для просмотра списка отправленных push кампаний отправляется GET запрос по ссылке

//api.sendmps.com/push/tasks

Параметры запроса:

limit количество записей которое нужно взять
offset смещение

Пример URL запроса при передаче дополнительных параметров:

//api.sendmps.com/push/tasks/?limit=10&offset=2

Взять 10 записей, начиная со второй

Пример ответа:

[
  {
    "id": "121",
    "title": "push title",
    "body": "push text",
    "website_id": "53",
    "send_date": "2015-12-17 14:44:47",
    "status": "13"
  }
]

Получить общее количество сайтов

Для просмотра общего количества сайтов отправляется GET запрос по ссылке

//api.sendmps.com/push/websites/total

Пример ответа:

{
  "total": 2
}

Получить список сайтов

Чтобы получить список сайтов, нужно отправить GET запрос по ссылке

//api.sendmps.com/push/websites/

Параметры запроса:

limit количество записей которое нужно взять
offset смещение

Пример URL запроса при передаче дополнительных параметров:

//api.sendmps.com/push/websites/?limit=10&offset=2

Пример ответа:

[
  {
    "id": "53",
    "url": "www.test-site.com",
    "add_date": "2015-11-23 14:42:37",
    "status": "1"
  }
]

Получить список переменных для сайта

Чтобы получить список всех переменных для данного сайта, следует отправить GET запрос по ссылке

//api.sendmps.com/push/websites/{id}/variables

Параметры запроса:

{id} идентификатор сайта

Пример ответа:

[
  {
    "id": "97",
    "name": "uname",
    "type": "string"
  }
]

Получить список подписчиков сайта

Чтобы получить список подписчиков для конкретного сайта, необходимо отправить GET запрос по ссылке

//api.sendmps.com/push/websites/{id}/subscriptions

Параметры запроса:

{id} идентификатор сайта (обязательный)
limit количество записей которое нужно взять
offset смещение

Пример URL запроса при передаче дополнительных параметров:

//api.sendmps.com/push/websites/{id}/subscriptions/?limit=10&offset=2

Пример ответа:

[
  {
    "id": "1",
    "browser": "chrome",
    "lang": "ru",
    "variables": [],
    "status": "0"
  }
]

Получить количество подписчиков сайта

Чтобы получить общее число подписчиков для сайта, нужно отправить GET запрос по ссылке

//api.sendmps.com/push/websites/{id}/subscriptions/total

Параметры запроса:

{id} идентификатор сайта (обязательный)

Пример ответа:

{
  "total": 2
}

Активировать/Деактивировать подписчика

Для того, чтобы активировать или деактивировать подписчика, нужно отправить POST запрос по ссылке

//api.sendmps.com/push/subscriptions/state

Параметры запроса (обязательные):

{id} идентификатор подписчика
state тригер переключения состояния подписчика, 1 – активен, 0 – деактивирован

Пример ответа:

{
  "result": true
}

Создать новую push-рассылку

Чтобы создать новую push-рассылку, нужно отправить POST запрос по ссылке

//api.sendmps.com/push/tasks

Обязательные параметры запроса:

title заголовок
website_id идентификатор сайта
body тело рассылки
ttl время жизни push рассылки

Необязательные параметры запроса:

link ссылка для перехода, если не указана будет взята ссылка сайта
filter_lang фильтрация подписчиков по языку (пример ru)
filter_browser фильтрация по браузеру, может принимать несколько значений разделенных запятой (пример – Chrome,Safari)
filter сегментация по одной из переменных
stretch_time время, в течение которого рассылается push-рассылка. Указывается в секундах. Если не указано, используется время по умолчанию (5 часов).

Пример структуры параметра filter:

{
  "variable_name": "uname",
  "operator": "or",
  "conditions": [
    {
      "condition": "likewith",
      "value": "a"
    },
    {
      "condition": "notequal",
      "value": "b"
    }
  ]
}

где:

variable_name имя переменной
operator соединяющий оператор, может принимать значения только or или and
conditions массив условий
condition может принимать следующие значения
equal полностью равно
notequal полностью не равно
greaterthan больше чем
lessthan меньше чем
startwith начинается с
endwith заканчивается этим значением
likewith содержит в себе
notlikewith не содержит в себе

Пример ответа сервера при успешном создании кампании:

{
  "result": true,
  "id": 1
}


Статистика по отправленным рассылкам

Чтобы получить статистику по отправленным web push рассылкам, нужно отправить GET запрос по ссылке

//api.sendmps.com/push/tasks/{id}

Параметры запроса:

{id} id push рассыки

Пример ответа сервера при успешном получении статистики:

{
"id": "36",
"message": {
"title": "s",
"text": "s",
"link": "http://aaa.aaa"
},
"website": "www.google.com",
"website_id": 53,
"status": 3,
"send": "21",
"delivered": "14",
"redirect": "13"
}


Для получения статуса подписки, можно использовать следующие собятия:


window.addEventListener('pushSubscribe', function (e) {
    console.log(' * push Subscribe', e.detail, e);
    // send ajax for save subscribe info
});


window.addEventListener('pushUnSubscribe', function (e) {
    console.log(' * push UnSubscribe ', e.detail, e);
    // send ajax for save subscribe info
});

Коды ошибок и их описание

Код ошибки Описание
1 Over errors
2 Only POST requests are accepted
5 SQL error
8 Missing required params
9 Incorrect request parameters
100 Access denied - invalid private key
101 Access denied - invalid site ID
103 Error push data save
104 Subscriber unsubscribed
105 Subscriber not found
106 Cant send push to subscriber
107 Over limit: one message for last 180 sec/
108 Over limit: subscriber not read yet last 3 message for last 12 hours
109 Over limit: mobile subscriber not read yet last 3 message for last 12 hours
110 Hello config not set!
111 Wrong ids!

Ограничения на отправку сообщений PUSH