Одним из механизмов обмена, используемым для передачи данных между кассовым сервером и товароучетной системой, является протокол SOAP. Обмен данными через SOAP может использоваться как самостоятельно, так и параллельно с обычным механизмом загрузки справочников. 

Включение сервиса SOAP

Для выполнения загрузки справочников на базе Ubuntu 18.04 на КС необходимо:

1. Для сервиса exchangers-soap-upload в директории /etc/default/ необходимо вручную создать пустой файл:

   touch exchangers-soap-upload

2. Запустить сервис с помощью команды:

   systemctl start exchangers-soap-upload

   Просмотреть статус сервиса можно командой:

   systemctl status exchangers-soap-upload

   После старта сервис будет работать даже после перезагрузки.

Настройка обмена через SOAP

Настройка сервиса обмена SOAP осуществляется в конфигурационном файле /opt/exchangers/config/cs/exchangers.ini в секции [SOAP_UPLOAD].

[SOAP_UPLOAD]
; Порт для SOAP сервиса
port = 18080
; Максимальный размер тела SOAP запроса в битах. По умолчанию 83886080 (10 MB)
maxContentLength=83886080
; Проверять логин и пароль при SOAP запросе. По умолчанию - False
authorize = False
; Логин для авторизации SOAP запроса. По умолчанию - admin
login = admin
; Пароль для авторизации SOAP запроса. По умолчанию - admin
passwd = admin
; Время простоя сессии (в секундах). Если истекло время, указанное в данной настройке,
; после последнего запроса внутри сессии, то вся сессия отменится. По умолчанию - 300 сек
sessionIdleTimeout = 300
; Являются ли коды магазинов, которые передают в запросе идентификаторами магазинов. По умолчанию - False
shopCodeIsShopId = False
; Максимальное количество архивов запросов для одного магазина в бэкап директории (устаревшие архивы будут удаляться)
; Если указать значение 0, то данная настройка учитываться не будет
maxCountBackupRequests = 0
; Количество дней актуальности архивов запросов для одного магазина в бэкап директории (устаревшие архивы будут удаляться)
; Если указать значение 0, то данная настройка учитываться не будет
actualCountDaysForBackupRequests = 3
; Использовать сессионную загрузку справочников. По умолчанию - False
useSession = False
; Использовать валидацию SOAP запросов.  По умолчанию - False
useValidation = False
; В один момент времени разрешать грузить только один справочник в магазин при использовании сессионного режима
singleShopSession = False
; Многопоточный режим загрузки через SOAP сервис
multiprocessing = False

Данные справочников из АСТУ на КС передаются в виде xml-файлов. Документ xml представляет собой запрос. Актуальная wsdl для формирования запросов расположена по URL http://<хост сервера>:18080/soap?wsdl.

SOAP запрос может представлять:

• открытие сессии,
• добавление массива объектов,
• удаление массива объектов,
• закрытие сессии,
• отмену сессии.

Все SOAP запросы отправляются на порт сервиса, указанный в настройках. Каждый справочник следует загружать отдельно. Справочник может содержать некоторое количество объектов. Если объектов одного типа слишком много, то запрос необходимо разбить на несколько таким образом, чтобы тело запроса не превышало порога, заданного параметром maxContentLength. 

Архивы запросов на загрузку справочников хранятся помагазинно в директории /opt/exchangers/logs/SOAP_BACKUP. Количество архивных запросов и количество дней, в течение которых запросы остаются актуальными, определяется параметрами maxCountBackupRequests и actualCountDaysForBackupRequests соответственно. Устаревшие запросы удаляются. Если параметры не определены, то в директории хранятся все переданные запросы.

Добавление объектов

SOAP запрос на добавление объектов может включать 4 параметра:

• Код магазина – определяет магазин, в БД которого необходимо загрузить справочники. Является обязательным параметром.
• Идентификатор справочника – используется для отслеживания статусов загрузки справочника. Является обязательным параметром.
• Параметр очищения справочника – определяет необходимость очистки содержимого справочника перед загрузкой.
• Массив объектов.

Удаление объектов

SOAP запрос на удаление объектов может включать 3 параметра:

• Код магазина – определяет магазин, из БД которого необходимо удалить справочники. Является обязательным параметром.
• Идентификатор справочника – используется для отслеживания статусов загрузки справочника. Является обязательным параметром.
• Массив объектов.

В параметре <код магазина> может быть указан:

• код магазина или категории магазинов,
• идентификатор магазина или категории магазинов.

Правила использования кодов или идентификаторов задаются параметром shopCodeIsShopId.

Очистка справочников

При загрузке справочников используются методы добавления и удаления объектов. Команда clear не является самостоятельным методом, а используется в качестве параметра метода add:

• при значении параметра clear = true производится предварительная очистка перед загрузкой данных справочника,
• при значении параметра clear = false данные справочника будут добавлены к существующим.

Параметр clearIfEmptyData предназначен для очистки справочников и используется только при значении параметра clear = true и загрузке пустого справочника. В таблице приведено описание поведения при других значениях параметров clear и clearIfEmptyData.

Сессионная загрузка справочников

Загрузку одного справочника несколькими запросами можно выполнить единой порцией данных при помощи сессионной загрузки справочников. Возможность сессионной загрузки справочников определяется параметром useSession. Загрузка в один момент времени только одного справочника в один магазин задается параметром singleShopSession.

Если сессионная загрузка справочников разрешена (useSession = true), то для управления сессиями загрузки используются методы:

• startSession – запуск сессии.
• stopSession – завершение сессии. Метод должен быть вызван обязательно после окончания отправки справочников, чтобы все переданные части справочника были загружены в БД.
• rollbackSession – отмена загрузки справочников. Если сессия была открыта, но за время простоя, определяемого параметром sessionIdleTimeout, не было выполнено ни одного вызова, то сессия отменяется со всеми переданными данными.

В рамках одной сессии может выполняться загрузка данных только на один магазин. 

Если сессионная загрузка справочников запрещена (useSession = false), то использование методов управления сессиями будет недоступно. При загрузке справочников одному запросу добавления справочника будет соответствовать один справочник.

Особенности использования протокола SOAP

Протокол SOAP базируется на обмене сообщениями между клиентом и сервером. Каждое сообщение содержит информацию о данных, которые передаются из АСТУ в БД кассового сервера. SOAP описывает структуру сообщения при помощи XML-схем. На кассовом сервере расположен документ wsdl, содержащий данные о расположении сервиса, типах данных передаваемых объектов и операции, которые могут быть выполнены при обращении к нему.

Документ wsdl расположен по адресу http://<хост сервера>:18080/soap/?wsdl и состоит из следующих элементов:

Веб-сервис, предоставляя возможность вызова какого-либо метода, дает возможность клиентам узнать, какие параметры для этого метода используются. На основании этого принципа любой SOAP-клиент, обращаясь к wsdl-документу, строит внутреннюю структуру запроса для загрузки справочников.

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

Поля и объекты с пометкой <!--Optional:–> не обязательны для заполнения и могут быть удалены из запроса. 

Объекты с пометкой <!--Zero or more repetitions:–> могут повторяться в запросе, т.е. одним запросом можно загрузить справочник с несколькими разными объектами, например, товарами, у каждого из которых указываются свои параметры.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aif="http://aif.soap.exchange.artix.su">
   <soapenv:Header/>
   <soapenv:Body>
      <aif:addAlcoCodes>
         <!--Optional:-->
         <aif:alcocodes>
            <!--Zero or more repetitions:-->
            <aif:AlcoCode>
               <!--Optional:-->
               <aif:alcocode>112233</aif:alcocode>
            </aif:AlcoCode>
			<aif:AlcoCode>
               <!--Optional:-->
               <aif:alcocode>334499</aif:alcocode>
            </aif:AlcoCode>
         </aif:alcocodes>
         <!--Optional:-->
         <aif:shopCode>15</aif:shopCode>
         <!--Optional:-->
         <aif:clear>0</aif:clear>
         <!--Optional:-->
         <aif:dictionaryId>46</aif:dictionaryId>
      </aif:addAlcoCodes>
   </soapenv:Body>
</soapenv:Envelope>