Описание XML-обмена GrisScan и учетной системы

Минимальная версия приложения: 1.21

Изменения и нововведения

• 31.07.2018 - добавлены сроки годности в выгружаемом документе и при загрузке документа. Минимальная версия программы 1.22
• 02.08.2018 - добавлена единица измерения позиции товаров (pack). Минимальная версия программы 1.23
• 10.08.2018 - добавлена выгрузка товаров и клиентов частями
• 15.08.2018 - добавлен новый документ Возвратная накладная (код документа 5). Минимальная версия программы 1.25
• 07.09.2018 - добавлены периоды редактирования документа (periods). Минимальная версия программы 1.30
• 14.11.2018 - добавлены справочник "Места хранения" и выбор места хранения в документе Инвентаризация (stack). В ответ "Получить список документов" добавлено поле "Комментарий". Минимальная версия программы 1.42
• 30.01.2019 - группировка товаров в списке и документах при наличии параметра "group". Минимальная версия программы 1.45

Описание обмена

Обмен данными между учетной системой и сервером производится через HTTP запросы. Основное требование - наличие параметра id (15-16 значный идентификатор устройства) в строке запроса. Действием будет значение параметра "action"

1. Поиск устройства - (action=search, метод GET, параметр id игнорируется) осуществляется поиск каталога для устройства на сервере. С устройства предварительно нужно выполнить первый обмен (пустой). Поиск производится по первым буквам идентификатора (идентификатор отображается внизу слева основного окна программы на устройстве).
   Сервер возвращает xml с полным идентификатором устройства, если такое устройство найдено.

   http://grissoft.info/xml/scan.php?search=1d2e&action=search

   http://grissoft.info/xml/scan.php?search=1111111111&action=search

2. Удалить все файлы выгрузки на сервере - (action=clear, метод GET) удаляет все файлы выгрузки на сервере (товары, клиенты, документы). Файлы результатов от устройств остаются нетронутыми. Возвращает xml содержащий статус удаления "success".

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=clear

3. Выгрузка списка товаров/клиентов - (action=upload, метод POST) выгружает товары и клиентов на сервер. В пост-запросе отправляются параметры:
   - "articles" содержащий xml-описание товаров.
   - "clients" содержащий xml-описание клиентов.
   - "people" содержащий xml-описание сотрудников.                         
   - "stack" содержащий xml-описание мест хранения.                         
   Возвращает xml содержащий информацию о статусе загрузки данных по каждому из параметров
   Статус принимает значения:
   - skip - параметр отсутствовал, данные на сервере не изменились
   - success - данные на сервере обновлены
   - empty - данные на сервере очищены (если отправить пустое значение)

   Возможна выгрузка товаров и/или клиентов частями. В этом случае к URL добавляется параметр "part" содержащий порядковый номер выгрузки (части). Значение должно быть больше нуля (1, 2, 3 и т.д.).

   Пример:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=upload&part=1

   Описание xml списка товаров

   xml состоит из элементов <article> с полями

   • barcode - штрихкод (обязательно)
   • article - артикул (обязательно)
   • name - наименование (обязательно)
   • ed - основная единица измерения
   • pack - единица измерения позиции
   • k - кратность позиции
   • w - признак весового товара
   • price - цена
   • comment - текстовый комментарий
   • group - группа товаров или другая группировка

   Пример:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=articles

   Описание xml списка клиентов

   xml состоит из элементов <client> с полями

   • code - уникальный код (обязательно)
   • name - наименование (обязательно)
   • inn - инн
   • telephone - номера телефонов
   • address - адрес

   Пример:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=clients

   Описание xml списка сотрудников

   xml состоит из элементов <people> с полями

   • code - уникальный код (обязательно)
   • name - наименование (обязательно)
   • barcode - штрихкод, предназначен для идентификации сотрудника с помощью сканера

   Пример:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=people

   Описание xml списка мест хранения

   xml состоит из элементов <stack> с полями

   • code - уникальный код (обязательно)
   • name - наименование (обязательно)

   Пример:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=stacks

4. Выгрузка документов на сервер - (action=put, метод POST) выгружает документ на сервер.
   Выгружаемый документ будет импортирован на устройство с типом "Складской документ". Предназначен для сверки приходов, заказов и т.д. ответственным сотрудником.

   xml состоит из элементов <document>

   Для выгрузки нескольких документов необходимо добавить несколько записей <document> в xml или выполнить отправку каждого документа отдельно, после чего выполнить обмен на устройстве.

   ВНИМАНИЕ! После импорта на устройство документы с сервера удаляются.

   ВНИМАНИЕ! Повторная загрузка документа на устройство удалит существующий документ.

   В пост-запросе отправляется параметр documents содержащий xml описание документов

   Структура элемента <document>:

   • code - уникальный идентификатор документа (обязательно)
   • date - дата-время документа в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда) (обязательно)
   • name - тип документа, например "Приход товара"
   • num - номер документа для отображения, например "ПР-0000001"
   • barcode - штрихкод, предназначен для идентификации документа с помощью сканера
   • stack - уникальный код места хранения
   • comment - текстовый комментарий
   • telephone - контактные телефоны через запятую, формат "ТЕЛЕФОН" или "ТЕЛЕФОН:ИМЯКОНТАКТА". Например "0500000001,0670000001:Петрик П'яточкін"
   • dimension - если установить значение "1", то при сохранении документа в программе GrisScan будет запрошено ввести габариты и вес посылки(-ок)
   • terms - значение 1 требует от пользователя указать сроки годности товаров и их количества при обработке документа в программе GrisScan
   • client - содержит элементы:
     • code - уникальный код клиента
     • name - наименование клиента
   • people - содержит поля
     • code - уникальный код сотрудника
     • name - наименование сотрудника
     • barcode - штрихкод сотрудника
   • rows - содержит элементы <row> с полями:
     • barcode - штрихкод (обязательно)
     • article - артикул (обязательно)
     • name - наименование (обязательно)
     • ed - основная единица измерения
     • pack - единица измерения позиции
     • k - кратность позиции
     • w - признак весового товара
     • price - цена
     • quantity - количество
     • comment - текстовый комментарий
     • group - группа товаров или другая группировка

   Возвращает xml с полем "success" со значением "1" или "error"
   Возможные значения ошибок:
   - empty - отсутствуют данные

   Пример xml:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=documents

   Пример ответа:

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=put

5. Получить список документов - (action=list, метод GET) возвращает xml списка документов для указанного идентификатора (параметр id).

   xml состоит из элементов <document> с полями:

   • docid - идентификатор документа на сервере
   • code - уникальный идентификатор документа
   • date - дата-время документа в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)
   • num - номер документа для отображения, например "ПР-0000001"
   • type - цифровой тип документа
   • name - тип документа, например "Приход товара"
   • comment - текстовый комментарий

   Параметр TYPE может принимать следующие значения:
   - 1 - Инвентаризация
   - 2 - Инвентаризация у клиента
   - 3 - Расходная накладная
   - 4 - Складской документ
   - 5 - Возвратная накладная

   Для выборки определенного типа документов в строке запроса необходимо добавить параметр "type" с указанием типа документа.

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=list&type=4

6. Получить документ - (action=get, метод GET) возвращает xml документа по имени (параметр doc) или с ошибкой "error" "notfound".

   Параметр doc соответствует значению поля docid из запроса списка документов

   Ответ состоит из одного элемента <document> со следующими полями:

   • type - цифровой тип документа
   • code - уникальный идентификатор документа
   • date - дата-время документа в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)
   • begin - дата-время начала обработки документа в приложении в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)
   • finish - дата-время окончания обработки документа в приложении в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)
   • name - тип документа, например "Приход товара"
   • num - номер документа для отображения, например "ПР-0000001"
   • barcode - штрихкод, предназначен для идентификации документа с помощью сканера
   • terms - значение 1 означает, что в документе присутствуют сроки годности товаров и их количества
   • stack - уникальный код места хранения
   • comment - текстовый комментарий
   • client - содержит элементы:
     • code - уникальный код клиента
     • name - наименование клиента
   • people - содержит элементы:
     • code - уникальный код сотрудника
     • name - наименование сотрудника
     • barcode - штрихкод сотрудника
   • rows - содержит элементы <row> с полями:
     • barcode - штрихкод (обязательно)
     • article - артикул (обязательно)
     • name - наименование (обязательно)
     • ed - единица измерения
     • price - цена
     • quantity - количество
     • terms - содержит элементы <term> с полями:
       • date - срок годности в формате YYYY-MM-DD (Год-Месяц-День)
       • quantity - количество
     • group - группа товаров или другая группировка
   • dimensions - содержит элементы <dimension> с полями:
     • width - ширина, см
     • height - высота, см
     • length - длина, см
     • weight - вес, кг
   • periods - содержит элементы <period> с полями:
     • id - идентификатор записи
     • begin - дата-время начала обработки документа в приложении в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)
     • finish - дата-время окончания обработки документа в приложении в формате YYYY-MM-DD HH:NN:SS (Год-Месяц-День Час:Минута:Секунда)

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=get&doc=doc_4_16_20180718081002.xml

7. Удалить документ - (action=del, метод GET) удаляет документ на сервере по имени (параметр doc).

   Возвращает xml с полем "success" со значением "1" или поле "error" содержащее текст ошибки (в текущей версии обмена только "notfound" - документ не найден).

   http://grissoft.info/xml/scan.php?id=1d2e3m4o5x6m7l8&action=del&doc=doc_4_16_20180718081002.xml