Структура обмена данными 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 – кол-во в базе маркета на момент завершения инвентаризации

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

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

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