API кассового сервера поддерживает протокол SOAP. Обмен данными по этому протоколу ведется посредством XML-сообщений.
Загрузка справочников на КС
Документ wsdl
расположен по адресу http://<хост сервера>:18080/soap/?wsdl
. С описанием можно ознакомиться, перейдя по ссылке.
Выгрузка продаж с КС
Актуальная wsdl
расположена по адресу: http://<хост сервера>:<порт>/sales-ws/cashserver/sales/ws/sales.wsdl
. С описанием можно ознакомиться, перейдя по ссылке.
Редактирование данных магазинов
Создание и удаление магазинов осуществляется через веб-интерфейс кассового сервера.
Редактирование данных магазинов обеспечивается сервисом, для работы которого на КС необходимо установить пакет artixcs-tree-ws
командой:
<p>apt-get install artixcs-tree-ws</p>
Также сервис можно установить на отдельную машину, указав в настройках доступ к ядру КС.
При установке пакета в директории /opt/artixcs-tree-ws/
создается конфигурационный файл application.properties
, в котором указываются следующие параметры:
Наименование | Тип данных | Возможные значения | Описание | Примечания |
---|---|---|---|---|
server.use-forward-headers | логический |
| Включение/отключение заголовка X-Forwarded-For в запросах | По умолчанию true |
server.port | строковый | Порт сервера | По умолчанию 38060 | |
rest.port | строковый | Порт ядра | По умолчанию 38051 | |
rest.host | строковый | Хост ядра | По умолчанию localhost | |
rest.user | строковый | Имя пользователя для авторизации по REST-протоколу на КС (для получения доступа к ядру КС) | По умолчанию По умолчанию настройка закомментирована, так как она используется только в случае, если сервис устанавливается на отдельную машину и включена авторизация на КС | |
rest.password | строковый | Пароль для авторизации по REST-протоколу на КС (для получения доступа к ядру КС) | По умолчанию По умолчанию настройка закомментирована, так как она используется только в случае, если сервис устанавливается на отдельную машину и включена авторизация на КС | |
security.basic.enabled | логический |
| Включение/отключение аутентификации | По умолчанию false |
security.user.name | строковый | Логин | По умолчанию Работает при | |
security.user.password | строковый | Пароль | По умолчанию Работает при |
Редактирование данных можно выполнить как через веб-интерфейс, так и посредством запроса SOAP с объектом ShopInfo
. Редактирование данных магазинов может производиться через soap-запросы только на ЦКС и обычном КС.
Актуальная wsdl
для формирования запросов расположена по URL
http://<хост сервера>:38060/tree-ws/tree.wsdl
.
Файлы логов хранятся в директории var/log/artix/artixcs-tree-ws/artixcs-tree-ws.log
.
Идентификация магазина, данные которого необходимо изменить, осуществляется по коду магазина, указываемому в поле code
объекта ShopInfo
.
Параметрами объекта ShopInfo
определяется необходимость выполнения полной выгрузки по категориям, если изменился их список:
Поле | Тип данных | Описание | Примечания |
---|---|---|---|
sendFullUnloadCommandForShop | логический | Отправлять команду полной выгрузки по категориям, если изменился список категорий | Необязательное поле. По умолчанию false |
userIdForUnloadCommand | строковый | ID пользователя, от имени которого выполняется команда полной выгрузки при смене категории, если запросом отправляется такая команда | Необязательное поле |
Использование полей позволяет выполнять частичное обновление данных магазина. При помощи SOAP
-сервиса могут быть изменены следующие данные магазина:
Поле | Тип данных | Описание | Примечания |
---|---|---|---|
code | строковый | Код магазина | |
address | строковый | Адрес торговой точки | |
title | строковый | Название магазина | |
extendedoptions | строковый | Опции | |
organizationExsise.organizationId | строковый | Идентификатор организации для продажи акцизного алкоголя | Добавление производится по Организация должна быть создана на КС |
organizationExsise.organizationInn | строковый | ИНН организации для продажи акцизного алкоголя | |
kppExcise | строковый | КПП акцизного алкоголя | |
fsraridExcise | строковый | ФСРАР акцизного алкоголя | |
shopLabels | строковый | Идентификаторы меток, которые присутствуют на магазине | Указываются по ID или наименованию метки. Метки должны быть созданы на сервере. Системные метки не подлежат исправлению |
Наименования меток, которые присутствуют на магазине | |||
vendor.vendorId | строковый | Идентификатор продавца | Привязка продавца к магазину по Продавец должен быть создан на КС |
vendor.vendorInn | строковый | ИНН продавца |
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:bean="http://cashserver.artix.su/tree/ws/beans"> <soapenv:Header/> <soapenv:Body> <bean:shopInfoRequest> <!--1 or more repetitions:--> <bean:shopInfo sendFullUnloadCommandForShop="true" userIdForUnloadCommand="admin"> <bean:code>21</bean:code> <!--Optional:--> <bean:address>Калинина 116</bean:address> <!--Optional:--> <bean:title>Магазин</bean:title> <!--Optional:--> <bean:extendedoptions>COOL=OK</bean:extendedoptions> <!--Optional:--> <bean:organizationExsise> <!--You have a CHOICE of the next 2 items at this level--> <bean:organizationInn>7800238901</bean:organizationInn> </bean:organizationExsise> <!--Optional:--> <bean:kppExcise>123456789</bean:kppExcise> <!--Optional:--> <bean:fsraridExcise>111111</bean:fsraridExcise> <!--Optional:--> <bean:organizationNonExsise> <!--You have a CHOICE of the next 2 items at this level--> <bean:organizationInn>111111111111</bean:organizationInn> </bean:organizationNonExsise> <!--Optional:--> <bean:>987654321</bean:> <!--Optional:--> <bean:fsraridNonExcise>222222</bean:fsraridNonExcise> <!--Zero or more repetitions:--> <bean:categories> <!--You have a CHOICE of the next 2 items at this level--> <bean:categoryCode>7</bean:categoryCode> </bean:categories> <!--Zero or more repetitions:--> <bean:shopLabels> <!--You have a CHOICE of the next 2 items at this level--> <bean:shopLabelName>Супермаркет</bean:shopLabelName> </bean:shopLabels> <!--Optional:--> <bean:vendor> <!--You have a CHOICE of the next 2 items at this level--> <bean:vendorInn>1234567890</bean:vendorInn> </bean:vendor> </bean:shopInfo> <bean:shopInfo> <bean:code>333</bean:code> <!--Optional:--> <bean:address>Калинина 117</bean:address> </bean:shopInfo> </bean:shopInfoRequest> </soapenv:Body> </soapenv:Envelope>
При отправке soap
-запроса сервис выполняет валидацию полей на корректность введенных значений. Если какое-либо из полей заполнено некорректно, то выдается ошибка. Причина возникновения ошибки указывается в теге detail
.
В приведенном примере текст ошибки указывает на то, что поле "Код магазина" не было заполнено:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Client</faultcode> <faultstring xml:lang="en">Validation error</faultstring> <detail> <spring-ws:ValidationError xmlns:spring-ws="http://springframework.org/spring-ws">cvc-complex-type.2.4.a: Invalid content was found starting with element 'bean:address'. One of '{"http://cashserver.artix.su/tree/ws/beans":code}' is expected.</spring-ws:ValidationError> </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
После валидации полей сервис проверяет доступность данных на кассовом сервере. Результат обновления можно увидеть в ответе сервиса.
В ответе сервис возвращает:
- количество изменяемых сущностей
totalCount
, - количество успешно обновленных сущностей
successCount
, - количество необновленных сущностей
failCount
.
Полное обновление выполнено, если totalCount = successCount
. Если какие-либо сущности обновить не удалось, то причина указывается в массиве errorItems
.
В приведенном примере указано, что сервер не обнаружил для магазина №21 несколько категорий из тех, которые были указаны:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <ns2:shopInfoResponse xmlns:ns2="http://cashserver.artix.su/tree/ws/beans"> <ns2:successCount>0</ns2:successCount> <ns2:failCount>1</ns2:failCount> <ns2:description>Success with errors</ns2:description> <ns2:errorItems> <ns2:shopcode>21</ns2:shopcode> <ns2:errorCode>400</ns2:errorCode> <ns2:description>Some sended categories not found on DB</ns2:description> </ns2:errorItems> <ns2:totalCount>1</ns2:totalCount> </ns2:shopInfoResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>