Описание REST API, изменения версии 1.1. Все изменения выделены зеленым цветом.
В версии 1.1 сюда впервые добавляется работа с короткими ссылками, которая реализуется через новый параметр в JSON – options, который является необязательным. Имейте в виду, что вызовы api версии 1.0 будут игнорировать данные параметры.
options представляет собой массив дополнительных настроек сообщения. В версии 1.1 мы представляем опцию short_links, которая позволяет слать с помощью смс длинные ссылки с предварительной обфускацией через короткую ссылку для экономии количества символов в смс. В итоге, options представляет собой следующую структуру:
[
{"short_links": [
{"link_name_1": {"long_url": "https://bsg.world", "scheme":"https"}},
{"link_2": {"long_url": "http://google.com", "scheme":"https"}}
]}
]
Разберем данные параметры.
short_links – массив, описывающий замену коротких ссылок в тексте. Выглядит как массив ключ-значение, где ключ потом будет искаться в тексте сообщения. Для примера выше, в тексте будет искаться строки {{link_name_1}} и {{link_2}} , которые потом будут заменены на полученные короткие ссылки. Если по какой-то причине одной или более строки не будет найдено в тексте сообщения, то будет сгенерирована ошибка 13.
{"link_name_1": {"long_url": "https://bsg.world", "scheme":"https"}
Для данной записи будет применена следующая логика:
- Будет сгенерирована короткая ссылка, по нажатию на которую будет переход на https://bsg.world
- Ссылка, начинающаяся с https:// , будет вставлена в текст смс вместо строки {{link_name_1}}
long_url – оригинальная ссылка, куда будет переход с короткой
scheme – определяет, будет короткая ссылка в тексте сообщения начинаться с http или же с https.
Отправка SMS
PUT (поддерживается так же и POST) /sms/create
Поддерживается создание одиночной смс("destination":"phone"), массовой рассылки("destination":"phones") и индивидуальных смс (("destination":"individual"). В будущем будет добавлена возможность создать по API рассылку с адресной книги("destination":"addresbook").
Передаваемый параметр payload для "destination":"phone" содержащий JSON-encoded массив следующей структуры:
{"originator ":"test",
"body":"test sms",
"validity": "1",
"tariff":"0",
"destination":"phone",
"msisdn": "380972000000",
"reference":"12erdgm9",
"send_time" : "ISO 8601 date",
"options":[]}
destination – устанавливается в значение "phone"
originator — отправитель. Строка до 14 символов.
body — текст сообщения. Текст
msisdn – номер телефона, на который отправляется sms
reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/
validity — время действия смс (по умолчанию — 72 часа). Целое число от 1 до 72
tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.
send_time – время отправки смс (для планирования смс рассылок)
options – массив опций для рассылки. Структура рассмотрена в начале документа.
Пример правильного ответа:
{"error":"0",
"id":"22125"",
"reference":"12erdgm9",
"price":"0.02",
"currency":"EUR"}
В случае наличия ошибки в запросе:
{"error":"11",
"errorDescription":"Incorrect msisdn"}
Для случая destination = phones
{"originator":"test",
"body":"test sms",
"validity": "1",
"tariff":"0",
"destination":"phones",
"phones":[{"msisdn":
"380972000001",
"reference":"12erdgm9"},
{"msisdn":
"380972000002",
"reference":"12erdgn0"}],
"send_time" : "ISO 8601 date",
"options":[]}
передаются следующие параметры (курсивом выделены необязательные):
destination – устанавливается в значение "phones"
originator — отправитель. Строка до 14 символов.
body — текст сообщения. Текст
validity — время действия смс (по умолчанию — 72 часа). Целое число от 1 до 72
tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.
phones – массив значений:
msisdn – номер телефона, на который отправляется sms
reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/
send_time – время отправки смс (для планирования смс рассылок)
options – массив опций для рассылки. Структура рассмотрена в начале документа.
В этом случае пример правильного ответа:
{"result":
[{"reference":"12erdgm9",
"id":"12345",
"error":"0",
"price":"0.02",
"currency":"EUR"},
{"reference":"12erdgn0",
"id":"12346",
"error":"0",
"price":"0.02",
"currency":"EUR"}],"error":"0", "totalprice":"0.04","currency":"EUR","task_id":"21902"}
Параметра task_id служит для запроса статуса по всей рассылке
При ошибке в данных будет возвращен ответ примерно такого вида
{"error":"25","errorDescription":"Invalid originator"}
Для случая destination = individual
{"validity": "1",
"tariff":"0",
"destination":"individual",
"phones":
[{"originator":"test1",
"body":"test sms1",
"msisdn": "380972000001",
"reference":"12erdgm9",
"options":[]},
{"originator":"test2",
"body":"test sms2",
"msisdn": "380972000002",
"reference":"12erdgn0",
"options":[]}],
"scheduledDatetime" : "ISO 8601 date"}
передаются следующие параметры (курсивом выделены необязательные):
destination – устанавливается в значение "phones"
validity — время действия смс (по умолчанию — 72 часа). Целое число от 1 до 72
tariff — номер тарифа. По умолчанию — 0. Целое число от 0 до 9.
phones – массив значений:
msisdn – номер телефона, на который отправляется sms
reference — внешний id sms. Строка до 32 символов, содержащих /a-zA-Z0-9/
originator — отправитель. Строка до 14 символов.
body — текст сообщения. Текст
scheduledDatetime – время отправки смс (для планирования смс рассылок)
options – массив опций для рассылки. Структура рассмотрена в начале документа.
В этом случае пример правильного ответа:
{"result":[{"reference":"12erdgm9",
"id":"12345","error":"0",
"price":"0.02",
"currency":"EUR"},
{"reference":"12erdgn0",
"id":"12346",
"error":"0",
"price":"0.02",
"currency":"EUR"}],
"error":"0",
"totalprice":"0.04",
"currency":"EUR",
"task_id":"21902"}
Параметра task_id служит для запроса статуса по всей рассылке
При ошибке в данных будет возвращен ответ примерно такого вида
{"error":"24",
"errorDescription":"Invalid request payload"}
Получение цены смс
PUT (поддерживается так же и POST) /sms/price
Параметры аналогичные отправке смс. В ответ может быть получена одна из ошибок или структура следующего содержания:
{error":"0",
"totalprice":"0.004",
"currency":"EUR"}
Получение статусов смс
GET /sms/{id}
Где {id} – id записи, полученной из метода /sms/create
GET /sms/reference/{reference}
Где {reference} – внешний id сообщения
В ответ будет получен JSON примерно следующей структуры:
{ "error":"0","msisdn": "380972000000",
"reference":"12erdgm9",
"time_in":"2016-01-01 00:00:01",
"time_sent":"2016-01-01 00:00:02",
"time_dr":"2016-01-01 00:01:01",
"status":" delivered ",
"price":"0.02",
"currency":"EUR"}
При ошибке в данных будет возвращен ответ примерно такого вида
{"error":"20",
"errorDescription":"SMS not found"}
Для смс, которые были созданы с ключом destination = phones, можно запрашивать расширенную статистику:
GET /sms/task/{id}
Где {id} – task_id из ответа
В ответ будет получен JSON примерно следующей структуры:
{"error":"0",
"originator ":"test",
"body":"test sms",
"validity": "1",
"sent":"2",
"delivered":"1",
"undeliverable":"1",
"expired": "0",
"unknown":"0",
"totalprice":"0.04",
"currency":"EUR"
}
При ошибке в данных будет возвращен ответ примерно такого вида
{"error":"30",
"errorDescription":"Task not found"}
Получение таблицы цен SMS
GET /sms/prices/{tariff}
Необязательный параметр tariff указывает номер тарифной сетки. По умолчанию (в случае отсутствия) он принимается равным 0 (Global tariff)
Пример правильного ответа:
{"error":"0",
"prices":[
{"type":"sms",
"country":" AE",
"country_name":"United Arab Emirates",
"mcc":" 424",
"price":"0.02",
"currency":"EUR"},":
[{"type":"sms",
"country":" AF",
"country_name":"Afghanistan",
"mcc":" 412",
"price":"0.05",
"currency":"EUR"}]}
В ответе будут перечислены все страны, для которых возможа отправка sms-сообщений, вместе с ценами.
В случае наличия ошибки в запросе:
{"error":"6",
"errorDescription":"Invalid tariff code"}
Приложение 1. Коды ошибок
Общие ошибки (0-9)
0 – нет ошибки
1 – неверный ключ
3 – пользователь заблокирован
2 – недостаточно параметров
4 – запрашиваемая функция не поддерживается
5 – неизвестная ошибка
6 – указан несуществующий номер тарифной сетки
7 – неверные параметры
8 – недостаточно денег
9 – тарифная сетка неактивна
10 – неверное время отправки
11 – превышено максимальное число одновременно обрабатываемых на отправку сообщений
12 – превышен максимальный размер пакета сообщений
13 – несоответствие количества опций short_links и переменных в тексте sms.
Ошибки SMS (20-39)
20 — SMS не найдена
21 — неверный номер телефона
22 – отсутствует внешний ID SMS-запроса
23 – SMS с таким ID уже присутствует
24 – неверный payload запроса
25 — неверный originator
26 — пустой или слишком длинный текст смс
27 — неверный внешний ID SMS
28 — неверное значение времени действия SMS
29 – id задачи неверный
30 – задача не найдена
31 – телефон уже присутствует в рассылке
32- sender not allowed
Комментарии
0 комментариев
Статья закрыта для комментариев.