Что такое REST API
Сервис ASSISTEX предоставляет возможность интеграции с Вашими информационными системами, путём передачи данных
через программный интерфейс (API) в формате XML по протоколу HTTP.
Работа с API организована в стиле REST.
Доступ к отельным объектам осуществляется стандартными методами HTTP-протокола, а именно GET/POST/PUT/DELETE,
а сами объекты размещаются под определёнными уникальными идентификаторами (URI), которые соответствуют их размещению в сети (URL).
Работа с сервисом через API предоставляет набор возможностей, схожий с функциональностью WEB-интерейса (в частности есть возможность
загружать актуальные прайсы, списки розничных точек, товарные матрицы и другие объекты, публиковать данные, принимать готовые документы и т.д.)
Важное замечание:
Возможно, ваши сотрудники уже загрузили данные вручную и начали пользоваться сервисом. Чтобы избежать неприятностей при отладке и не испортить их данные,
вы можете создать отдельную область данных.
Авторизация
Для работы с API требуется BASIC-авторизация.
Этот способ авторизации подразумевает передачу имени и пароля в заголовке HTTP-запроса.
Заголовок формируется следующим образом: строка вида <имя пользователя>:<пароль> кодируется в
Base64.
Полученное значение подставляется в заголовок запроса в виде
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
В целях безопасности используйте протокол HTTPS.
Быстрый старт
Чтобы было проще разобраться в работе с API, рассмотрим небольшой пример манипуляции с отдельными объектами.
1. Создайте через WEB-интерфейс область данных и ей будет присвоен уникальный идентификатор вида mt123.
Запомните этот идентификатор и перейдите в режим работы с данными щелчком по названию области данных.
2. На вкладке «Базовый прайс» создайте вручную или загрузите из XLS-файла несколько объектов.
3. Чтобы прочитать объекты через API откройте в браузере URL:
https://secure.assistex.ru/mt/api/1.0/mt123/Ware где вместо mt123 нужно подставить идентификатор области данных.
Сервер запросит пароль Basic-авторизации. Используйте тот же пароль, что и для авторизации в WEB-интерфейсе или
создайте отдельного пользователя на странице «Администрирование».
В результате сервер вернёт XML-документ, содержащий список объектов типа Ware:
GET /mt/api/1.0/mt123/Ware HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
HTTP/1.1 200 OK
Server: assistex.ru
Transfer-Encoding: chunked
Date: Tue, 11 Dec 2012 08:12:11 GMT
<?xml version="1.0" encoding="UTF-8"?>
<List>
<Ware>
<wareId>w0001</wareId>
<barCode>0000001</barCode>
<name>Test ware</name>
<group1>Group1</group1>
<group2>Group2</group2>
<uom>uom</uom>
<pack1name>pack1name</pack1name>
<pack2name>pack2name</pack2name>
<basePrice>10.1</basePrice>
</Ware>
</List>
4. Теперь можно записать аналогичные объекты методом PUT. Вам потребуется библиотека, реализующая HTTP/HTTPS-протокол на
вашей программной платформе. Для авторизации добавьте соответствующий заголовок (HTTP header) или используйте встроенные
средства авторизации, которые предоставляет используемая библиотека (см. авторизация).
В качестве передаваемого тела запроса, в первый раз, можете просто скопировать XML, который вернул сервер по указанной
выше ссылке, а затем удалить объекты через WEB-интерфейс.
Если всё сделать правильно, то объекты будут видны в WEB-интефейсе, а сервер вернёт статусы обработки по каждому объекту.
PUT /mt/api/1.0/mt123/Ware HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Content-Length: 263
Content-Type: text/xml; charset=UTF-8
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
<?xml version="1.0" encoding="UTF-8"?>
<List>
<Ware>
<wareId>w0001</wareId>
<barCode>0000001</barCode>
<name>Test ware</name>
<group1>Group1</group1>
<group2>Group2</group2>
<uom>uom</uom>
<pack1name>pack1name</pack1name>
<pack2name>pack2name</pack2name>
<basePrice>10.1</basePrice>
</Ware>
</List>
HTTP/1.1 200 OK
Server: assistex.ru
Transfer-Encoding: chunked
Date: Tue, 11 Dec 2012 08:12:13 GMT
<?xml version="1.0" encoding="UTF-8"?>
<List>
<Status>
<result>created</result>
<id>w0001</id>
<target>https://secure.assistex.ru/mt/api/1.0/mt123/Ware/w0001</target>
</Status>
</List>
Таким образом, мы создали объект типа Ware, который имеет идентификатор w0001 и размещается по адресу
https://secure.assistex.ru/mt/api/1.0/mt123/Ware/w0001
Список всех объектов данного типа находится про адресу https://secure.assistex.ru/mt/api/1.0/mt123/Ware. Для удаления отдельного
объекта или всех объектов данного типа поступаем аналогично: посылаем запрос DELETE на соответствующий URL.
DELETE /mt/api/1.0/mt123/Ware HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
HTTP/1.1 200 OK
Server: Assistex
Transfer-Encoding: chunked
Date: Tue, 11 Dec 2012 08:12:13 GMT
<?xml version="1.0" encoding="UTF-8"?>
<List>
<Status>
<result>deleted</result>
<id>w0001</id>
<target>https://secure.assistex.ru/mt/api/1.0/mt123/Ware/w0001</target>
</Status>
</List>
Совет: используйте системный журнал, если что-то пошло не так.
Идентификация объектов
Обязательным условием работы с API является уникальная идентификация объектов каждого типа.
Идентификаторы могут пересекаться для разных типов объектов, важно поддерживать уникальность в пределах однотипных объектов.
В зависимости от типа объекта вы должны указывать идентификатор явно либо система его присваивает автоматически (так называемый автоинкрементный идентификатор).
Простые справочники, такие как SalesAgent, Ware, Retail и т.д. требуют явно задавать идентификатор, который должен быть
строкового типа длинной до 255 символов. В качестве таких идентификаторов вы можете использовать те же самые значения,
которыми оперирует ваша информационная система.
В случае типов, описывающих отношение между объектами многий-ко-многим (матрицы), используются числовые
автоинкрементные идентификаторы, которые сервис возвращает после записи объекта. В частности, речь идёт об объектах типа WareMatrix, SalesAgentRetail и др.
Информацию о способе идентификации вы найдёте в описании соответствующего типа.
Структура URI
Методы API организованы таким образом, что отдельные объекты, списки объектов и методы сервиса имеют уникальные
идентификаторы определённой структуры, которые совпадают с их фактическим размещением в сети (URL). Когда вы запрашиваете
тот или иной объект, сервис разделяет URI на отдельные компоненты, и в сочетании с HTTP-методом определяет какую именно
процедуру необходимо выполнить и какие параметры ей необходимо передать.
В общем виде URI имеет следующую структуру:
https://secure.assistex.ru/mt/api/[версия API]/[id области данных]/[тип объектов |rpc][/<id-объекта|имя rpc-метода>]
Префикс https://secure.assistex.ru/mt/api/ является общим для всех URI, что делает понятия URI и URL синонимами. В следующей таблице перечислено назначение каждого компонента URI.
Компонент URI |
Значение |
версия API |
1.0 (зарезервировано для последующих версий) |
id-области данных |
Cервис позволяет обрабатывать данные по нескольким организациям одновременно из одной учётной записи.
При создании новой организации создаётся соответствующая ей область данных,
которая получает свой уникальный идентификатор (например mt123),
который можно узнать в WEB-интерфейсе системы на вкладке "организации и филиалы". |
тип объектов или rpc |
Работа с API предусматривает доступ к объектам различных типов, таких как «торговый представитель»,
«розничная точка», «товар» и пр. (см. типы данных).
Кроме того, имя rpc зарезервировано для вызовов некоторых процедур, связанные с эксплуатацией сервиса
(например, публикация данных и подключение пользователей) |
id-объекта или имя rpc-процедуры |
Значение идентификатора объекта данного типа или имя процедуры, если на предыдущем уровне указано имя rpc |
Транспортный уровень
Как уже было отмечено в определении API, в качестве транспорта используется стандартный протокол HTTP(s) 1.1.
Для интеграции с сервисом вам потребуется реализация HTTP-клиента под вашу платформу (благо подобных библиотек
предостаточно для любой современной платформы), а так же выполнения некоторых простых условий взаимодействия с сервисом,
таких как использование стандартных HTTP-методов и статусов ответов.
1. Сервис использует следующие HTTP-методы: GET, POST, PUT, DELETE, OPTIONS
(см. спецификацию). Другие методы не поддерживаются и
сервис вернёт HTTP-статус 405 (Method Not Allowed).
Некоторые типы данных, такие как Document, доступны только для чтения.
При необходимости, вы можете запросить список поддерживаемых типов методом OPTIONS.
2. При работе с API ваше клиентское приложение, должно отслеживать и корректно обрабатывать ошибки из серии 4xx (Client error) и 5xx (Server error).
Ошибки могут возникать в при неправильном функционировании инфраструктуры сервиса,
передаче не корректного HTTP-запроса или по иным причинам, предусмотренным спецификацией HTTP.
Явным образом сервис возвращает перечисленные ниже статусы:
- 200 ОК
Успешная обработка запроса
- 401 Unauthorized
Клиент не авторизован. Запрос не содержит заголовок Authorization, либо неверно указаны имя пользователя и пароль.
- 403 Forbidden
Доступ запрещён. Неверное имя области данных или проблемы с авторизацией.
- 404 Not found
Не верный URL или запрашиваемый объект не найден (например, был удалён).
- 405 Method Not Allowed
Разрешены следующие методы: GET, POST, PUT, DELETE, OPTIONS
- 500 Internal Server Error
Все возможные ситуации, когда сервер не может обработать ваш запрос.
В т.ч. когда не корректна структура XML, не заданы обязательные атрибуты объекта или просто что-то сломалось на сервере.
В теле ответа сервис возвращает XML с более детальным описанием ошибки.
3. Заголовок запроса (HTTP Header) Authorization является обязательным (см. авторизация)
4. Для PUT-запросов следует устанавливать заголовок Content-Type: text/xml; charset=UTF-8
Определение простого объекта
Тип объекта — это предопределённый набор имён типизированных атрибутов.
Объект - это набор значений атрибутов соответствующего типа. (Прим: по аналогии с ООП как класс и экземпляр класса)
В рамках API сервиса типы объектов можно условно разделить на две категории: простые и комплексные.
Для простых типов характерен набор атрибутов тривиальных значений (строка, число, дата и т.п.).
Ссылки на другие объекты для простых типов представляются так же простыми типами в виде значения идентификатора объекта, на который ссылается данный.
Т.е. простые объекты не подразумевают явной иерархии или вложенности других простых объектов, кроме как ссылки по идентификатору.
С точки зрения XML-представления, объекты простых типов имеют следующую структуру:
<Имя_типа>
<имя_атрибута_1>значение атрибута 1</имя_атрибута_1>
<имя_атрибута_2>значение атрибута 1</имя_атрибута_2>
...
<имя_атрибута_N>значение атрибута N</имя_атрибута_N>
</Имя_типа>
Если атрибут сам является объектом простого типа, то соответствующий элемент XML-представления будет иметь атрибуты
refType (имя простого типа) и target (URI-объекта), а значение будет соответствовать значению идентификатора
(см. атрибут category в примере ниже).
Пример: тип Retail (розничная тока) является простым типом и при запросе будет иметь следующее XML-представление:
<Retail>
<retailId>100789</retailId>
<name>Квадрат ООО</name>
<inn>2505009418</inn>
<kpp></kpp>
<city>Дальнегорск г</city>
<address>50 лет Октября 298 </address>
<category refType="RetailCategory" target="http://secure.assistex.ru/mt/api/1.0/mt39/RetailCategory/1">1</category>
</Retail>
Примечание:
При записи объектов нет необходимости подставлять refType и target. Их возвращает сервис при GET-запросе для удобства чтения данных.
Комплексные типы объектов
Объекты комплексного типа — это целостная структура данных, включающая множество взаимосвязанных объектов, представленных
в виде XML-документа. К комплексным типам относятся документ, список контроля,
лента сообщений
для торгового представителя. Ключевыми особенностями комплексных типов являются следующие характеристики:
- предопределённая XML-структура;
- не предусмотрена модификация отдельных элементов комплексного объекта - объекты создаются, модифицируются и удаляются целиком;
- могут быть предусмотрены специализированные методы обработки комплексных объектов (например, получение части реестра документов с определённой даты).
Список объектов
Список объектов — это множество объектов одного типа, соответствующее данному URI. Работа со списками характерна для
ситуаций, когда по URI не возможно определить однозначно, какой именно объект запрашивается или модифицируется.
С точки зрения XML-структуры, список объектов — это элементы вложенные в корневой элемент List.
Например, список розничных точек имеет URI https://secure.assistex.ru/mt/api/1.0/mt123/Retail и
при GET-запросе сервер вернёт следующий список объектов:
<?xml version="1.0" encoding="UTF-8"?>
<List>
<Retail>
<retailId>100789</retailId>
<name>Квадрат ООО</name>
<city>Дальнегорск г</city>
<address>50 лет Октября 298 </address>
<category>1</category>
</Retail>
<Retail>
<retailId>100790</retailId>
<name>Куб ООО</name>
<category>1</category>
</Retail>
</List>
В случаях, когда для типа объектов разрешена модификация, сервис позволяет записывать множество объектов методом PUT и удалять методом DELETE.
При таком вызове сервис будет проверять существование объектов с данными ID и в зависимости от результатов проверки будет
выполнять запись нового объекта или обновление существующего. Если некоторые объекты существуют на сервере,
но не представлены в передаваемом списке, то они останутся без изменений.
Совет:
Используйте списки для записи однотипных объектов. Это снижает трафик и работает быстрее по сравнению с записью отдельных объектов.
XSD-схемы
Для генерации кода и проверки корректности формируемых XML-документов вы можете использовать следующие XSD-схемы.
Основная схема API:
https://secure.assistex.ru/mt/xsd/api.xsd
Список контроля:
https://secure.assistex.ru/mt/xsd/CheckList.xsd
RSS-канал:
https://secure.assistex.ru/mt/xsd/rss.xsd
https://secure.assistex.ru/mt/xsd/rss-ext.xsd
Рекомендуемая матрица:
https://secure.assistex.ru/mt/xsd/SoftMatrix.xsd
Процедура публикации
Для публикации данных необходимо послать GET или POST запрос на URL вида:
https://secure.assistex.ru/mt/api/1.0/<ID-области данных>/rpc/publish
Сервис выполняет процедуру публикации асинхронно, а это значит, что при вызове будет немедленно отправлен HTTP-статус 200,
в теле ответа будет передан уникальный токен для отслеживания процесса публикации.
Контроль завершения публикации не является обязательным и вы можете его реализовать по своему усмотрению
(например, для организации уведомлений при возникновении ошибок).
Для получения статуса выполнения асинхронной задачи необходимо послать GET-запрос на URL
https://secure.assistex.ru/mt/api/1.0/<ID-области данных>/rpc/asyncStatus?token=<token>
В качестве ответа будет получен XML, содержащий собственно статус выполнения процедуры,
а так же время начала и окончания. Предусмотрены следующие статусы:
InProgress — процедура выполняется;
Completed — выполнение завершено;
Canceled - отмена;
Error — ошибка.
Пример:
GET /mt/api/1.0/mt123/rpc/publish HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
HTTP/1.1 200 OK
Server: Assistex
Transfer-Encoding: chunked
Date: Tue, 11 Dec 2012 08:12:13 GMT
<?xml version="1.0" encoding="UTF-8"?>
<string>00fd0f311d4fdb3bf75c07eceb4a-t2</string>
GET /rpc/asyncStatus?token=00fd0f311d4fdb3bf75c07eceb4a-t2 HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
HTTP/1.1 200 OK
Server: Assistex
Transfer-Encoding: chunked
Date: Tue, 11 Dec 2012 08:12:13 GMT
<?xml version="1.0" encoding="UTF-8"?>
<AsyncStatus>
<status>InProgress</status>
<dtStart>2013-03-25 11:44:41</dtStart>
</AsyncStatus>
Типы данных
В следующей таблице приведён полный перечень типов объектов, работу с которыми поддерживает API.
SalesAgent. Торговый представитель
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgent
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgent/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
salesAgentId |
Уникальный идентификатор |
String(255) |
+ |
name |
ФИО |
String(255) |
+ |
email |
Адрес электронной почты |
String(255) |
|
phone |
Номер телефона для отправки SMS при подключении |
String(255) |
|
Retail. Розничная точка
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Retail
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Retail/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
retailId |
Уникальный идентификатор |
String(255) |
+ |
name |
Наименование розничной точки |
String(255) |
+ |
inn |
ИНН |
String(255) |
|
kpp |
КПП |
String(255) |
|
city |
Город |
String(255) |
|
address |
Адрес фактичкеского расположения |
String(255) |
|
category |
Ссылка на категорию |
Ссылка на RetailCategory |
+ |
longitude |
Географические координаты долготы |
Float |
|
latitude |
Географические координаты широты |
Float |
|
RetailCategory. Категория розничной точки
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailCategory
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailCategory/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
retailCategoryId |
Уникальный идентификатор |
String(255) |
+ |
name |
Наименование категории |
String(255) |
+ |
priceMultiplier |
Коэффициент цен для базового прайса |
Float |
+ |
RetailDebt. Информация о дебиторской задолженности розничной точки
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailDebt
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailDebt/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
retailId |
Уникальный идентификатор |
String(255) |
+ |
debtSum |
Сумма долга |
Float |
|
alarm |
Показывать предупреждение при работе с розничной точкой |
boolean |
|
details |
Подробное описание по дебиторской задолженности |
String |
|
SalesAgentRetail. Розничные точки торгового представителя
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentRetail
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentRetail/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
salesAgentRetailId |
Уникальный идентификатор (autoincrement) |
long |
+ |
salesAgent |
Ссылка на торгового представителя |
Ссылка на SalesAgent |
+ |
retail |
Ссылка на розничную точку |
Ссылка на Retail |
+ |
WarePack. Справочник упаковки
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WarePack
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WarePack/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
warePackId |
Уникальный идентификатор |
String(255) |
+ |
name |
Наименование |
String(255) |
+ |
quantity |
Кол-во единиц продукции в упаковке |
float |
+ |
Ware. Товарная позиция
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Ware
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Ware/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
wareId |
Уникальный идентификатор |
String(255) |
+ |
barCode |
Штрих-код |
String(255) |
|
name |
Наименование |
String(255) |
+ |
description |
Описание |
String |
|
group1 |
Группа 1 |
String(255) |
|
group2 |
Группа 2 |
String(255) |
|
group3 |
Группа 3 |
String(255) |
|
group4 |
Группа 4 |
String(255) |
|
group5 |
Группа 5 |
String(255) |
|
uom |
Единица измерения |
String(255) |
|
basePrice |
Базовая цена |
Float |
+ |
weight |
Вес единицы продукции |
Float |
|
size |
Объем единицы продукции |
Float |
|
termOfSale |
Срок реализации в днях |
Integer |
|
pack1 |
  |
Ссылка на WarePack |
|
pack2 |
  |
Ссылка на WarePack |
|
pack3 |
  |
Ссылка на WarePack |
|
pack4 |
  |
Ссылка на WarePack |
|
pack5 |
  |
Ссылка на WarePack |
|
factoryPack |
  |
Ссылка на WarePack |
|
WareMatrix. Матрица индивидуальных цен для точек/категорий точек
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WareMatrix
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WareMatrix/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
wareMatrixId |
Уникальный идентификатор (autoincrement) |
long |
+ |
retail |
Указывает, что цена действует только для данной точки |
Ссылка на Retail |
|
ware |
Товарная позиция, для котрой определена специальная цена |
Ссылка на Ware |
+ |
category |
Указавает, что данная цена действует для розничных точек данной категории |
Ссылка на RetailCategory |
|
netPrice |
Цена без НДС |
float |
+ |
nds |
НДС |
float |
+ |
grossPrice |
Цена с НДС |
float |
+ |
Warehouse. Склад
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Warehouse
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Warehouse/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
warehouseId |
Уникальный идентификатор |
String(255) |
+ |
name |
  |
String(255) |
|
SalesAgentWarehouse. Склады торгового представителя
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentWarehouse
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentWarehouse/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
salesAgentWarehouseId |
Уникальный идентификатор (autoincrement) |
long |
+ |
salesAgent |
Ссылка на агента |
Ссылка на SalesAgent |
|
warehouse |
Ссылка на склад |
Ссылка на Warehouse |
|
defaultWarehouse |
  |
boolean |
|
WareStock. Остаток по складу
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WareStock
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/WareStock/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
wareStockId |
Уникальный идентификатор (autoincrement) |
long |
+ |
warehouse |
Ссылка на склад |
Ссылка на Warehouse |
|
ware |
Ссылка на товар |
Ссылка на Ware |
|
quantity |
Остаток |
float |
|
SaleLimitationMatrix. Матрица ограничений продаж в розничные точки данной категории (жесткая матрица)
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SaleLimitationMatrix
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SaleLimitationMatrix/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Данный тип данных более не поддерживается и будет удален в последующих версиях API. Вместо SaleLimitationMatrix добавлен тип
HardMatrix.
CheckList. Список контроля
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/CheckList
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/CheckList/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
Списки контроля предназначены для формирования формы отчёта по розничной точке, связанных с осуществлением контрольных
мероприятий, таких как контроль представленности товаров или групп товаров.
Список контроля — это комплексный тип, структуру которого определяет XSD-схема, размещённая по адресу
https://secure.assistex.ru/mt/xsd/CheckList.xsd.
В общем виде список контроля имеет следующую структуру:
<?xml version="1.0" encoding="UTF-8"?>
<CheckList xmlns="https://secure.assistex.ru/mt/xsd/CheckList.xsd"
id="уникальный идентификатор"
title="Заголовк списка контроля"
measure="ед. измерения"
inputType="тип поля ввода"
forAllRetails="признак контроля во всех точках">
<Item id="уникальный ID элемента" name="наименование элемента"/>
...
</CheckList>
Дополнительную информацию о назначении элементов и атрибутов вы сможете найти непосредственно в XSD-схеме.
Совет:
Если вы не знакомы со спецификацией XSD,
то можете создать список контроля в WEB-интерфейсе на вкладке
«контроль выкладки» и затем запросить объекты типа CheckList, чтобы ознакомиться с их структурой.
CheckListByRetailCategory. Устанавливает отношение "многий ко многим" между CheckList и RetailCategory
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/CheckListByRetailCategory
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/CheckListByRetailCategory/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
checkListByRetailCategoryId |
Уникальный идентификатор (autoincrement) |
long |
+ |
checkList |
Ссылка на список контроля |
Ссылка на CheckList |
+ |
retailCategory |
Ссылка на категорию розничной точки |
Ссылка на RetailCategory |
+ |
RetailCheckList. Матрица контроля в определённой розничной точке
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailCheckList
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailCheckList/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
retailCheckListId |
Уникальный идентификатор (autoincrement) |
long |
+ |
retail |
Розничная точка |
Ссылка на Retail |
+ |
checkList |
Список контроля |
Ссылка на CheckList |
+ |
RssChannel. Лента сообщений для торгового представителя
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RssChannel
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RssChannel/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
Сервис ASSISTEX позволяет информировать торговых представителей о проводимых акциях, планах продаж, начисленных бонусах,
а так же по любым другим вопросам. Для этого в API предусмотрен комплексный тип RssChannel,
который имеет структуру ленты сообщений аналогичную формату RSS 2.0.
Каналы бывают двух типов: каналы личных сообщений для определённых торговых представителей и общие сообщения для всех торговых представителей (в пределах области данных).
Важным отличением от стандарта RSS 2.0 является меньшее число элементов в схеме,
а так же два дополнительных элемента: системный идентификатор канала и идентификатор торгового представителя.
В связи с этим, для избежания ошибок, рекомендуется использовать следующие XSD-схемы:
- схема RSS с учётом установленных ограничений на используемые элементы;
- схема дополнительных элементов.
Стоит отметить, что использование данных схем не является обязательным,
но может помочь избежать ошибок, если вы будете использовать готовые библиотеки для формирования RSS.
Пример:
<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0"
xmlns="https://secure.assistex.ru/mt/xsd/rss.xsd"
xmlns:mt="https://secure.assistex.ru/mt/xsd/rss-ext.xsd">
<channel>
<title>Объявления</title>
<pubDate>2012-10-10T10:15:28</pubDate>
<lastBuildDate>2012-10-10T10:15:28</lastBuildDate>
<!--Идентификатор канала. Присваивается автоматически.
Используйте его когда нужно обновить сообщения
в существующем канале-->
<mt:channelId>1</mt:channelId>
<!--Идентфикатор торгового представителя указывает,
что сообщения являются персональными. Если он не определён,
то сообщения видны всем торговым представителям -->
<mt:salesAgent>6822</mt:salesAgent>
<item>
<title>Бонус</title>
<description>Дата расчета: 17 янв 2012 10:15
ТЕКУЩИЙ МЕСЯЦ: Январь
Уникальных точек 1 менее 30, премия не рассчитывается.
Продажи: 90 руб.
Цель 2 «Качественная дистрибьюция»:
SKU на т.:2, уник.т.:1
ПРЕДЫДУЩИЙ МЕСЯЦ: Декабрь
Уникальных точек 5 менее 30, премия не рассчитывается.
Продажи: 605 руб.
Цель 2 «Качественная дистрибьюция»:
SKU на т.:3.4, уник.т.:5</description>
<pubDate>2012-10-10T10:15:28</pubDate>
<guid>4634-5634-5678</guid>
</item>
<item>
<title>Промежуточные итоги по сред. SKU и сумме продаж:</title>
<description>Motelica Elena II
or.Cahul str.Horelor 9J
Продажи: 90.36 р. SKU: 2

</description>
<pubDate>2012-10-10T10:15:28</pubDate>
<guid>4634-5634-5679</guid>
</item>
</channel>
</rss>
SalesAgentPlan. План посещения розничных точек торговым представителем
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentPlan
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentPlan/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
salesAgentPlanId |
Уникальный идентификатор (autoincrement) |
long |
+ |
salesAgent |
Ссылка на торгового представителя |
Ссылка на SalesAgent |
+ |
retail |
Ссылка на розничную точку |
Ссылка на Retail |
+ |
visitDate |
Дата посещения розничной точки |
Date |
+ |
Document. Входящий документ
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Document
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Document/<ID>
Поддерживаемые HTTP-методы:
-GET
-OPTIONS
Document — это комплексный тип данных, отвечающий за структурированное
представление входящих документов (от торговых
представителей), таких как «заказ», «анкета розничной точки» и «отчёт по контролю в розничной точке».
При работе с документами через API есть несколько особенностей:
- Документы каждого типа имеют общую XSD-схему,
которая размещена по адресу https://secure.assistex.ru/mt/xsd/Document.xsd
В описании схемы вы так же найдёте информацию о назначении элементов и атрибутов документа;
- Документы через API доступны только для чтения (метод GET);
- Получение документов из вашей информационной системы должно осуществляться в два прохода: загрузка реестра
документов и загрузка каждого документа в отдельности.
Структура реестра документов
Реестр документов — это список объектов простого типа.
Чтобы получить реестр, достаточно послать
GET запрос вида
https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Document?skip=<пропускаемое число объектов с начала списка>&since=<время мс.>.
В таблице приведено описание атрибутов для объектов реестра.
Атрибут |
Наименование |
Тип |
Обязательный |
documentId |
Уникальный идентификатор |
String(255) |
+ |
docType |
Тип документа (ORDER|PROFILE|CHECKLIST) |
String(255) |
+ |
retail |
Розничная точка, в которой создан документ |
Ссылка на Retail |
+ |
documentSum |
Сумма по документу |
Float |
|
creator |
Торговый представитель, создавший данный документ |
Ссылка на SalesAgent |
+ |
created |
Дата и время создания документа на клиентском устройстве. |
Date |
+ |
timestamp |
Дата и время приёма документа |
Long |
+ |
cancelled |
Признак отменённого документа. |
Boolean |
- |
Параметры строки запроса
Предусмотрены два параметра строки запроса: skip и since.
Поскольку хранилище документов может содержать большое число документов, результаты выдачи реестра документов ограничены
- сервер вернёт не более 100 объектов. Вы можете указать какое кол-во документов необходимо пропустить с начала списка
в параметре skip.
Параметр since позволяет указать точное время, начиная с которого необходимо вернуть записи реестра.
Каждый документ в реестре имеет атрибут timestamp, значение которого соответствует точному времени приёма,
а параметр since позволяет отфильтровать записи по условию "больше или равно". Таким образом,
чтобы организовать регулярное получение новых документов вам достаточно всякий раз запоминать время получения документов, которое сервер возвращает в заголовке server-time и
запрашивать не все записи в реестре, а только новые, начиная со значения параметра since.
Параметр должен содержать числовые значения, которые соответствую машинному способу представления даты и времени
(число миллисекунд прошедшее с 01.01.1970 00:00:00)
Процедура отмены заказа
Если документ типа «заказ» утратил свою актуальность и торговый представитель на клиентском устройстве
запустил соответствующий функциональный режим, то на сервер будет передан тот же самый документ с
признаком отмены. При записи в реестр сервер выполняет поиск соответствующего документа.
Если такой документ найден, то для старой редакции устанавливается признак отмены и обновляется
значение атрибута since. В противном случае (например, при удалении документа) в реестре будет записан
новый документ с признаком отмены.
Чтобы корректно организовать обработку процедуры отмены,
вы можете просто запоминать в информационной системе идентификатор документа, присвоенный сервером.
При очередном запросе с параметром since документ окажется в списке новых документов с атрибутом cancelled.
Такая реализация будет работать корректно, если не удалять документы на сервере. В противном случае,
следует производить поиск документа в вашей информационной системе по точному совпадению атрибутов retail,
creator, created.
Установка статуса
Для информирования торгового представителя о дальнейшем движении документа предусмотрена процедура установки статуса,
в т.ч. можно задать иконку из предложенного набора, заголовок, описание и цветовую индикацию.
Для этого необходимо отправить GET или POST запрос на URL вида
https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>rpc/setDocumentStatus.
В следующей таблице приведены параметры вызова процедуры.
Параметр |
Наименование |
Тип |
Обязательный |
documentId |
ID документа |
String(255) |
+ |
icon |
Графическое изображение (константы 0..2) |
Integer |
|
title |
Заголовок |
String(255) |
|
description |
Описание, дополнительная информация о статусе |
String(255) |
|
color |
Цвет RGB вида #RRGGBB |
String(255) |
|
LogFile. Системный журнал
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/LogFile
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/LogFile/<ID>
Поддерживаемые HTTP-методы:
-GET
-OPTIONS
Сервис предоставляет возможность просмотра системного журнала обработки запросов через API.
Журнал фрагментирован по дням, пользователям и областям данных. Это означает, что пользователь,
от которого производятся вызовы API видит только свои собственные записи по определённой области
данных и не видит записи действий других пользователей.
Предусматривается два режима журналирования: стандартный режим (только запись ошибок) и трассировка.
Режим трассировки предназначен для получения подробной информации в процессе разработки клиентского
приложения. В этом режиме записывается детальная информация о запросах и ответах.
Режим трассировки применяется к запросам с параметром trace.
Доступ к журналу организован через API как к коллекции объектов типа LogFile.
Чтобы прочитать журнал за определённую дату нужно послать GET-запрос (например, открыть в браузере)
URL вида https://secure.assistex.ru/mt/api/1.0/[id области данных]/LogFile/yyyy-MM-dd,
где yyyy-MM-dd — это дата, за которую запрашивается журнал.
SoftMatrix. Рекомендуемая матрица
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SoftMatrix
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SoftMatrix/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
SoftMatrix — это комплексный тип, который предназначен для сортировки и цветовой индикации
списка товаров. Когда торговый представитель вызывает режим формирования заказа, для каждого элемента
в списке товаров производится проверка его включения в множество матриц для данной точки.
Причём, если товар попадает в несколько матриц, то будет выбрана матрица с наивысшим приоритетом
(минимальным числовым значением приоритета). Затем список товаров сортируется по значению приоритета
для каждого товара, при этом будет отдано предпочтение цвету из матрицы с наивысшим приоритетом.
Чтобы определить матрицу, необходимо сформировать XML-документ, соответствующий XSD-схеме:
https://secure.assistex.ru/mt/xsd/SoftMatrix.xsd
XML-документ определяет наименование матрицы, приоритет в списке товаров и цвет, а так же два множества:
множество товаров и множество точек, к которому применима данная матрица. Множество товаров может быть
задано как явно, путём перечисления идентификаторов, так и путём строго совпадения наименования группы
(group1 или group2 см. тип Ware). Множество точек может быть определено путём перечисления
идентификаторов точек или перечислением идентификаторов категорий розничных точек. Кроме того,
можно не определять это множество, и такая ситуация будет интерпретирована как определение матрицы
для всех точек.
Пример матрицы для всех розничных точек:
<?xml version="1.0" encoding="UTF-8"?>
<SoftMatrix xmlns="https://secure.assistex.ru/mt/xsd/SoftMatrix.xsd">
<SoftMatrixId>1</SoftMatrixId>
<Name>Must stock</Name>
<Priority>0</Priority>
<Color>#FF0000</Color>
<WareList filter="wareId">
<!--Матрица включает товары с идентификаторами w0001, w0002.
Соответсвующие товары будут выделены красным цветом. -->
<Item>w0001</Item>
<Item>w0002</Item>
</WareList>
</SoftMatrix>
Пример индивидуальной матрицы для категории:
<?xml version="1.0" encoding="UTF-8"?>
<SoftMatrix xmlns="https://secure.assistex.ru/mt/xsd/SoftMatrix.xsd">
<SoftMatrixId>1</SoftMatrixId>
<Name>Must stock</Name>
<Priority>0</Priority>
<Color>#FF0000</Color>
<RetailList filter="retailCategoryId">
<!--Та же матрица, что и в предыдущем примере, но только для категории
с идентификатором 1 -->
<Item>1</Item>
</RetailList>
<WareList filter="wareId">
<Item>w0001</Item>
<Item>w0002</Item>
</WareList>
</SoftMatrix>
Image. Изображение
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Image
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Image/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Тип Image предназначены для хранения изображений на сервере, публикации и передачи на
клиентские устройства. Объекты этого типа используются в составе других объектов, и в частности
для объектов типа Ware.
Тип Image соответствует определению простого типа, но с некоторыми ограничениями на вызовы
методов и обработку. Поскольку изображения могут быть достаточно большими, для типа Image
запрещена операция записи коллекции целиком, а при запросе списка объектов в коллекции из
выдачи исключается атрибут content, отвечающий за бинарное представление изображения в
структуре объекта.
При записи изображения производится его конвертация в формат JPEG (если формат отличается) и
уменьшение размера до 720 пикселей по ширине и высоте, с сохранением отношения сторон.
Атрибут |
Наименование |
Тип |
Обязательный |
Доступ |
Примечание |
imageId |
Уникальный идентификатор |
String(255) |
+ |
rw |
|
content |
Бинарные данные в кодировке Base64 |
String |
+ |
rw |
Исключен из выдачи в списке объектов коллекции |
width |
Фактическая ширина после обработки |
Integer |
+ |
r |
|
height |
Фактическая высота после обработки |
Integer |
+ |
r |
|
height |
Фактическая высота после обработки |
Integer |
+ |
r |
|
contentType |
Тип |
String(255) |
+ |
r |
Зарезервировано. В настоящий момент всегда JPEG |
Для загрузки изображения на сервер необходимо отправить PUT-запрос на URL вида
https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Image ,
в котом должен содержаться единственный объект с атрибутами imageId и content.
В качестве imageId может использоваться имя файла или любой другой уникальный идентификатор.
Атрибут content должен содержать бинарные данные графического формата (JPEG, PNG, GIF, TIFF, BMP),
закодированные в Base64.
Пример запроса:
PUT /mt/api/1.0/mt123/Image HTTP/1.1
Authorization: Basic QwxhZGluOnNlc2FtIG9wZW4=
Content-Length: 123456
Content-Type: text/xml; charset=UTF-8
Host: secure.assistex.ru
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0.3 (java 1.5)
<?xml version="1.0" encoding="UTF-8"?>
<Image>
<imageId>sample01</imageId>
<content>QwxhZGluOnNlc2FtIG9wZW4=</content><!--Бинарные данные в Base64-->
</Image>
ImageKeywords. Ключевые слова для изображение
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/ImageKeywords
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/ImageKeywords/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
imageKeywordsId |
Уникальный идентификатор (autoincrement) |
long |
+ |
image |
Изображение |
Ссылка на Image |
+ |
keywords |
  |
String(255) |
|
appliedTo |
  |
int |
|
Task. Поручение
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Task
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/Task/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
taskId |
Уникальный идентификатор |
String(255) |
+ |
title |
Заголовок |
String(255) |
|
description |
Описание |
String |
|
dtEnd |
Дата окончания, когда истекает срок выполнения |
Date |
|
highPriority |
Признак высокой важности |
boolean |
|
creatorName |
Имя пользователя, который создал данное поручение |
String(255) |
|
forAllAgents |
Признак поручения для всех агентов |
boolean |
|
RetailTask. Поручения по розничным точкам
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailTask
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/RetailTask/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
retailTaskId |
Уникальный идентификатор (autoincrement) |
long |
+ |
task |
Ссылка на поручение |
Ссылка на Task |
+ |
retail |
Ссылка на розничную точку |
Ссылка на Retail |
+ |
SalesAgentTask. Поручения торгового представителя
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentTask
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/SalesAgentTask/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
salesAgentTaskId |
Уникальный идентификатор (autoincrement) |
long |
+ |
task |
Ссылка на поручение |
Ссылка на Task |
+ |
salesAgent |
Ссылка на агента |
Ссылка на SalesAgent |
+ |
HardMatrix. Жесткая матрица
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/HardMatrix
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/HardMatrix/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
HardMatrix — это комплексный тип, который предназначен для ограничения доступного
ассортимента розничной точки или категории розничных точек (так называемая жесткая матрица или просто
матрица).
Чтобы определить матрицу, необходимо сформировать XML-документ, соответствующий XSD-схеме:
https://secure.assistex.ru/mt/xsd/HardMatrix.xsd
XML-документ определяет наименование матрицы и два множества:
множество товаров и множество точек, к которому применима данная матрица. Множество товаров может быть
задано как явно, путём перечисления идентификаторов, так и путём строго совпадения наименования группы
(group1 или group2 см. тип Ware). Множество точек может быть определено путём перечисления
идентификаторов точек или перечислением идентификаторов категорий розничных точек. Кроме того,
можно не определять это множество, и такая ситуация будет интерпретирована как определение матрицы
для всех точек.
Пример матрицы для категории:
<?xml version="1.0" encoding="UTF-8"?>
<HardMatrix xmlns="https://secure.assistex.ru/mt/xsd/HardMatrix.xsd">
<HardMatrixId>1</HardMatrixId>
<Name>Must stock</Name>
<RetailList filter="retailCategoryId">
<!--Та же матрица, что и в предыдущем примере, но только для категории
с идентификатором 1 -->
<Item>1</Item>
</RetailList>
<WareList filter="wareId">
<Item>w0001</Item>
<Item>w0002</Item>
</WareList>
</HardMatrix>
DeviceSetting. Конфигурация устройства
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/DeviceSetting
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/DeviceSetting/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
DeviceSetting — это комплексный тип, который позволяет управлять конфигурацией клиентских
устройств. Предусмотрен основной объект DeviceSetting со значением идентификатора null, который определяет конфигурацию по
умолчанию для всех устройств. Кроме того, можно установить индивидуальную конфигурацию для отдельных торговых агентов.
Собственно конфигурация включает три контейнера (тега):
OrderCustomAttrs — набор дополнительных (custom) полей для заказа;
SimplePreferences — простые параметры конфигурирования мобильного приложения по принципу «ключ-значение»;
TaskSequence — список задач в точке.
Подробное описание параметров вы можете найти в xsd-схеме.
LegalPerson. Юридическое лицо
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/LegalPerson
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/LegalPerson/<ID>
Поддерживаемые HTTP-методы:
-PUT
-POST
-GET
-OPTIONS
-DELETE
Атрибут |
Наименование |
Тип |
Обязательный |
code |
Идентификатор юр. лица |
String(255) |
+ |
name |
Название юр. лица |
String(255) |
+ |
address |
Адрес |
String(255) |
|
inn |
ИНН |
String(255) |
|
DiscountMatrix. Матрица скидок
Структура URI:
- доступ к коллекции объектов https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/DiscountMatrix
- доступ к отдельному объекту https://secure.assistex.ru/mt/api/1.0/<идентфикатор области данных>/DiscountMatrix/<ID>
Поддерживаемые HTTP-методы:
-PUT
-GET
-OPTIONS
-DELETE
SoftMatrix — это комплексный тип, который предназначен для определения цены основанной
на скидке, которая является вещественным числом(в том числе отрицательным, если нужно увеличение цены).
Цена вычисляется по формуле (бц-базовая цена, с-скидка): бц - (бц*с)
Чтобы определить матрицу, необходимо сформировать XML-документ, соответствующий XSD-схеме:
https://secure.assistex.ru/mt/xsd/SoftMatrix.xsd
XML-документ определяет два множества:
множество товаров и множество точек, к которому применима данная матрица. Множество товаров может быть
задано как явно, путём перечисления идентификаторов, так и путём строго совпадения наименования группы
(group1 или group2 см. тип Ware). Множество точек может быть определено путём перечисления
идентификаторов точек или перечислением идентификаторов категорий розничных точек. Если множество не задано,
то матрица действет на все точки или товары, соответственно.
Пример матрицы для всех розничных точек:
<?xml version="1.0" encoding="UTF-8"?>
<DiscountMatrix xmlns="https://secure.assistex.ru/mt/xsd/DiscountMatrix.xsd">
<DiscountMartixId>1</DiscountMartixId>
<Discount>50</Discount>
<WareList filter="wareId">
<!--Матрица включает товары с идентификаторами w0001, w0002.
Соответсвующие товары будут выделены красным цветом. -->
<Item>w0001</Item>
<Item>w0002</Item>
</WareList>
</DiscountMatrix>
Пример индивидуальной матрицы для категории:
<?xml version="1.0" encoding="UTF-8"?>
<DiscountMatrix xmlns="https://secure.assistex.ru/mt/xsd/DiscountMatrix.xsd">
<DiscountMartixId>1</DiscountMartixId>
<Discount>50</Discount>
<RetailList filter="retailCategoryId">
<!--только для категории с идентификатором 1 -->
<Item>1</Item>
</RetailList>
<!--И для товаров принадлежащих группе "Овощи"-->
<WareList filter="group1">
<Item>Овощи</Item>
</WareList>
</DiscountMatrix>