03.10.2017

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

  1. Главная
  2. База знаний
  3. Вопросы и решения
  4. Взаимодействие с другим ПО
  5. Структура обмена данными GBS.Market через XML с другими программами

Важно!

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

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

Настройки

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

Настройки обмена данными через XML файлы с другим ПО в GBS.Market

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

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

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

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

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

Папка обмена

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

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

IwIKFj3iK5ck5yWxLnxRT3f1zko2Imfh0IgJErEa

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

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

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

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

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

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

skHEgztHzZLeqrMnJiYkXKxSbnFhmQek74CDUpyo

Файл 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 должен иметь следующую структуру:

roa6RLJVJ9987gNg3Bxln5bnBtONPCDUlrYY32E4

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

  • 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 – основная розничная цена*
  • price1price2price3, price4, price5 – доп. колонки цен
  • ext1 – ext5 – доп. поля
  • comment – комментарий

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

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

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

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

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

g9CQqmoSgD_ObsgGL9Dd6HqlyNUOEyB64M8vOxU9

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

DKhnTr0Pe2epyOYMTlLQ69mkKMTBdB51MdmFFJQM

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

PNiJCwpg78EY6cCYZlcfW8Abq_FcLNJZodI7Fe-R

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

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

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

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

uwK81h0HeUFWWUTfK3N7OjxKQNXvZ-3olHgtmupJ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

aVZcrgjNDc3VShQMcnJGtXfiWN4FZCsqfJIGGCNO

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

rWafbN_oN6tyWQopvYHdwkJrWbcnY2mjp8mtN9us

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

9rVcbZiBRG2qZv4Op9oHfMMvqJMFsYNEzXgJ4wa7

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

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

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

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

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

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

1_PcW6EHVX41mKi1Xzefn77aO7fpG6rwV7ZIFIu3

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

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

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

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

XvvxeQAm2Xal6VwBlR8muvg9qAm-z9EnKy7N1rwh

Ветка <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)

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

Fk84uKrJP7aU7ddiZ2e65nos64bidh3jT1zrhlUR

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

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

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

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

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

tEx7DDv5cPM-kF-5f0DcXA5gDXtGroOb25YfVMfM
Ветка <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 – внесение

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

lpi0q5muLTUwTKpyvopA5CJ39FMZbvtPW6y_wCR0

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

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

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

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

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

8rydTaLRExP4HSnkshSMEENsghOi4wFPgKvEr69q

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

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

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

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

eU13_hTtpjJDyKEDjl7jLqdXu_FKBcEk_u9O-NAo

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

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

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

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

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

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

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

Была ли полезна статья?

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

    • Запись в возврате привязана к записи в продаже: sale_item_id, который в свою очередь привязан к good_id.
      Т.е. возврат осуществляется для конкретной записи в чеке, для которой известен товар.

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *