Используйте эту главу, чтобы найти ID объектов, импортировать макет, загрузить коды или прочитать результаты. Сначала установите службу и выполните первый запрос. Все ID, пути и значения в примерах условные; замените их данными своего проекта.

Получить каталог

Запрос Что возвращает
GET /api/v1/labels Макеты
GET /api/v1/labels/{id} Один макет
GET /api/v1/products Товары
GET /api/v1/products/{id} Один товар
GET /api/v1/printers Настроенные принтеры проекта
GET /api/v1/orders Производственные задания
GET /api/v1/orders/{id} Одно задание
GET /api/v1/lines Настроенные линии
GET /api/v1/lines/{id}/status Сохранённое состояние линии и текущее задание

{id} — положительный внутренний идентификатор. Если объекта нет, API вернёт 404. Номер производственного задания orderNumber отличается от его id; при синхронизации нужны именно номера.

Для списков макетов, товаров, заданий и линий доступны limit от 1 до 500 и offset от 0. Без этих параметров вернётся весь список. Пример первой страницы товаров:

GET /api/v1/products?limit=25&offset=0

Следующую страницу получите с offset=25. У списка принтеров пагинации нет. Это список из проекта, а не поиск устройств в сети.

Ответы содержат основные свойства объектов: ID, название и параметры. Точный состав полей указан в GET /api/v1/openapi.json. У принтера printMode — число: 0 означает выбор режима в GUI, 1 — текстовый формат, 2 — графический. В запросах печати используются строки text и graph.

У линии поле id выбирает запись для GET /lines/{id}/status, а поле lineId используется в командах синхронизации.

Состояние линии берётся из данных проекта. Этот запрос не проверяет связь с работающей линией. Каталог доступен в том числе для MySQL; остальные ограничения базы отличаются.

Проверить принтер по TCP

Отправьте GET /api/v1/printers/{id}/status. API найдёт принтер в проекте и запросит его состояние по TCP-порту 9100. Проверка поддерживает TSC, GoDEX и ARNI. Если модель не поддерживается, API вернёт printer_status_not_supported; если устройство недоступно — printer_unavailable.

Для HTTP-панели ARNI используйте отдельные запросы. При подключении проекта через MySQL проверка принтера недоступна.

Проверить импорт макета

Импорт частичный. Изображения могут превратиться в поля-заглушки, а координаты и свойства объектов BarTender — восстановиться не полностью. Сначала получите предварительный результат, затем решайте, сохранять ли макет.

POST /api/v1/labels/import/preview принимает JSON:

Поле Как заполнить
contentBase64 Обязательное содержимое файла в Base64
fileName Необязательное имя исходного файла
language auto, tsc, godex или btw; без значения — автоматическое определение
ppm Необязательное положительное число точек на миллиметр

Поддерживаются текстовые файлы команд TSC/GoDEX и документы BarTender .btw. Для TSC без ppm программа пытается определить разрешение по командам и геометрии; если сведений не хватает, использует 8 точек/мм.

Ответ 200 содержит language, ppm, описание label, массив fields и warnings. У каждого предупреждения есть code и message, иногда строка и исходная команда. Проверьте размеры, содержимое и координаты полей. coordinateSource=synthetic означает приблизительно восстановленные координаты.

У BarTender в diagnostics могут быть изображения предпросмотра, метаданные и найденные строки. Наличие предпросмотра не доказывает, что все объекты восстановлены для редактирования. Встроенные изображения, шрифты, размеры и повороты объектов восстанавливаются не полностью. Выражения TSC BASIC могут остаться исходным текстом с предупреждением.

Предпросмотр не записывает данные и не требует открытого проекта. Для группы файлов без HTTP-службы есть команда CLI import-coverage.

Сохранить импортированный макет

POST /api/v1/labels/import принимает те же поля, что предпросмотр, и необязательный printerId. Укажите ID принтера явно, если в проекте их несколько. Без него программа использует первый доступный принтер.

  1. Получите и проверьте предварительный результат.
  2. Отправьте файл в labels/import с нужным printerId.
  3. Прочитайте label, fieldCount, language и warnings из ответа 200.
  4. Откройте сохранённый макет в редакторе и проверьте поля, изображения и размеры перед печатью.

Это синхронный импорт, без jobId. Повтор запроса может создать ещё один макет; заголовок идемпотентности команд здесь не применяется. Запись поддерживается в SQLite, PostgreSQL и Microsoft SQL Server. В GUI отдельной команды импорта этих файлов нет.

Получить статистику кодов

GET /api/v1/codes/statistics возвращает available и used. Необязательные фильтры: gtin и положительный orderId. Пример с условным ID задания:

GET /api/v1/codes/statistics?orderId=123

Доступными считаются включённые, неиспользованные, непроверенные и непросроченные коды. Коды с резервом другой операции в ответ не входят. При фильтре orderId учитываются коды выбранного задания и коды без привязки (OrderId=0). Срок рассчитывается от даты загрузки по времени сервера БД; 0 или NULL означает отсутствие ограничения. Просроченная строка остаётся в базе, но не входит в available.

Загрузить коды

При загрузке через API проверка дублей выполняется всегда. Она обрабатывает всю таблицу и может удалить старые неиспользованные дубли, даже если их нет в новом наборе. Параметра отключения проверки у этого запроса нет.

POST /api/v1/codes/import принимает:

Поле Как заполнить
codeType Обязательное individual для изделий или box для коробов
codes Обязательный непустой массив строк GS1
productId Необязательный ID товара
orderId Необязательный ID задания
codeLifeDays Неотрицательный срок в днях от загрузки; по умолчанию 0, без ограничения

Принимаются компактные GS1-строки, запись с идентификаторами применения в скобках и строки с разделителями GS. API получает сами строки кодов; CSV-файл с произвольными колонками в JSON не передаётся.

После ответа 202 дождитесь завершения задачи. В result проверьте insertedCount, duplicateDeletedCount и importedCount: число переданных строк может отличаться от числа кодов, оставшихся после проверки. Ответ также содержит тип кодов, срок и переданные фильтры.

Удалить коды

До запроса проверьте фильтр: интерактивного подтверждения у API нет. Без productId и orderId удаление затронет всю базу кодов.

POST /api/v1/codes/delete принимает обязательное usedOnly и один необязательный фильтр: productId или orderId. Одновременно задать оба нельзя. При usedOnly=true удаляются только использованные коды в выбранной области.

Пример удаления использованных кодов условного товара:

{"usedOnly": true, "productId": 10}

После 202 проверьте конечное состояние задачи и result.deletedCount. Для проверки оставшихся кодов снова запросите статистику.

Получить результаты задания

GET /api/v1/results/by-order/{id} возвращает orderId, resultsCount, rejectCount, boxCount и palletCount. Это итоговые счётчики локального задания, а не построчная история продукции.

Если результаты ещё находятся в базе линии, сначала загрузите их через синхронизацию. Чтение результатов и операции с кодами поддерживаются в SQLite, PostgreSQL и Microsoft SQL Server. Для MySQL эти операции не поддерживаются.