====== Краткое пошаговое руководство по работе с сервисом отправки СМС сообщений ======

В качестве клиента используем бесплатную программу [[https://www.soapui.org|SOAP UI]], но принцип работы сохраняется и при использовании других продуктов. В том числе и при разработке ПО на .NET ([[https://en.wikipedia.org/wiki/SOAP#History|Microsoft придумала стандарт SOAP]] и их средства как никакие другие подходят для этого). Программа существует под все популярные платформы и не имеет ограничений использования.\\
\\
Руководство по программе можно найти [[https://www.soapui.org/soap-and-wsdl/getting-started.html|на официальном сайте]]\\
\\
В SOAP UI создаём новый проект и в качестве Initial WSDL используем ссылку из [[products:kmis:project_documentation:server|документации]]: [[http://kmis.callbox.biz/?wsdl]]\\
\\
В этот момент SOAP UI (как и библиотека .NET) выгрузит из WSDL все приложения. Их три:
  - //get_report// - получение статистики
  - //notification// - оповещение абонента
  - //upload_audio// - загрузка файла на сервис

Также программа выгрузит все методы для всех приложений. На текущий момент в каждом приложении 1 метод.\\
\\
При переходе к редактированию метода //Request// приложения //notification// откроется полный текст запроса с комментариями к нему:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:ser="services.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <ser:customer_id>?</ser:customer_id>
            <!--Optional:-->
            <ser:sms_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataSMS>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                        <ser:is_personalized>?</ser:is_personalized>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
                     </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:message_template>?</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataSMS>
            </ser:sms_notifications>
            <!--Optional:-->
            <ser:ts_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataReadText>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                        <ser:is_personalized>?</ser:is_personalized>
                        <!--Optional:-->
                        <ser:template_parameters>
                           <!--1 or more repetitions:-->
                           <ser:TemplateParameter>
                              <ser:key>?</ser:key>
                              <ser:value>?</ser:value>
                           </ser:TemplateParameter>
                        </ser:template_parameters>
                     </ser:RecipientData>
                  </ser:recipients_data>
                  <ser:message_template>?</ser:message_template>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataReadText>
            </ser:ts_notifications>
            <!--Optional:-->
            <ser:audio_notifications>
               <!--1 or more repetitions:-->
               <ser:UserDataAudio>
                  <ser:date_begin>?</ser:date_begin>
                  <ser:date_end>?</ser:date_end>
                  <!--Optional:-->
                  <ser:start_time>?</ser:start_time>
                  <!--Optional:-->
                  <ser:end_time>?</ser:end_time>
                  <ser:recipients_data>
                     <!--1 or more repetitions:-->
                     <ser:RecipientBaseData>
                        <ser:request_id>?</ser:request_id>
                        <ser:recipient_phone>?</ser:recipient_phone>
                     </ser:RecipientBaseData>
                  </ser:recipients_data>
                  <ser:audio_record_id>?</ser:audio_record_id>
                  <!--Optional:-->
                  <ser:attempt_count>?</ser:attempt_count>
               </ser:UserDataAudio>
            </ser:audio_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>
Вопросительные знаки требуют ввода данных.\\
\\
Метод описывает сразу три возможных оповещения: посылка СМС (раздел sms_notifications), звонок абоненту с зачитыванием текста (ts_notifications) и звонок абоненту с проигрыванием файла (audio_notifications). В запросе должен быть использовано хотя бы одно оповещение. При этом, можно в одном запросе рассылать оповещения всех типов разным абонентам.\\
\\
Нас интересует СМС оповещение. Для его создания удаляем из запроса секции ts_notification и audio_notification и приводим запрос к виду:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:core="core.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <core:customer_id>?</core:customer_id>
            <!--Optional:-->
            <core:sms_notifications>
               <!--1 or more repetitions:-->
               <core:UserDataSMS>
                  <core:recipients_data>
                     <!--1 or more repetitions:-->
                     <core:RecipientData>
                        <core:request_id>?</core:request_id>
                        <core:recipient_phone>?</core:recipient_phone>
                        <!--Optional:-->
                        <core:is_personalized>?</core:is_personalized>
                     </core:RecipientData>
                  </core:recipients_data>
                  <core:date_begin>?</core:date_begin>
                  <core:date_end>?</core:date_end>
                  <!--Optional:-->
                  <core:start_time>?</core:start_time>
                  <!--Optional:-->
                  <core:end_time>?</core:end_time>
                  <core:message_template>?</core:message_template>
                  <!--Optional:-->
                  <core:attempt_count>?</core:attempt_count>
               </core:UserDataSMS>
            </core:sms_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>

Далее необходимо построчно заполнить данный запрос.\\
Первая строка с вопросительным знаком идентифицирует пользователя системы:
<code><core:customer_id>?</core:customer_id></code>
Вместо вопросительного знака необходимо в данную строку подставить UUID, выданный администратором системы. Пример корректного заполнения:
<code><core:customer_id>394ffb3b-20f5-4046-b6b2-758103698fe7</core:customer_id></code>
Вторая строка с вопросительным знаком идентифицирует запрос.
<code><core:request_id>?</core:request_id></code>
В данную строку необходимо сгенерить и подставить UUID. В случае дублирование UUID (некорректная генерация) сервер выдаст сообщение об ошибке. Пример корректного заполнения:
<code><core:request_id>edeb4385-a7c5-4b1e-862c-bbf4b8b73abe</core:request_id></code>
Следующая строка с вопросительным знаком, требующая заполнения определяет номер телефона пользователя, на который будет выслана СМС. Номер принимается в формате Е164. В качестве исключения код страны +7 может быть заменён на 8. При этом в данном случае в системе номер будет преобразован в формат Е164 и отчётная информация будет выводится именно по такому номеру.
<code><core:recipient_phone>?</core:recipient_phone></code>
Пример корректного заполнения:
<code><core:recipient_phone>+77778897158</core:recipient_phone></code>
Следующая строка, требующая заполнения определяет является ли рассылка персонализированной или нет.
<code><core:is_personalized>?</core:is_personalized></code>
Данное поле обязательно для заполнения (комментарий Optional перед ним в WSDL введён на момент отладки системы). В случае, если флаг установлен в False сообщение отсылается в том виде, в каком оно передано в запросе. В случае, если флаг установлен в True система воспринимает передаваемый текст как шаблон и ищет в запросе поля для его заполнения. Корректно заполнение поля для рассылки не адресной СМС:
<code><core:is_personalized>false</core:is_personalized></code>
Следующая строка, требующая заполнения определяет дату начала рассылки.
<code><core:date_begin>?</core:date_begin></code>
Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения (показана дата в прошлом на момент написания статьи):
<core:date_begin>2017-08-01</core:date_begin>
Следующая строка, требующая заполнения определяет дату окончания рассылки.
<code><core:date_end>?</core:date_end></code>
Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения:
<code><core:date_end>2017-08-03</core:date_end></code>
Следующие две строки, требующие заполнения определяют время начала и время окончания рассылки. Временной интервал применяется к одним суткам. То есть, например, если нам необходимо пытаться разослать сообщение каждый день только с полудня и до конца рабочего дня то в данных полях можно указать 12:00:00 и 17:00:00 и во вне этого интервала рассылка проводиться не будет.
<code>
<core:start_time>?</core:start_time>
<core:end_time>?</core:end_time>
</code>
При этом если время начала больше чем время окончания рассылки (например, с 18:00:00 до 09:00:00) то система проверяет что диапазон дат содержит несколько дней и будет осуществлять рассылку в ночное время.\\
Указание временного диапазона необязательно. В случае, если временной диапазон не указан, то рассылка подразумевается с 9:00:00 до 17:00:00. Пример корректного заполнения:
<code>
<core:start_time>00:00:00</core:start_time>
<core:end_time>23:59:59</core:end_time>
</code>
Следующая строка содержит текст непосредственно отправляемого сообщения
<code><core:message_template>?</core:message_template></code>
В случае, если указан флаг персональных сообщений данная строка воспринимается как шаблон. Описание шаблона смотрите в полной документации к работе сервера. Пример корректного заполнения:
<code><core:message_template>Проверочная СМС.</core:message_template></code>
Следующая строка определяет количество попыток доставки СМС до абонента. Данные попытки не определяют работу оператора связи. Система переходит к следующей попытке только после получения сообщения "не доставлено" от оператора связи.
<code><core:attempt_count>?</core:attempt_count></code>
Параметр может принимать любое целочисленное значение от 0 до 65535. Указание параметра не обязательно. В случае, если параметр не указан система предпримет одну попытку доставки сообщения. Пример корректного заполнения:
<code><core:attempt_count>3</core:attempt_count></code>
Итого, с учётом всех необязательных полей простейшей запрос для отправки СМС будет иметь следующий вид:
<code>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:kmis="kmis.services" xmlns:core="core.custom_types">
   <soapenv:Header/>
   <soapenv:Body>
      <kmis:notification>
         <kmis:request_data>
            <core:customer_id>394ffb3b-20f5-4046-b6b2-758103698fe7</core:customer_id>
            <!--Optional:-->
            <core:sms_notifications>
               <!--1 or more repetitions:-->
               <core:UserDataSMS>
                  <core:recipients_data>
                     <!--1 or more repetitions:-->
                     <core:RecipientData>
                        <core:request_id>1beb9345-383a-422c-a67e-a4681e69be40</core:request_id>
                        <core:recipient_phone>+77778897158</core:recipient_phone>
                        <core:is_personalized>false</core:is_personalized>
                     </core:RecipientData>
                  </core:recipients_data>
                  <core:date_begin>2017-08-01</core:date_begin>
                  <core:date_end>2017-08-03</core:date_end>
                  <core:message_template>Тестовая СМС</core:message_template>
               </core:UserDataSMS>
            </core:sms_notifications>
         </kmis:request_data>
      </kmis:notification>
   </soapenv:Body>
</soapenv:Envelope>
</code>