Структура обмена данными GBS.Market через XML с другими программами

Важно!

Рекомендуется в файлах с данными формировать теги и для необязательных полей, т.к. это ускорит разбор файла.

Для дробных значений разделитель — точка!

Настройки

Для обмена через файлы XML необходимо произвести настройки в Файл-Настройки-Обмен данными

• Обмен через XML — включает возможность автоматической загрузки каталога и покупателей и автоматическую выгрузку продаж (при закрытии программы) и данных по инвентаризации (при завершении инвентаризации)
• Папка обмена — папка, из которой будут загружаться и выгружаться файлы для обмена
• Обмен по времени — расписание в формате ЧЧ:мм, разделенное пробелом или запятыми

Обмен по времени

В указанное время будет происходить загрузка файла catolog.xml, clients.xml и выгрузка файла с продажами за текущий день. Обратите внимание, что в выгрузку попадут ВСЕ продажи за день, даже те, что были выгружены в предыдущий раз и необходимо по sale_id проверять наличие продажи во внешней системе.

При срабатывании расписания запроса на загрузку не будет, она будет выполнена в фоновом режиме. После загрузки будет отображено уведомление в трее.

Если обмен по времени отключен, то загрузка каталога и клиентов будет происходить при запуске программы, а выгрузка продаж при завершении работы.

Папка обмена

Обмен информацией реализован следующим образом:

Есть единая папка, путь к которой указывается в настройках. По умолчанию это папка xml. Папка имеет следующую структуру:

• xml — папка обмена
  • in — папка для входящих данных
    • DC0F21B386…. — GBS.ID компьютера, который будет принимать данные из этой папки
  • out — папка для исходящих данных
    • DC0F21B386…. — GBS.ID компьютера, который будет выгружать даные в эту папку

Каждый компьютер имеет уникальный GBS.ID, который используется для идентификации. GBS.ID можно увидеть в Справка-Информация о лицензии.

В папках In и out может содержаться по несколько подпапок с разными ID для каждого ПК отдельно. Папка обмена может быть как в локальной сети, так и в облаке, например, Dropbox или даже на ftp, если в системе она добавлена как сетевая папка.

Загрузка покупателей из XML в GBS.Market

Структура документа для загрузки покупателей

Структура файла clients.xml

Файл clients.xml должен иметь следующие поля:

• uid* — уид покупателя в
• name* — ФИО, полные
• card — ШК или номер дисконтной карты. Рекомендуется ШК в формате EAN-13
• phone — телефон
• email — электронная почта
• address — адрес
• discount — личная скидка в %
• ext1 — ext3 — доп. поля
• comment — комментарий
• price_id — колонка цен (0-основная цена, 1-5 — доп. цены)

*-обязательные поля

Ручная загрузка покупателей в GBS.Market

Если в настройках включена опция “Обмениваться данными через XML”, то на главной форме доступно меню обмена через XML.

Нажмите Обмен данными-Загрузить файл и выберите файл, который содержит данные о клиентах. Если корневой элемент файла имеет имя “сlients”, произойдет загрузка покупателей.

Логика загрузки покупателей

Процесс загрузки покупателей в базу аналогичен загрузке товаров. Из файла GBS будет производить сверку по базе и указанному UID покупателя:

• Если покупатель с таким УИД есть в базе, его данные будут обновлены из файла
• Если покупателя с таким УИД нет, он будет добавлен
• Если покупатель есть в базе, но в файле для него не было найдено совпадения по УИД или у покупателя не было УИД — он будет отмечен удаленным

Загрузка каталога товаров из XML в GBS.Market

Структура файла каталога для загрузки

Файл catalog.xml должен иметь следующую структуру:

Поля товара, принимаемые в Маркет:

• uid — уид товара*
• name -имя товара*
• barcode — штрих-код*
• group_uid — уид группы*
• group_name — имя группы*
• group_maxDiscount  — значение максимальной скидки на группу. Если не указано, то значение принимает 100%
• group_taxType — значение налоговой ставки. По умолчанию 1
• group_goodsType — тип товара, принимает следующие значения:
  • 0 — Обычный или составной товар (по умолчанию)
  • 1 — Весовой товар
  • 2 — Услуги
  • 3 — Составные части
  • 4 — Пивная продукция (штучный)**
  • 5 — Пивная продукция (разливной)**
  • 6 — Крепкий алкоголь (штучный)**
  • 7 — Подарочные сертификаты
• stock — остаток на складе*
• plu — весовой код товара (целое число, до 5 знаков)
• price — основная розничная цена*
• price1, price2, price3, price4, price5 — доп. колонки цен
• ext1 — ext5 — доп. поля
• comment — комментарий

*-обязательные поля

**- используется при интеграции с ЕГАИС

Если для товара указан PLU, на его основании и указанного в настройках префикса ШК для весовых товаров ему будет присвоен весовой ШК, который заменяет ШК, если он был.

Ручная загрузка

Если в настройках включена опция “Обмениваться данными через XML”, то на главной форме доступно меню обмена через XML:

Маркет запросит выбрать файл для загрузки

Затем подтверждение на загрузку

Если загрузка прошла успешно, пользователь получит уведомление “Успешно загружено”. Если нет — появится окно с ошибкой, возникшей при загрузке документа.

Автоматическая загрузка

Программа проверяет папку по адресу %Sync%\in\%gbs.id% и ищет в ней файл catalog.xml при запуске программы

Если файл найден, будет предложено обновить данные из файла.

Если файл найден, то все товары помечаются удаленными, далее идет анализ файла и внесение корректировок в базу маркета. Все данные: название, штрих-код, цена, остаток и т.д. — будут заменены данными из файла.

В первую очередь проводится анализ товарных групп по УИД. Изначально все группы отмечаются удаленными, далее так же, как и с товарами.

Логика загрузки

Перед применением изменений из документа все категории (группы товаров) и сами товары помечаются как удаленные, далее происходит сверка с документом по следующей схеме:

В первую очередь по документу производится сравнение категорий (групп) товаров:

• Если категория с group_uid есть в базе — будут внесены изменения
• Если категории нет — будет добавлена новая
• Если в базе категория есть, но ее нет в документе, она будет отмечена как удаленная.

Из  файла Маркет будет производить сверку по своей базе по УИД товара. :

• Если товар с таким УИД есть в базе — будут внесены корректировки
• Если товара с таким УИД нет в базе — будет добавлен новый
• Если в базе Маркета товар с УИД есть, но его нет в документе XML — товар будет помечен как удаленный — история этого товара будет сохранена, но новые действия с ним выполнить не получится

После автоматического внесения данных в Маркет файл catalog.xml удаляется.

Выгрузка продаж из GBS.Market

Выгрузку данных можно сделать следующим образом:

Выгрузку данных осуществляется вручную из главной формы с возможностью выбрать папку для выгрузки или из настроек в папку для автоматического обмена.

Ручная выгрузка

Если включена опция “Обмениваться данными через XML” на главной форме доступно меню:

Далее необходимо выбрать папку, куда будет выгружены данные (по умолчанию — рабочий стол):

Будет создано 7 файлов с именем sales_yyyy-mm-dd.xml, по одному файлу для дня за прошедшую неделю (включая сегодня)

Автоматическая выгрузка

Выгрузка данных будет происходить в папку %Sync%\out\%gbs.id% при закрытии программы. Автоматически выгружается только один файл за текущий день. Если файл есть — он будет перезаписан, если нет, будет создан новый.

Выгружаемый файл имеет имя  sales_yyyy-mm-dd.xml.

Образец файла: https://drive.google.com/open?id=0B9QP3e70tNFBRjk5SlhSeTB6UzQ

Структура файла выгрузки

Файл выгрузки имеет следующую структуру

Документ содержит 5 веток:

• sales — продажи
• payments — платежи (по продажам и возвратам)
• returns — возвраты товара
• money_out — выемка (снятие) наличных из кассы
• money_in — внесение наличных в кассу

Ветка продажи (sales)

Структура ветки следующая:

Ветка <sales> содержит дочерние ветки <sale>, что соответствует чеку. В чеке содержатся следующие данные:

• id — ИД продажи в базе Маркета
• date_time — дата и время совершения продажи
• user_id — ИД пользователя (сотрудника), привязанного к продаже. Если пользователь не указан, значение -1
• client_id — ИД покупателя в базе маркета. Если не указан, то -1 (минус 1)
• client_uid — уид покупателя
  • если  у покупателя нет uid (данные о покупателях вводились через Маркет), то тэг client_uid не будет добавлен в структуру
  • если покупатель не привязан к продаже — client_uid принимает пустое значение
• client_barcode — ШК дисконтной карты клиента
• discountOnSale — скидка на весь чек в денежном эквиваленте. Это НЕ СУММА скидок по позициям, а отдельная скидка. Данная скидка образуется при включенном округлении чека до целого значения.
• isFiscal — фискальный чек или нет, булевое значение (false\true)
• items — ветка с товарными позициями

Ветка <items> содержит дочерние ветки <item>, что соответствует товарной позиции в чеке. Для позиции передаются данные:

• good_id — ИД товара в базе маркета
• good_uid — УИД товара
• good_name — название товара
• count — кол-во товара
• price — цена товара (без скидки)
• discount — процент скидки
• tax_type — номер налоговой ставки
• bonuses — сумма бонусов, начисленная за покупку данного товара

Ветка платежи (payments)

Выглядит следующим образом:

Ветка <payments> содержит дочерние ветки <payment>, что соответствует одному платежу. Платеж в Маркете закрепляется за продажей. Для одной продажи может быть несколько платежей, например оплата наличными и оплата картой.

Ветка payment содержит данные:

• id — ИД платежа в базе Маркета
• sale_id  — ИД продажи в базе Маркет
• date_time — дата, время платежа. Платеж может поступить не вместе с продажей, если она была сделана в долг
• summ — сумма платежа. Сумма может быть отрицательная, это значит, что для продажи был сделан возврат товара и средства возвращены покупателю.
• method — способ оплаты, возможны следующие значения
  • 0 — наличные
  • 1 — банковская карта
  • 2 — безнал (на счет в банке)
  • 3 — оплата баллами\бонусами
• comment — комментарий к платежу

Ветка возвраты (returns)

Ветка имеет следующую структуру:

Ветка <returns> имеет дочерние ветки <return>, что соответствует одному возврату (чеку на возврат):

• id — ИД возврата в базе Маркета
• date_time — дата, время возврата
• comment — комментарий (причина) возврата
• user_id — пользователь, принявший возврат
• sale_id — ID продажи в базе Маркета, для которой был сделан возврат
• good_name — название возвращенного товара
• items — ветка, содержащая записи товарных позиций

Ветка <items> содержит дочерние ветки <item> — для каждой товарной позиции и содержит:

• good_uid  — УИД товара
• count — количество возвращенного товара (положительно значение)
• sale_price — цена, по которой был продан товар
• sale_discount — скидка, сделанная в момент продажи, в процентах

Ветки внесения\снятия (money_in, money_out)

Ветки содержат информацию о внесении и выемки наличных из кассы.

• money_out — выемка наличных
• money_in — внесение

Имеют структуру:

Ветки содержат дочерние ветки <item>, которые соответствуют факту внесения\выемки

Содержат следующую информацию:

• id — ИД записи в базе Маркет. Внесения и выемки хранятся в разных таблицах и ИД могут быть одинаковыми
• date_time — дата, время
• summ — сумма. В обоих случаях — положительная
• user_id — ИД пользователя, выполнившего действие
• comment — комментарий к действию

Выгрузка инвентаризации

Выгрузка результата инвентаризации происходит автоматически при завершении инвентаризации.

Выгрузка будет выполнена только в том случае, если включен обмен данными через XML

Сохраняется в папку обмена (%sync%\out\%gbs.id%) в файл inventory_dd-MM-yyy_HH-mm-ss.xml. Один документ соответствует одной инвентаризации.

Структура выгружаемого файла

Файл имеет следующую структуру

Документ содержит родительскую ветку <inventory> , для которой указано:

• id — ИД инвентаризации в базе маркета
• date_time — дата начала
• user_id — ИД пользователя, выполнившего инвентаризацию
• comment — комментарий, пока никак не используется
• items — записи о товарах

Ветка <items> содержит дочерние ветки <item>, каждая из которых соответствует одному товару и содержит:

• good_id — ИД товара в базе маркета
• good_uid — УИД товара
• count_fact — количество по факту (то, что указал пользователь в момент проведения)
• count_base — кол-во в базе маркета на момент завершения инвентаризации

Нюансы по инвентаризации

Стоит учесть, что кол-во в базе, выгруженное в документ, может не быть правильным, т.к. может, к примеру, возникнуть ситуация, когда были совершены продажи, а затем подгружен документ с остатками за вчерашний день. Т.е. при расчете избытка\недостатка необходимо ориентироваться на остатки, рассчитанные вне маркета

Также необходимо учесть, что удаление инвентаризации в базе маркета приведет к возврату кол-ва товаров, которое было списано в момент проведения. Хоть и последующая загрузка файла с остатками выровняет количество обратно, важно понимать, что удаление результатов (и корректировку остатков) необходимо делать вне маркета