Share via Share via... Twitter Facebook Telegram WhatsApp TeamsSend via e-MailPrint × Table of Contents Общее описание Аутентификация Общий формат ответа Коды ошибок Отправить сообщения Отправка статусов сообщений Примеры Общее описание Данный REST API предназначен для взаимодействия клиентов с сервером уведомлений PLAY MOBILE. Все запросы к API осуществляются по протоколу HTTP. Тело запроса передается в формате JSON. При этом необходимо устанавливать Content-type: application/json. Также в параметре charset необходимо передавать значение кодировки - UTF-8. Формат для отправки даты и времени ISO 8601. Время передается в часовом поясе UTC. Аутентификация Используется Basic аутентификация. При базовой аутентификации клиент вместе с запросом отправляет серверу логин и пароль. Эти данные отправляются в заголовке запроса Authorization в виде base64 кода. Authorization: Basic base64_encode(login:password) Так например, если логин и пароль admin, нужно добавить такой заголовок: Authorization: Basic YWRtaW46YWRtaW4= Общий формат ответа Используются HTTP ответы с соответствующими кодами. Если какая-либо переменная ответа имеет несколько значений, они формируются в виде массива. Если в запросе было несколько значений какой-либо переменной, в ответе значения будут в том же порядке. Если запрос содержит ошибку(код 400), то в теле ответа обязательно присутствует JSON-объект со следующими полями. Имя Тип Обязательность Описание error_code string да Код ошибки error_description string да Описание ошибки Коды ошибок Данные коды возвращаются при получении HTTP ответа с кодом 400. И являются значениями поля “error_code”, описанного выше. Код Описание Перевод 100 Internal server error Внутренняя ошибка сервера 101 Syntax error Синтаксическая ошибка 102 Account lock Аккаунт клиента заблокирован 103 Empty channel Не задан канал для отправки сообщений 104 Invalid priority Указано некорректное значение параметра priority 105 Too much IDs Передано слишком много идентификаторов сообщений 202 Empty recipient Адрес получателя не задан (кроме канала email) 204 Empty email address Адрес электронной почты получателя не задан (для канала email) 205 Empty message-id Идентификатор сообщения не задан 206 Invalid variables Указано некорректное значение параметра variables 301 Invalid localtime Указано некорректное значение параметра localtime 302 Invalid start-datetime Указано некорректное значение параметра start-datetime 303 Invalid end-datetime Указано некорректное значение параметра end-datetime 304 Invalid allowed-starttime Указано некорректное значение параметра allowed-starttime 305 Invalid allowed-endtime Указано некорректное значение параметра allowed-endtime 306 Invalid send-evenly Указано некорректное значение параметра send-evenly 401 Empty originator Адрес отправителя не указан 402 Empty application Приложение не указано 403 Empty ttl Значение ttl не указано (если задано несколько каналов отправки) 404 Empty content Содержимое сообщения не указано 405 Content error Неправильный формат содержимого контента 406 Invalid content Недопустимое значение контента для указанного канала 407 Invalid ttl Неправильно указано значение времени ожидания доставки 408 Invalid attached files Прикрепленные файлы имеют слишком большой объем 410 Invalid retry-attempts Неправильно указано значение количества попыток дозвона 411 Invalid retry-timeout Неправильно указано значение времени повторного дозвона Отправить сообщения Сервер Play Mobile принимает запросы от сервера клиента на URL: https://send.smsxabar.uz/broker-api/send http://91.204.239.39/broker-api/send Тело запроса Приведенный JSON демонстрирует все доступные в запросе параметры. allexample.json { "template-id": "", "priority": "", "blacklist-id": "", “timing”: { "localtime": "", "start-datetime": "", "end-datetime": "", “allowed-starttime”: “”, “allowed-endtime”: “”, "send-evenly": "" }, "sms": { “originator”: “smsSender”, “ttl”: “300”, “content”: { “text”: “Test text” } }, "call": { “originator”: “998900000000”, “ttl”: “300”, “content”: { “text”: “Test text”, “menu”: “Test”, “file”: “” }, "retry-attempts": "", "retry-timeout": "" }, "messages": [ { “recipient”: “998900000001”, “message-id”: “abc000001”, "template-id": "", "priority": "", "variables": [], “timing”: { "localtime": "", "start-datetime": "", "end- datetime": "", “allowed-starttime”: “”, “allowed-endtime”: “” }, "sms": { “originator”: “smsSender”, “ttl”: “300”, “content”: { “text”: “Test text” } }, "call": { “originator”: “998900000002”, “ttl”: “300”, “content”: { “text”: “Test text”, “menu”: “Test”, “file”: “” }, "retry-attempts": "", "retry-timeout": "" } ] } Параметры запроса Общие параметры. Название Тип Обязательность Описание template-id string Нет Идентификатор шаблона для отправки сообщения priority string Нет Приоритет: low - низкий, normal - обычный, high - высокий, realtime - наивысший. Если не указан, то используется normal timing object Нет Временные настройки sms object Нет Параметры для отправки по соответствующему каналу call object Нет Параметры для отправки по соответствующему каналу messages array Да Параметры для отправки по соответствующему каналу Параметры объекта timing. Название Тип Обязательность Описание localtime Number Нет Отправлять по местному времени 0 - получателя 1 - системы start-datetime datetime Нет Дата начала отправки. Формат YYYY-MM-DD hh:mm. Если не указана, то сообщения отправляются сразу же. end-datetime datetime Нет Дата завершения отправки. Формат YYYY-MM- DD hh:mm. Если не указана, то система не стремится отправиться все сообщения до определенного времени. allowed-starttime datetime Нет Время, с которого разрешена отправка.\\Формат hh:mm allowed-endtime datetime Нет Время, до которого разрешена отправка. Формат hh:mm send-evenly Number Нет Равномерно распределять отправку 1 - распределять 0 - не распределять Параметры объектов каналов (sms, call). Название Тип Обязательность Описание originator string Нет Адрес отправителя ttl Number Нет Время жизни сообщения в секундах. По истечении данного времени сообщению присваивается статус expired и производится отправка сообщения по альтернативному каналу, если он задана content object Нет Параметры для отправки по каналу Параметры объекта content для sms. Название Тип Обязательность Описание text string Нет Текст сообщения. Параметры объекта content для call. Название Тип Обязательность Описание text string Нет Текст сообщения для синтеза TTS, до 2000 байт (1000 символов). Используется один из трех параметров: text, file, ivrmenu. Запрос с более чем одним параметром считается некорректным. file string Нет Название аудиофайла. Используется один из трех параметров: text, file, ivrmenu. Запрос с с более чем одним параметром считается некорректным. menu string Нет Название IVR-меню. Используется один из трех параметров: text, file, ivrmenu. Запрос с с более чем одним параметром считается некорректным. retry-attempts Number Нет Количество попыток повторного звонка. Допустимы только неотрицательные числа. retry-timeout Number Нет Интервал, через который будет произведен повторный звонок, в миллисекундах Параметры элемента массива messages. Название Тип Обязательность Описание recipient string Нет Адрес получателя (как правило MSISDN), указывается строго в формате 9989xxxxxxx, без пробелов и без знака + message-id string Нет Уникальный для системы-отправителя идентификатор сообщения Должен быть уникальный для каждого отправленного или пере отправленного сообщения. Пример “abc0000001” abc = название организации. Размер поля не более 40 символов. template-id string Нет Идентификатор шаблона для отправки сообщения priority string Нет Приоритет: low - низкий, normal - обычный, high - высокий, realtime - наивысший. Если не указан, то используется normal Настраивается в личном кабинете. timing object Нет Временные настройки variables array Нет Объект параметров и их значений для подстановки в сообщение (каждый элемент представлен как запись ПАРАМЕТР:ЗНАЧЕНИЕ, например, {“PARAM1”:”VALUE1”,”PARAM2”:”VALUE2”}). sms object Нет Параметры для отправки по соответствующему каналу call object Нет Параметры для отправки по соответствующему каналу Параметры объектов timing и объектов каналов аналогичны параметрам для общей части запроса. Параметры ответа Успешный запрос имеет статус 200/OK и тела ответа Request is received Отправка статусов сообщений URL партнера: <base-url>/status URL партнера используется для принудительного получения статусов отправленных сообщений от СМСЦ «Play Mobile». Статус отправляется на URL партнера, как только получим его от сотового оператора. Отправка единичного статуса status.json { “messages”: [ { “message-id”: “”, “channel”: “”, “status”: “”, “status-date”: “”, “description”: “” } ] } Массовая рассылка статуса status.json { “messages”: [ { “message-id”: “”, “channel”: “”, “status”: “”, “status-date”: “”, “description”: “” }, { “message-id”: “”, “channel”: “”, “status”: “”, “status-date”: “”, “description”: “” } ] } Запрос статусов возвращает следующие статусы сообщений: Delivered - доставлено; Transmitted - передано оператору, от вас смс получили и отправили оператору, оператор еще не обработал, причиной может быть когда абонент вне зоны сети или выключен. После 24 часов статус сменится на Доставлено.; NotDelivered - недоставлено, обычно причиной может быть то что абонент блокируется со стороны оператора(недостаточно средст или долг); Rejected - один из основных причин это то что номер находится в черном списке; Failed - ошибка при отправки запроса(например когда адрес отправителя указан неверно); Expired - срок жизни смс истек(когда абонент в течение сутки не выходил на связь. У билайн если в теение часа). Примеры Отправка единичного сообщения send.json { "messages": [ { "recipient": "998900000000", "message-id": "abc000000001", "sms": { "originator": "3700", "content": { "text": "Test message" } } } ] } Отправка массовой рассылки sendMas.json { "messages": [ { "recipient": "9989хххххххх", "message-id": "abc00000001", "sms": { "originator": "3700", "content": { "text": "Test text" } } }, { "recipient": "9989xxxxxxxx", "message-id": "abc00000002", "sms": { "originator": "3700", "content": { "text": "Test text 1" } } }, { "recipient": "998970000000", "message-id": "abc00000003", "sms": { "originator": 3700, "content": { "text": "Test text 2" } } } ] } Отправка единичного сообщения по шаблону sendTemplate.json { "messages": [ { "template-id": "111", "recipient": "998900000000", "message-id": "abc0000001", "variables": { "NAME": "IVAN", "SURNAME": "IVANOV" } } ] } Отправка массовой рассылки по расписанию sendTiming.json {priority": "", "timing": {"localtime": "true", "start-datetime": "2017-11-05 10-00", "end-datetime": "2017-11-25 19-00", "allowed-starttime'""': "10-00 ","allowed-endtime": "19-00""send-evenly": "false" }, "sms": { "originator": "smsSender", "content": { "text": "Test text" } }, "messages": [ { "recipient": "998900000000", "message-id": "abc00000145" }, { "recipient": "998900000001", "message-id": "abc00000146" } ] } } Отправка массовой рассылки по шаблону sendMasTemplate.json { "template-id": "112", "messages": [ { "recipient": "998900000000", "message-id": "abc000001", "variables": { "NAME": "IVAN", "SURNAME": "IVANOV" } }, { "recipient": "998900000001", "message-id": "abc000002", "variables": { "NAME": "PETR", "SURNAME": "KUZIN" } }, { "recipient": "998900000002", "message-id": "abc000003", "variables": { "NAME": "VLADIMIR", "SURNAME": "NESTEROV" } } ] } Last modified: 23 months ago