===== Общее описание ===== 

Данный **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 демонстрирует все доступные в запросе параметры.
<file 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": ""
      }
    ]
  }
</file>
==== Параметры запроса ====

**Общие параметры.**
^ Название ^ Тип ^ Обязательность ^ Описание ^ 
| template-id | string | Нет | Идентификатор шаблона для отправки сообщения | 
| priority | string | Нет | Приоритет:\\ 2 - низкий,\\ 4 - обычный,\\ 6 - высокий,\\ 8 - наивысший.\\ Если не указан, то используется 4 | 
| 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 | Нет | Параметры для отправки по соответствующему каналу |
<note>Параметры объектов timing и объектов каналов аналогичны параметрам для общей части запроса.</note>
**Параметры ответа** 
Успешный запрос имеет статус 200/OK и тела ответа ''Request is received''

===== Отправка статусов сообщений =====

URL партнера: <base-url>/status\\ 
URL партнера используется для принудительного получения статусов отправленных сообщений от СМСЦ «Play Mobile».\\ 
Статус отправляется на URL партнера, как только получим его от сотового оператора.\\ \\
**Отправка единичного статуса**
<file json status.json>
{ 
“messages”: [
        { 
“message-id”: “”, 
“channel”: “”, 
“status”: “”, 
“status-date”: “”, 
“description”: “”
        }
    ]
}
</file>\\
**Массовая рассылка статуса**
<file json status.json>
{ 
“messages”: [
        { 
“message-id”: “”, 
“channel”: “”, 
“status”: “”, 
“status-date”: “”, 
“description”: “”
        },
        { 
“message-id”: “”, 
“channel”: “”, 
“status”: “”, 
“status-date”: “”, 
“description”: “”
        }
    ]
}
</file>

**Запрос статусов возвращает следующие статусы сообщений:**\\
//Delivered// - доставлено;\\
//Transmitted// - передано оператору, от вас смс получили и отправили оператору, оператор еще не обработал, причиной может быть, когда абонент вне зоны сети или выключен. После 24 часов статус сменится на Доставлено.;\\
//NotDelivered// - недоставлено, обычно причиной может быть то что абонент блокируется со стороны оператора (недостаточно средств или долг);\\
//Rejected// - одна из основных причин в том, что номер находится в черном списке;\\
//Failed// - ошибка при отправки запроса (например когда адрес отправителя указан неверно);\\
//Expired// - срок жизни смс истек (когда абонент в течение суток не выходил на связь. У билайн если в течение часа).\\
===== Примеры =====

==== Отправка единичного сообщения ====



<file json send.json>
{
    "messages": [
      {
        "recipient": "998900000000",
        "message-id": "abc000000001",
        "sms": {
          "originator": "3700",
          "content": {
            "text": "Test message"
          }
        }
      }
    ]
  }
  </file>\\  
==== Отправка массовой рассылки ====


<file json 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"
                }
            }
        }
    ]
}
</file>
        
        
==== Отправка единичного сообщения по шаблону ====

 
<file json sendTemplate.json>
{
    "messages": [
        {
            "template-id": "111",
            "recipient": "998900000000",
            "message-id": "abc0000001",
            "variables": {
                "NAME": "IVAN",
                "SURNAME": "IVANOV"
            }
        }
    ]
} 
</file>\\
==== Отправка массовой рассылки по расписанию ====

 
<file json 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"
    }
]
}
} 
</file>\\
==== Отправка массовой рассылки по шаблону ====

<file json 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"
    }
}
]
}
</file>