- Главная
- База знаний
- Вопросы и решения
- Взаимодействие с другим ПО
- Структура обмена данными GBS.Market через XML с другими программами
Важно!
Рекомендуется в файлах с данными формировать теги и для необязательных полей, т.к. это ускорит разбор файла.
Для дробных значений разделитель – точка!
Настройки
Для обмена через файлы XML необходимо произвести настройки в Файл-Настройки-Обмен данными
- Обмен через XML – включает возможность автоматической загрузки каталога и покупателей и автоматическую выгрузку продаж (при закрытии программы) и данных по инвентаризации (при завершении инвентаризации)
- Папка обмена – папка, из которой будут загружаться и выгружаться файлы для обмена
- Обмен по времени – расписание в формате ЧЧ:мм, разделенное пробелом или запятыми
Обмен по времени
В указанное время будет происходить загрузка файла catolog.xml, clients.xml и выгрузка файла с продажами за текущий день. Обратите внимание, что в выгрузку попадут ВСЕ продажи за день, даже те, что были выгружены в предыдущий раз и необходимо по sale_id проверять наличие продажи во внешней системе.
При срабатывании расписания запроса на загрузку не будет, она будет выполнена в фоновом режиме. После загрузки будет отображено уведомление в трее.
Если обмен по времени отключен, то загрузка каталога и клиентов будет происходить при запуске программы, а выгрузка продаж при завершении работы.
Папка обмена
Обмен информацией реализован следующим образом:
Есть единая папка, путь к которой указывается в настройках. По умолчанию это папка xml. Папка имеет следующую структуру:
- xml – папка обмена
- in – папка для входящих данных
- DC0F21B386…. – GBS.ID компьютера, который будет принимать данные из этой папки
- out – папка для исходящих данных
- DC0F21B386…. – GBS.ID компьютера, который будет выгружать даные в эту папку
- in – папка для входящих данных
Каждый компьютер имеет уникальный 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 – кол-во в базе маркета на момент завершения инвентаризации
Нюансы по инвентаризации
Стоит учесть, что кол-во в базе, выгруженное в документ, может не быть правильным, т.к. может, к примеру, возникнуть ситуация, когда были совершены продажи, а затем подгружен документ с остатками за вчерашний день. Т.е. при расчете избытка\недостатка необходимо ориентироваться на остатки, рассчитанные вне маркета
Также необходимо учесть, что удаление инвентаризации в базе маркета приведет к возврату кол-ва товаров, которое было списано в момент проведения. Хоть и последующая загрузка файла с остатками выровняет количество обратно, важно понимать, что удаление результатов (и корректировку остатков) необходимо делать вне маркета
при выгрузке товаров в xml в ветке возвратов не указан good_id, невозможно произвести обмен проверьте , плз
Запись в возврате привязана к записи в продаже: sale_item_id, который в свою очередь привязан к good_id.
Т.е. возврат осуществляется для конкретной записи в чеке, для которой известен товар.
закупочную цену никак нельза загрузить?
Олег, закупочная цена фактически относится не к товару, а к накладной на поступление и указывается именно в накладной. Но загрузка накладных из файла недоступна.
Вообще мы рассчитывали на то, что если контроль за товарными остатками происходит вне нашей программы, например, в 1С, то и учет поступлений (в т.ч контроль прибыли) происходит там же.
Как-то можно картинку товара выгружать через обновление каталога ?
Имеете в виду в нашу программу загрузить картинку при обновлении каталога через XML?
к примеру загрузить картинку с 1с в Gbs.market через catalog.xml
p.s. Речь идет о структуре файла каталога catalog.xml, есть ли поле или доп. поле, через которое можно отправить информацию или ссылку на картинку товара?
Чтобы, после обработки catalog.xml на стороне Gbs.Market, картинка товара обновилась
Здравствуйте!
Извиняюсь, пропустил Ваш комментарий. К сожалению, сейчас нет такой возможности и в рамках 5й версии мы уже не планируем ее добавлять.
В 6й версии мы планируем логику обмена с другими программами переделать и, вероятно, что вопрос с фото товаров будет решен.