Описание протокола JSON API для обмена данными с GBS.Market¶
В GBS.Market есть программный интерфейс (JSON API) для возможности получения информации путем http-запросов. Например, это может использоваться для интеграции с другими учетными системами.
На текущий момент API работает только в режиме read-only (только чтение) и не предполагает внесение каких-то изменений в базу данных.
Настройка API¶
Активация API¶
Для работы с API необходимо выполнить его активацию и настройку.
- с главной формы откройте Файл - Настройки
- перейдите на вкладку "Интеграции"
- включите опцию
Активировать API
Настройки подключения¶
При необходимости вы можете настроить дополнительные параметры:
- порт - порт, по которому программа будет прослушивать запросы
- логин - имя пользователя для авторизации при выполнении запросов
- пароль - пароль для авторизации
После завершения настройки сохраните изменения. Чтобы API начал работать, обязательно перезапустите GBS.Market
Важно
Обратите внимание, что если программа запущена с правами обычного пользователя Windows, то запросы могут быть прослушаны только с localhost. Для доступна к API из вне необходимо запустить программу от имени администратора Windows или настроить проксирование, например, средствами nginx
Проверка доступности¶
Чтобы проверить, что API работает, можно открыть в браузере следующий url: http://localhost:8419/api/v1/status, а затем ввести логин и пароль, указанные в настройках.
Если все сделано верно, то после авторизации вы увидите страницу с кодом ответа:
{
"Status": "Ok",
"ResponseTime": 0,
"Data": {
"Type": "StatusInfo",
"GbsId": "3CA3126FAAD94144947085D8A0145B10",
"LicenseExpiration": "2024-07-17T00:00:00",
"AppVersion": "6.6.0.2465"
}
}
Работа с API¶
Основная информация¶
Базовый URL: http://localhost:8419/api/v1
Формат ответов:
{
"Status": "Ok", //статус ответа
"ResponseTime": 0, //время ответа, мс
"TotalPages": 77, //кол-во страниц с записями по запросу
"TotalItems": 7677, //всего элементов по запросу
"Data": { //json-объект или массив json-объектов
}
}
Для авторизации необходимо передавать заголовки аутентификации. Авторизация базовая (basic)
Все запросы выполняются методом GET.
Кэширование¶
Для построения ответов используется кэширование, что может привести к задержке отображения информации. Для обновления кэша можно использовать соответствующий метод.
Обратите внимание, что загрузка кэша может занимать длительное время при большом объеме данных. Кэш обновляется автоматически обычно с периодичностью в 5-20 минут, поэтому нет необходимости перед каждым запросом обновлять кэш.
Важно
Документы кэшируются только за последние год. Для повышения производительности необходимо использовать небольшие периоды для запроса списка документов, т.к. на БД с большим количеством документов возможны большие задержки.
Пагинация¶
Разделение ответов на страницы
Запросы товаров, категорий товаров, документов поддерживают пагинацию через параметры запросов: - page - номер запрашиваемой страницы - page_size - размер страницы (кол-во записей на страницу), по умолчанию 100 записей на страницу
Пример запроса: http://localhost:8419/api/v1/documents?page=2&page_size=10 - записи будут поделены на страницы по 10 записей, в ответе будет содержимое страницы 2
Запросы¶
Получение статуса¶
Метод: /status
Возвращает информацию:
- GBS.ID
- срок истечения лицензии
- версия программы
Пример¶
Запрос: http://localhost:8419/api/v1/status
Ответ:
{
"Status": "Ok",
"ResponseTime": 0,
"Data": {
"Type": "StatusInfo",
"GbsId": "AD6E5736820C4B9A864A2A9417E9FE43", //ИД
"LicenseExpiration": "2022-07-10T00:00:00", //срок окончания лицензии
"AppVersion": "6.3.0.1745" //версия ПО
}
}
Загрузка кэша¶
Метод: /load_caches
Обновляет кэш данных, используемых для предоставления ответов на запросы
Пример¶
Запрос: http://localhost:8419/api/v1/load_caches
Ответ:
{
"Status": "Ok",
"ResponseTime": 3683,
"Data": {
"Type": "Message",
"Message": "Кэш данных успешно обновлен"
}
}
Получение товаров¶
Метод: /goods
Возвращает массив товаров из базы данных.
Доступны параметры:
- uid - uid товара
Пример¶
Запрос: http://localhost:8419/api/v1/goods?page=2
Ответ:
{
"Status": "Ok", //успешно
"ResponseTime": 24, //время выполнения
"TotalPages": 77, //всего страниц
"TotalItems": 7677, //всего записей
"Data": [ //массив json-объектов
{
"Type": "Good", //тип объекта - товар
"IsDeleted": false, //удален - нет
"Properties": [ //доп. поля, массив
{
"TypeUid": "24aaef1f-d733-47f1-ada7-ac3627cf4068", //uid-доп. поля
"TypeName": "Код товара", //название доп. поля
"Value": "56" //значение доп. поля
}
],
"Stocks": [ //остатки, массив
{
"Quantity": 0.0, //кол-во на остатке
"Price": 875.0, //цена розничная
"Storage": { //склад остатка
"Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70", //uid-склада
"Name": "Основной" //название склада
}
},
{
"Quantity": 20.0,
"Price": 950.0,
"Storage": {
"Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70",
"Name": "Основной"
}
}
],
"Uid": "a4eb0bb3-9244-4549-9c9e-463261feb368", //uid товара
"Barcode": "2013815156242", //штрихкод
"Name": "Флеш накопитель 32 Гб \"Триколор ТВ\"", //название
"Group": { //категория
"Name": "Флешки", //название категории
"Uid": "24d2ac23-468d-49c1-b73a-57005a41fada" //uid категории
}
},
{
"Type": "Good", //следующий товар
"IsDeleted": true,
"Properties": [
],
"Stocks": [
{
"Quantity": 0.0,
"Price": 190.0,
"Storage": {
"Uid": "2eff591c-93de-4409-b6c5-6d1fb54d3f70",
"Name": "Основной"
}
}
],
"Uid": "cfdf20b2-8197-41b0-83e0-8ea28ca9e39a",
"Barcode": "4690241027964",
"Name": "Battlefield: Битва за Нью-Йорк - игра (Новый диск)",
"Group": {
"Name": "Игры ",
"Uid": "775c61d2-4399-4797-a86f-e13fcf396561"
}
}
]
}
Получение категорий (групп) товаров¶
Метод: /good_groups
Возвращает массив категорий товаров из базы данных.
Доступны параметры:
- uid - uid категории
Пример¶
Запрос: http://localhost:8419/api/v1/good_groups
Ответ:
{
"Status": "Ok", //статус
"ResponseTime": 92, //время ответа
"TotalPages": 1, //всего страниц
"TotalItems": 36, //всего элементов
"Data": [ //массив категорий
{
"Name": "Для компьютеров", //название
"Type": "GoodGroup", //категория товара объекта
"IsDeleted": true, //удалена?
"Uid": "260ecc3e-af14-444b-bdec-4ccaeb9fce9a" //uid
},
{
"Name": "Шнуры, кабеля, з/у для телефонов",
"Type": "GoodGroup",
"IsDeleted": false,
"Uid": "ee48135f-ddd9-43a5-a89f-e26744462e58"
}
]
}
Получение документов¶
Метод: /documents
Возвращает массив документов
Доступны параметры:
- date_start - начало периода (включительно)
- date_end - конец периода (включительно)
- type - тип документа (ВАЖНО: регистрозависимый параметр)
Типы документов:
- Sale - продажа
- SaleReturn - возврат продажи
- Buy - входящая накладная (поступление)
Типы оплат:
- MoneyDocumentPayment - платеж деньгами по документу
- BonusesDocumentPayment - платеж бонусами по документу
- Prepaid - предоплата по документу (для заказов)
- CheckDiscount - скидка по документу (используется для округления)
Пример 1¶
Запрос продаж за период с 01.07.2023 по 31.07.2023: http://localhost:8419/api/v1/documents?type=Sale&date_start=2023-07-01&date_end=2023-07-31
Пример 2¶
Запрос: http://localhost:8419/api/v1/documents
Ответ:
{
"Status": "Ok", //успешно
"ResponseTime": 24, //время ответа
"TotalPages": 182, //всего страниц
"TotalItems": 18119, //всего записей
"Data": [ //массив объектов
{
"Type": "Document", //тип объекта - документ
"ParentUid":"00000000-0000-0000-0000-000000000000", //uid родителя (для возвратов, например)
"Uid": "a36c63fb-0654-4731-b205-6914272754c3", //uid-документа
"IsDeleted": false, //удален?
"DocumentType": "SaleReturn", //возврат продажи
"DateTime": "2019-08-07T16:29:50.478", //дата, время
"Items": [ //массив записей в документе
{
"Uid": "1306b3fa-aaa9-4013-a805-16ae024fbf20", //uid-записи
"Good": { //товар
"Uid": "f5a57fd1-9aef-40b2-a238-9374f1fb7185", //uid-товара
"Barcode": "2067518736034", //штрих-код
"Name": "Единый мульти ЛАЙТ 1 год", //название товара
"Group": { //категория
"Name": "Оплата Триколор", //название категории
"Uid": "e1b32b53-5c2e-498f-8dc1-ec9ffd4be1be" //uid-категории
}
},
"Quantity": 1.0, //кол-во
"BuyPrice": 0.0, //закупочная цена (для накладных)
"SalePrice": 1590.0, //розничная цена
"Discount": 0.0 //скидка (для продажи)
}
],
"Payments": [ //массив платежей
{
"Uid": "191066a9-3f60-47c6-9352-6df63431eddd", //uid-платежа
"DateTime": "2020-12-27T10:28:55.784", //дата-время платежа (может не совпадать с датой документа, т.к. оплата может быть совершена позже)
"SumIn": 1590.0, //сумма, полученная по документу
"SumOut": 0.0, //сумма, выплаченная по документу
"Method": { //способ оплаты, может быть null
"Uid": "ec3fa8ee-e3b3-46dc-a736-62c3932590bd", //uid-способа
"Name": "Наличными" //название способа оплаты
},
"Type": "MoneyDocumentPayment" //тип оплаты
}
]
},
{
"Type": "Document",
"Uid": "f116d8af-fb6f-428b-8b90-9acf3f50e5b1",
"IsDeleted": false,
"DocumentType": "Buy", // входящая накладная
"DateTime": "2019-08-07T16:30:45.604",
"Items": [
{
"Uid": "f8b0df39-a7a7-4f5e-9163-f5dc2d9f88a6",
"Good": {
"Uid": "aded9bd2-35ec-47bd-93ad-750f57b214cf",
"Barcode": "4605840733826",
"Name": "личный счет триколор тв 100р",
"Group": {
"Name": "Оплата Триколор",
"Uid": "e1b32b53-5c2e-498f-8dc1-ec9ffd4be1be"
}
},
"Quantity": 100.0,
"BuyPrice": 100.0,
"SalePrice": 110.0,
"Discount": 0.0
}
]
}
]
}