Описание 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

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

Обмен данными между учетной системой и сервером производится через 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 - текстовый комментарий

    Пример:

    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 - текстовый комментарий

    Возвращает 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 - количество
    • 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