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

1 Логика работы
2 Алгоритм работы
3 Метод веб-сервиса для генерации задания на создания изображения ценника
4 Настройка срока хранения изображения
5 Пример работы запроса в программах отладки
- 5.1 SoapUI
- 5.2 Postman
6 Дополнительная информация
- 6.1 Папка риснуков на сервере nginx

Логика работы

Метод, в рамках одного вызова (синхронно) выполняет:

по входящим данным полученным в формате JSON (по штриховому коду) определяет товар;
по настройкам привязок шаблонов ценников или форматов ценников определяет шаблон (шаблоны) ценника, (или по присланному коду шаблона ценника) который должен быть напечатан на этот товар.
генерирует изображение ценника по найденному шаблону;
сохраняет изображение ценника в формате PNG или BMP в заданную папку на жесткий диск сервера Set Retail 10;
возвращает в ответ на запрос пакет информации, включающий в себя:
- Информацию о найденном товаре;
- Информации о привязанном шаблоне ценника;
- Информацию о сгенерированном экземпляре ценника;
- Ссылку на файл с сохранённым изображением ценника в формате PNG или BMP для возможности его скачать с сервера Set Retail 10.
- Сообщение об ошибке, если что-то пошло не так.

Алгоритм работы

При вызове метода, будет передан логин пользователя. Пользователь передается для справочной информации и должен присутствовать в списке на сервере SetRetail10.
Запоминается значение атрибута downloadMethod из запроса для выдачи ответа в формате локальной ссылки на файл или url для скачивания через сайт, или выдачи изображения в теле самого ответа.
По списку ШК из секции arguments производится поиск товара в справочнике Setretail10. Так же учитывается, что может быть указан весовой ШК с весом, который предварительно разбирается по правилам парсинга весовых ШК для конкретного весового префикса, установленных в типах весового товара.
Если товар не найден, или ШК не привязан к товару, или товар (или ШК) удалён, тогда для таких товаров возвращается сообщение о соответствующей ошибке.
Код шаблона ценника может быть задан в запросе, тогда дополнительного поиска шаблонов привязанных к товару производить не надо. При печати необходимо будет использовать только этот шаблон.
Если код шаблона ценника не задан в запросе, то по каждому найденному товару находится привязанный к товару шаблон ценника по всем возможным вариантам привязки (регулярные и скидочные, в том числе и по “форматам”, а также “шаблон для всего товарного справочника”). Таких шаблонов может быть несколько. Это означает что все их необходимо будет сгенерировать и указать отдельно в массиве labels. На данном этапе возможно возникновение ошибки, когда к найденному товару не будет привязано ни одного шаблона ценника, соответственно в ответе необходимо будет выдать соответствующее сообщение об ошибке.
По каждому найденному шаблону указывается соответствующая информацию в ответе (код, название, тип, цвет, размеры).
Далее по каждому найденному шаблону генерируется сам ценник в виде изображения.
Для генерации ценника используются только актуальные данные и действующие цены, то есть, данный метод эмулирует печать ценников с полки “произвольной печати” по нажатию на кнопку “Печать по умолчанию“, но без учёта привязки шаблонов к принтерам.
Если в запросе не было указано информации о размерах листа и количестве экземпляров (блок groupOnPage), то по умолчанию генерируется один экземпляр ценника для каждого шаблона на листе, который размерами соответствует размеру шаблона.
Если в запросе были указаны размеры листа и количество ценников (блок groupOnPage), тогда размещается заданное количество экземпляров ценников по каждому найденному (или заданному в запросе) шаблону ценника на листах указанного размера с соблюдением заданных отступов. В данном варианте также может возникнуть ошибка, когда размеры шаблона ценника превышают размеры листа.
После генерации ценников каждый лист с ценником (или с ценниками) сохраняется как файлы на диск в отдельную папку (путь из настройки) в формате указанном в параметре imageFormat в запросе PNG, BMP (если не указан, то в формате по умолчанию - PNG ). Имя файла создается уникальным в рамках каждого шаблона, поэтому для формирования имени файла используются такие данные как - штриховой код товара из запроса, код найденного шаблона ценника, дата и время в полном формате с учётом миллисекунд.
В зависимости от значения параметра downloadMethod, полученного в запросе, в ответе в блоке labelsPath указываются ссылки на все сохранённые листы с ценниками по каждому конкретному шаблону.
Если в downloadMethod был указан метод response, тогда сохранённый файл передается в теле ответа в текстовом поле labelsImageBody, в виде закодированного содержимого файла с изображением в формате base64.

Метод веб-сервиса для генерации задания на создания изображения ценника

Создать изображение ценника
Метод	generatePriceTags
URL	http://IP-адрес сервера SetRetail10:8090/SET-GeneratePriceTagImages-REST/generatePriceTags
Тип запроса	POST
Комментарий	Создать задание на печать ценников.

Входящие параметры метода (JSON)

Родительский сегмент/Название	Тип	Описание	Обязательное

Родительский сегмент/Название	Тип	Описание	Обязательное
downloadMethod	String	Вариант указания ссылки в ответе: `web` - ссылка (URL) на файл на сайте сервера для возможности скачивания через HTTP-протокол `response` - сгенерированное изображение отправить обратно в теле ответа в виде последовательности байтов из файла с изображением в виде base64. По умолчанию `web`.	Нет
imageFormat	String	Формат, в котором необходимо сохранить изображение с ценником. Возможен один из следующих вариантов: PNG, BMP, JPEG. По умолчанию, если не указать параметр будет использован формат PNG	Нет
faked https://crystals.atlassian.net/browse/SRTS-281 https://crystals.atlassian.net/browse/CR-6224 10.3.4.0	Boolean	Признак необходимости генерации и возврата картинки ценника `faked = true` - не надо генерировать ценник и возвращать его и/или ссылку на него; `faked = false` - надо генерировать ценник и надо возвращать его и/или ссылку на него; По умолчанию отсутствует, то есть `faked = false`. Пример запроса Пример ответа	Нет
arguments	Complex (array)	Блок для однократного или множественного указания нескольких атрибутов для идентификации товаров и/или шаблонов ценников.	Да
arguments/ barcode	String	Штриховой код товара. по данному ШК происходит поиск товара для печати ценника. может не совпадать с ШК напечатанным на ценнике по найденному товару, так как на ценнике печатается ШК по умолчанию. Также возможно будет указан весовой ШК с необходимостью разбора по настройке префиксов.	Да
arguments/ templateCode	String	Возможно указание кода шаблона ценника (внешний код). При указании кода шаблона ценника в этом поле, искать привязки шаблонов ценника к товару не надо. Ценник должен быть напечатан с использованием именного этого шаблона.	Нет
arguments/ groupOnPage	Complex	Блок описывающий возможность печати нескольких ценников на одном листе.	Нет
arguments/groupOnPage/ labelsCount	Integer	Количество экземпляров ценников которые надо напечатать. По умолчанию 1.	Нет
arguments/groupOnPage/ pageWidth	Integer	Ширина листа (в мм.) на котором необходимо разместить ценники. По умолчанию = ширине шаблона ценника.	Нет
arguments/groupOnPage/ pageHeight	Integer	Высота листа (в мм.) на котором необходимо разместить ценники. По умолчанию = высоте шаблона ценника.	Нет
arguments/groupOnPage/ pagePadding	Integer	Отступы от краёв листа для размещения ценников. По умолчанию = 0 мм. т.е. ценники будут прижаты вплотную к верхнему левому краю листа.	Нет

Параметры ответа метода (JSON)

Родительский сегмент/Название	Тип	Описание	Обязательное

Родительский сегмент/Название	Тип	Описание	Обязательное
access	String	Cтатус наличия привилегии на выполнение данной операции: `granted` - у указанного пользователя есть привилегия на использование API по удалённой мобильной печати ценников `deny` - у указанного пользователя нет привилегии на печать ценников	Да
results	Complex (array)	Блок данных с результатами выполнения генерации ценников по найденным товарам. Один элемент массива - это один ШК из запроса	Да
results/ barcode	String	Штриховой код товара, из запроса, для возможности идентификации ответных данных.	Да
results/ item	String	Код, артикул найденного товара.	Нет
results/ name	String	Наименование найденного товара.	Нет
results/ errorCode	Integer	Код сообщения об ошибке, если она произошла. По умолчанию атрибуты с кодом и текстом ошибки отсутствуют.	Нет
results/ errorMessage	String	Текст сообщения об ошибке.	Нет
results/ labels	Complex (array)	Блок данных с описанием шаблонов ценников по найденному товару. Один элемент массива - это один шаблон ценника	Да
results/labels/ templateCode	String	Код найденного шаблона ценника привязанного к товару, код полученный из запроса. Берётся из поля “внешний код” в справочнике шаблонов ценников. может быть пустым, если поле “внешний код“ не задано в шаблоне ценника.	Да
results/labels/ templateName	String	Наименование найденного шаблона ценника. Если задано название в шаблоне.	Нет
results/labels/ templateWidth	Integer	Ширина найденного шаблона ценника в мм.	Да
results/labels/ templateHeight	Integer	Высота найденного шаблона ценника в мм.	Да
results/labels/ templateType	String	Тип шаблона ценника: `regular` - регулярный `discount` - скидочный. По умолчанию регулярный.	Нет
results/labels/ templateColor	Integer	Цвет найденного шаблона ценника из справочника шаблонов. Варианты: `red` `blue` `green` `orange` `yellow` `violet`	Да
results/labels/ pageWidth	Integer	Ширина листа в мм. на котором помещён экземпляр ценника (или ценников). т.е. это размер сгенерированного изображения по ширине в мм. По умолчанию = ширине шаблона ценника.	Да
results/labels/ pageHeight	Integer	Высота листа в мм. на котором помещён экземпляр ценника (или ценников). т.е. это размер сгенерированного изображения по высоте в мм. По умолчанию = высоте шаблона ценника.	Да
results/labels/ labelsCount	Integer	Количество ценников размещённых на одном листе, или на листах. По умолчанию 1. Например если было нарисовано 13 ценников на 3-х листах (2 листа по 5 ценников и на одном листе 3), то тут будет указано 13.	Нет
results/labels/ labelsPath	Complex (array)	Блок данных - массив со списком ссылок на файлы - листы с ценниками, или одна ссылка на один файл с одним ценником. Если был указан вариант получения ссылки для скачивания `web`, то ссылка представляется как путь до изображения на сайте сервера SetRetail10, например: http://172.29.16.87:8090/png_labels/4602701200442_2021-02-11_19-12-22-913.png Массив может быть пустым, если ценники сформировать не удалось	Нет
results/labels/ labelsImageformat	String	Формат, в котором было сохранено изображение с ценником. Возможен один из следующих вариантов: PNG BMP JPEG По умолчанию формат PNG	Нет
results/labels/ labelsImageBody	Array base64Binary (String)	Массив, в котором будет содержимое файла изображения этикетки в виде последовательности байт, закодированных в base64 стандарте. Один элемент массива - один ценник, т.е .файл. Заполняется только при варианте настройки в запросе `downloadMethod = “response"`	Нет

Примеры запроса и ответа

Пример запроса на генерацию ценника

{
  "downloadMethod": "web",
  "imageFormat": "png",
  "arguments": [
    {
      "barcode": "4810167000258",
      "templateCode" : "76834",
      "groupOnPage": {
        "labelsCount": 1,
        "pageWidth": 60,
        "pageHeight": 40
        
      }
    }
  ]
}

Пример ответа на генерацию ценника

{
    "access": "granted",
    "results": [
        {
            "barcode": "4810167000258",
            "item": "45034",
            "name": "Хлеб РЖАНОЙ",
            "errorCode": null,
            "errorMessage": null,
            "labels": [
                {
                    "templateCode": "76834",
                    "templateName": "60 x 40",
                    "templateWidth": 60.0,
                    "templateHeight": 40.0,
                    "templateColor": "green",
                    "templateType": "regular",
                    "pageWidth": 60,
                    "pageHeight": 40,
                    "labelsCount": 1,
                    "labelsPath": [
                        "http://192.168.56.1:8091/image-printer-output/2021-05-24_16-15-32_1621862132453.png"
                    ],
                    "labelsImageFormat": "png",
                    "labelsImageBody": []
                }
            ]
        }
    ]
}

Коды и тексты ошибок

Код errorCode	Текст ошибки errorMessage	Описание

Код errorCode	Текст ошибки errorMessage	Описание
2	ШК `barcode` не найден	Если указанный ШК отсутствует в справочнике ШК в БД, или удалён
3	Товар по ШК `barcode` не найден	Если указанный ШК есть в справочнике ШК в БД, но он не привязан ни к одному товару, или товар по этому ШК удалён
4	Для товара с ШК `barcode` не задан шаблон ценника по умолчанию	По найденному товару не удалось обнаружить ни одной привязки к шаблону ценников ни по одному из возможных методов привязки
5	Шаблон ценника с кодом `templateCode` не найден	В случае когда в запросе был указан код шаблон ценника которого нет в справочнике шаблонов ценников в БД. Также возможен вариант когда код не существующего шаблона ценника указан у товара в привязке (например в цене)
6	Размер шаблона `templateWidth` x `templateHeight` больше размера листа `pageWidth` x `pageHeight`	Это в случае невозможности размещения ценника сгенерированного по найденному или указанному шаблону на листе с заданными в запросе размерами.
7	Невозможно сохранить файл с ценником в каталоге `path(labelsPath)`	Эта ошибка может возникнуть в случае отсутствия свободного места на диске или в случае отсутствия доступа до папки. Имя папки для сохранения изображений с ценниками задаётся в отдельной настройке.
8	Параметры не заданы	Пустой запрос
9	ШК не указан	ШК не указан в запросе
10	Что-то пошло не так	В процессе обработки запроса произошла ошибка

Пример ответа c ошибкой

{
    "access": "granted",
    "results": [
        {
            "barcode": "4810167000218",
            "item": null,
            "name": null,
            "errorCode": 2,
            "errorMessage": "ШК 4810167000218 не найден",
            "labels": []
        }
    ]
}

Пример ответа c ошибкой

{
    "access": "granted",
    "results": [
        {
            "barcode": "4810167000258",
            "item": "45034",
            "name": "Хлеб РЖАНОЙ",
            "errorCode": 6,
            "errorMessage": "Размер шаблона 60 x 40 больше размера листа 50 x 40",
            "labels": [
                {
                    "templateCode": "76834",
                    "templateName": "60 x 40",
                    "templateWidth": 60.0,
                    "templateHeight": 40.0,
                    "templateColor": "green",
                    "templateType": "regular",
                    "pageWidth": 50,
                    "pageHeight": 40,
                    "labelsCount": 1,
                    "labelsPath": [],
                    "labelsImageFormat": "png",
                    "labelsImageBody": []
                }
            ]
        }
    ]
}

Настройка срока хранения изображения

По умолчанию изображения ценников хранятся в папке сервера 1 день.

Для изменения настройки выпролните скрипт в базе данных

set, указав количество дней хранения.

UPDATE sales_management_properties
   SET property_value='1'
WHERE property_key='output.dir.clean.pictures.save.days';

Пример работы запроса в программах отладки

SoapUI

1. Кликните REST → в поле URI введите адрес следующего формата для генерации изображения ценников http://IP-адрес сервера SetRetail:8090/SET-GeneratePriceTagImages-REST/generatePriceTags → кликните OK.

2. Из спискоа Method выберите POST → из списка Media Type выберите application/json → вставьте запрос для генерации изображения ценника.

3. Нажмите кнопку для выполнения запроса → перейдите на вкладку JSON → появится ответ со ссылкой на изображение ценника.

4. Скопируйте и вставьте ссылку в адресную строку браузера → нажмите Enter для загрузки изображения ценника.

Postman

1. На вкладке запроса выберите POST → введите адрес следующего формата для генерации изображения ценников http://IP-адрес сервера SetRetail:8090/SET-GeneratePriceTagImages-REST/generatePriceTags → вставьте JSON-запрос для формирования ценика → кликните SEND → появится ответ от сервера со ссылкой на изображение ценника.

Веб-сервис REST для генерации изображений ценников

Логика работы

Алгоритм работы

Метод веб-сервиса для генерации задания на создания изображения ценника

Создать изображение ценника

Входящие параметры метода (JSON)

Параметры ответа метода (JSON)

Примеры запроса и ответа

Пример запроса на генерацию ценника

Пример ответа на генерацию ценника

Коды и тексты ошибок

Пример ответа c ошибкой

Пример ответа c ошибкой

Настройка срока хранения изображения

Пример работы запроса в программах отладки

SoapUI

Postman