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логический
  • true
  • false
Включение/отключение заголовка X-Forwarded-For в запросахПо умолчанию true
server.portстроковый
Порт сервераПо умолчанию 38060
rest.portстроковый
Порт ядраПо умолчанию 38051
rest.hostстроковый
Хост ядраПо умолчанию localhost
rest.userстроковый
Имя пользователя для авторизации по REST-протоколу на КС (для получения доступа к ядру КС)

По умолчанию admin

По умолчанию настройка закомментирована, так как она используется только в случае, если сервис устанавливается на отдельную машину и включена авторизация на КС

rest.passwordстроковый
Пароль для авторизации по REST-протоколу на КС (для получения доступа к ядру КС)

По умолчанию admin

По умолчанию настройка закомментирована, так как она используется только в случае, если сервис устанавливается на отдельную машину и включена авторизация на КС

security.basic.enabledлогический
  • true
  • false
Включение/отключение аутентификацииПо умолчанию false
security.user.nameстроковый
Логин

По умолчанию user

Работает при security.basic.enabled=true

security.user.passwordстроковый
Пароль

По умолчанию password

Работает при security.basic.enabled=true

Редактирование данных можно выполнить как через веб-интерфейс, так и посредством запроса 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

строковыйИдентификатор организации для продажи акцизного алкоголя

Добавление производится по ID или ИНН организации. При указании обоих параметров возникает ошибка.

Организация должна быть создана на КС

organizationExsise.organizationInnстроковыйИНН организации для продажи акцизного алкоголя

kppExcise

строковыйКПП акцизного алкоголя

fsraridExcise

строковыйФСРАР акцизного алкоголя

shopLabels


строковыйИдентификаторы меток, которые присутствуют на магазинеУказываются по ID или наименованию метки. Метки должны быть созданы на сервере. Системные метки не подлежат исправлению

Наименования меток, которые присутствуют на магазине

vendor.vendorId

строковыйИдентификатор продавца

Привязка продавца к магазину по ID или ИНН продавца. При указании обоих параметров возникает ошибка.

Продавец должен быть создан на КС

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>
  • No labels