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%
  • 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 — процент скидки

Ветка платежи (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 — кол-во в базе маркета на момент завершения инвентаризации

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

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

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

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

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

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