Профит-Групп

Инструменты пользователя

Инструменты сайта

Вы находитесь здесь: start » profitgroup » projects » kmis » sms
profitgroup:projects:kmis:sms

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

В качестве клиента используем бесплатную программу SOAP UI, но принцип работы сохраняется и при использовании других продуктов. В том числе и при разработке ПО на .NET (Microsoft придумала стандарт SOAP и их средства как никакие другие подходят для этого). Программа существует под все популярные платформы и не имеет ограничений использования.

Руководство по программе можно найти на официальном сайте

В SOAP UI создаём новый проект и в качестве Initial WSDL используем ссылку из документации: http://kmis.callbox.biz/?wsdl

В этот момент SOAP UI (как и библиотека .NET) выгрузит из WSDL все приложения. Их три:

  1. get_report - получение статистики
  2. notification - оповещение абонента
  3. upload_audio - загрузка файла на сервис

Также программа выгрузит все методы для всех приложений. На текущий момент в каждом приложении 1 метод.

При переходе к редактированию метода Request приложения notification откроется полный текст запроса с комментариями к нему: 

<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>

Вопросительные знаки требуют ввода данных.

Метод описывает сразу три возможных оповещения: посылка СМС (раздел sms_notifications), звонок абоненту с зачитыванием текста (ts_notifications) и звонок абоненту с проигрыванием файла (audio_notifications). В запросе должен быть использовано хотя бы одно оповещение. При этом, можно в одном запросе рассылать оповещения всех типов разным абонентам.

Нас интересует СМС оповещение. Для его создания удаляем из запроса секции ts_notification и audio_notification и приводим запрос к виду: 

<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>

Далее необходимо построчно заполнить данный запрос.
Первая строка с вопросительным знаком идентифицирует пользователя системы: 

<core:customer_id>?</core:customer_id>

Вместо вопросительного знака необходимо в данную строку подставить UUID, выданный администратором системы. Пример корректного заполнения: 

<core:customer_id>394ffb3b-20f5-4046-b6b2-758103698fe7</core:customer_id>

Вторая строка с вопросительным знаком идентифицирует запрос. 

<core:request_id>?</core:request_id>

В данную строку необходимо сгенерить и подставить UUID. В случае дублирование UUID (некорректная генерация) сервер выдаст сообщение об ошибке. Пример корректного заполнения: 

<core:request_id>edeb4385-a7c5-4b1e-862c-bbf4b8b73abe</core:request_id>

Следующая строка с вопросительным знаком, требующая заполнения определяет номер телефона пользователя, на который будет выслана СМС. Номер принимается в формате Е164. В качестве исключения код страны +7 может быть заменён на 8. При этом в данном случае в системе номер будет преобразован в формат Е164 и отчётная информация будет выводится именно по такому номеру. 

<core:recipient_phone>?</core:recipient_phone>

Пример корректного заполнения: 

<core:recipient_phone>+77778897158</core:recipient_phone>

Следующая строка, требующая заполнения определяет является ли рассылка персонализированной или нет. 

<core:is_personalized>?</core:is_personalized>

Данное поле обязательно для заполнения (комментарий Optional перед ним в WSDL введён на момент отладки системы). В случае, если флаг установлен в False сообщение отсылается в том виде, в каком оно передано в запросе. В случае, если флаг установлен в True система воспринимает передаваемый текст как шаблон и ищет в запросе поля для его заполнения. Корректно заполнение поля для рассылки не адресной СМС: 

<core:is_personalized>false</core:is_personalized>

Следующая строка, требующая заполнения определяет дату начала рассылки. 

<core:date_begin>?</core:date_begin>

Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения (показана дата в прошлом на момент написания статьи): <core:date_begin>2017-08-01</core:date_begin> Следующая строка, требующая заполнения определяет дату окончания рассылки. 

<core:date_end>?</core:date_end>

Дата указывается в формате YYYY-MM-DD и может быть произвольной. При этом хотя бы один день из диапазона дат должен быть в будущем. Пример корректного заполнения: 

<core:date_end>2017-08-03</core:date_end>

Следующие две строки, требующие заполнения определяют время начала и время окончания рассылки. Временной интервал применяется к одним суткам. То есть, например, если нам необходимо пытаться разослать сообщение каждый день только с полудня и до конца рабочего дня то в данных полях можно указать 12:00:00 и 17:00:00 и во вне этого интервала рассылка проводиться не будет. 

<core:start_time>?</core:start_time>
<core:end_time>?</core:end_time>

При этом если время начала больше чем время окончания рассылки (например, с 18:00:00 до 09:00:00) то система проверяет что диапазон дат содержит несколько дней и будет осуществлять рассылку в ночное время.
Указание временного диапазона необязательно. В случае, если временной диапазон не указан, то рассылка подразумевается с 9:00:00 до 17:00:00. Пример корректного заполнения: 

<core:start_time>00:00:00</core:start_time>
<core:end_time>23:59:59</core:end_time>

Следующая строка содержит текст непосредственно отправляемого сообщения 

<core:message_template>?</core:message_template>

В случае, если указан флаг персональных сообщений данная строка воспринимается как шаблон. Описание шаблона смотрите в полной документации к работе сервера. Пример корректного заполнения: 

<core:message_template>Проверочная СМС.</core:message_template>

Следующая строка определяет количество попыток доставки СМС до абонента. Данные попытки не определяют работу оператора связи. Система переходит к следующей попытке только после получения сообщения «не доставлено» от оператора связи. 

<core:attempt_count>?</core:attempt_count>

Параметр может принимать любое целочисленное значение от 0 до 65535. Указание параметра не обязательно. В случае, если параметр не указан система предпримет одну попытку доставки сообщения. Пример корректного заполнения: 

<core:attempt_count>3</core:attempt_count>

Итого, с учётом всех необязательных полей простейшей запрос для отправки СМС будет иметь следующий вид: 

<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>
profitgroup/projects/kmis/sms.txt · Последнее изменение: 2021/04/15 11:14 — m.zhanagulov