Создание модулей шлюзов сообщений

Модули шлюзов сообщений интегрируют платформу BILLmanager с внешними сервисами для отправки уведомлений (SMS, email, мессенджеры). Платформа вызывает эти модули напрямую или через модули уведомлений.

Модуль шлюза сообщений отвечает за:

• набор настроек подключения к внешнему сервису;
• внешний вид формы настроек шлюза в интерфейсе платформы;
• форматирование и передачу исходящих сообщений во внешнюю систему;
• приём входящих сообщений от внешнего сервиса.

Общие сведения

Каталог установки: /usr/local/mgr5/gate/ или /usr/local/mgr5/addon/.
XML-описание: /usr/local/mgr5/etc/xml/billmgr_mod_gw<имя>.xml.

Управление: основной скрипт модуля (gwXXX).

Платформа опрашивает каждый модуль при запуске, чтобы узнать о поддерживаемых возможностях и необходимых параметрах. Это ускоряет работу: исключаются неподдерживаемые вызовы и определяется поведение форм при настройке шлюза.

Механизм работы модуля

Этапы работы с модулем платёжной системы в BILLmanager:

1. Первоначальная настройка:
   1. Установка модуля.
   2. Добавление шлюза в разделе платформы.
2. Взаимодействие с внешней системой:
   1. Настройка параметров подключения и проверка соединения. Подробнее см. статьи раздела Система уведомлений.
   2. Инициация отправки сообщения платформой.
   3. Обработка ответа внешнего сервиса и обновление статуса задачи на отправку.

Установите модуль:

• вручную, если он представлен набором файлов;
• из стандартного репозитория при помощи пакетного менеджера.

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

Структура модуля

Модуль шлюза сообщений состоит из XML-описания и исполняемого скрипта. При необходимости добавляются CGI-скрипты для приёма входящих сообщений.

Стандартный список файлов модуля выглядит следующим образом:

Где XXX — название модуля, которое указывается латиницей. Если название основного скрипта модуля содержит расширение файла, оно также включается в имя модуля. Например, если ваш скрипт называется gwsms.php, то имя модуля — sms.php, а не sms.

Описание XML

Наименование файла должно иметь вид billmgr_mod_gwXXX.xml, где XXX — имя модуля. Файл копируется в каталог /etc/xml относительно пути установки BILLmanager. Файл содержит описание самого модуля (описывается как плагин), а также описание дополнительных форм и сообщений.

<mgrdata>
  <plugin name="XXX">
    <group>gateway</group>
    <msg name="desc_short" lang="ru">Шлюз XXX</msg>
    <msg name="desc_short" lang="en">XXX gateway</msg>
    <msg name="desc_full" lang="ru">Интеграция с сервисом XXX для отправки сообщений</msg>
    <msg name="desc_full" lang="en">Integration with XXX service for sending messages</msg>
  </plugin>

  <metadata name="gateway.XXX" type="form">
    <form>
      <page name="settings">
        <field name="api_url">
          <input name="api_url" type="text" check="url" required="yes"/>
        </field>
        <field name="api_key">
          <input name="api_key" type="text" private="yes" crypted="yes" required="yes"/>
        </field>
      </page>
    </form>
  </metadata>

  <lang name="ru">
    <messages name="gateway.XXX">
      <msg name="api_url">URL API</msg>
      <msg name="hint_api_url">Адрес конечной точки API провайдера</msg>
      <msg name="api_key">Ключ API</msg>
      <msg name="hint_api_key">Секретный ключ для авторизации запросов</msg>
    </messages>
    <messages name="gateway_include">
      <msg name="module_gwXXX">Шлюз XXX</msg>
      <msg name="gwXXX">Шлюз XXX</msg>
      <msg name="desc_gwXXX">Отправка уведомлений через сервис XXX</msg>
    </messages>
    <messages name="msgerror">
      <msg name="msg_error_connection_failed">Не удалось установить соединение с шлюзом</msg>
      <msg name="msg_error_invalid_key">Неверный ключ API</msg>
    </messages>
  </lang>
</mgrdata>

Здесь элемент <plugin> отвечает за описание самого модуля. Свойство name совпадает с именем модуля. Внутри элемента может быть один элемент group со значением gateway, который указывает, что данный модуль используется для шлюзов сообщений, и несколько элементов msg.

Элемент metadata с именем gateway.XXX отвечает за дополнительные поля модуля при добавлении и настройке шлюза. Формируется согласно стандартному описанию XML-формы. Разместите поля в элементе <page name="settings"></page> для корректного размещения полей на формах в BILLmanager. Атрибут crypted сообщает о необходимости хранения параметра в базе данных в зашифрованном виде. Атрибут private скрывает значение поля при выводе в интерфейсе.

Элемент lang содержит переводы наименований полей на форме. Раздел <messages name="gateway_include"> отвечает за подпись наименования модуля в списке методов оплаты. Раздел <messages name="msgerror"> содержит тексты ошибок, которые возвращает основной скрипт.

Основной скрипт модуля

Основной скрипт модуля шлюза отвечает за передачу платформе информации о поддерживаемых функциях и обработку этих функций. При работе с модулем BILLmanager исполняет файл скрипта со следующими параметрами:

gate/gwXXX --command cmd

Где cmd — управляющая команда.

Обязательная команда:

• features — возвращает XML-файл с <features> (список поддерживаемых возможностей) и <notify_module> (указание совместимого модуля уведомлений).

Основные команды (вызываются в зависимости от заявленных <feature>):

• outgoing — отправка исходящего сообщения;
• ingoing — получение входящих сообщений;
• formtune — модификация формы настроек шлюза;
• check_connection — проверка параметров подключения к внешнему сервису.

Пояснения к XML-файлу

features — выход

В ответ на команду features модуль должен вернуть в стандартный поток вывода XML-документ:

<doc>
  <features>
    <feature name="outgoing"/>
    <feature name="formtune"/>
    <feature name="check_connection"/>
  </features>
  <notify_module>ntsms</notify_module>
</doc>

Элемент feature содержит список возможностей модуля. Если возможность не поддерживается, она не должна присутствовать в выводе результата выполнения команды.

outgoing — вход (stdin)

Платформа передаёт на стандартный ввод XML-документ с данными для отправки:

<doc>
  <gateway>
    <login>user</login>
    <password>pass</password>
    <sender>BILLmanager</sender>
    <xmlparams>...</xmlparams>
  </gateway>
  <message>Ваш платёж принят</message>
  <user>
    <phone>+71234567890</phone>
    <email>client@example.com</email>
  </user>
  <project>
    <id>1</id>
    <name>MyProject</name>
  </project>
</doc>

Скрипт обязан извлечь параметры из секции <gateway>, сформировать запрос к API внешнего сервиса, используя текст из <message> и контактные данные из <user>. При успешной отправке скрипт выводит <doc/>. При ошибке скрипт выводит XML с описанием ошибки.

check_connection — вход и выход

Вход (stdin) — принимает параметры подключения в открытом виде, даже если в XML-описании указан атрибут crypted="yes". Это необходимо для выполнения тестового запроса к API.

<doc>
  <login>user</login>
  <password>pass</password>
  <url>https://sms.provider.com/api</url>
</doc>

Выход: <doc/> при успехе или XML ошибки при неудаче.