API позволяет читать данные проекта, печатать этикетки и обмениваться данными с линиями без открытого окна LabelRedo. Здесь собраны общие настройки и правила запросов для администратора и разработчика интеграции.

При первом подключении начните с установки API, затем прочитайте товары из проекта.

Задача Инструкция
Прочитать каталог, импортировать макет или загрузить коды Данные через API
Напечатать этикетки или получить файл команд Печать через API
Обменяться заданиями, результатами и справочниками Синхронизация через API
Проверить или настроить принтер ARNI Управление ARNI через API
Выполнить команду без HTTP-службы Командная строка CLI

Выбрать проект и адрес службы

Настройки JSON находятся внутри объекта LabelRedoApi. Вместо JSON можно использовать переменные окружения процесса службы.

Параметр JSON Переменные окружения, от высшего приоритета к низшему Значение
Host LabelRedoApi__Host, LABELREDO_API_HOST По умолчанию 127.0.0.1; нужен IP-адрес, не имя сервера
Port LabelRedoApi__Port, LABELREDO_API_PORT По умолчанию 5084; допустимо 1–65535
AllowLan LabelRedoApi__AllowLan, LABELREDO_API_ALLOW_LAN false по умолчанию; допустимы true и false
ProjectFilePath LabelRedoApi__ProjectFilePath, LABELREDO_API_PROJECT Путь к .sld, .slf или .sdf
ApiToken LabelRedoApi__ApiToken, LABELREDO_API_TOKEN Токен клиента; без него API не запускается

Переменная окружения заменяет одноимённое значение JSON. LABELREDO_API_CONFIG задаёт путь к файлу JSON; если такого файла нет, запуск завершится ошибкой. Без этой переменной программа ищет первый существующий appsettings.json: рядом с API, затем в lable_redo_v4.Api рабочего каталога, затем в самом рабочем каталоге. Файлы не объединяются.

На службе Windows путь к api-settings.json задаётся при запуске службы. После изменения пути проекта, токена или адреса перезапустите API: команда обновления проекта не перечитывает настройки процесса. Общие каталоги программы описаны в настройках и журналах.

Разрешить доступ из сети

Для работы с того же компьютера оставьте Host=127.0.0.1 и AllowLan=false. Для другого компьютера администратор задаёт сетевой IP и AllowLan=true, затем настраивает доступ к порту.

Сама служба передаёт HTTP без шифрования. Для сетевого доступа используйте HTTPS через обратный прокси или другой защищённый канал: токен не должен идти по открытой сети. В режиме LAN действует ограничение 60 запросов в минуту с одного адреса; при превышении служба отвечает 429 rate_limited.

Проверить подключение

Получите адрес и токен у администратора. Токен нужен на всех маршрутах, включая проверку работы службы и схему. Выберите один заголовок:

Authorization: Bearer <token>

или X-LabelRedo-Api-Key: <token>. Здесь <token> — место для вашего значения. Если отправлены оба заголовка, API проверяет X-LabelRedo-Api-Key.

Запрос Результат
GET /api/v1/health Служба отвечает; это ещё не проверка базы
GET /api/v1/version Версия API, .NET и ОС
GET /api/v1/project/status Настроен ли проект, верен ли файл, доступна ли база
POST /api/v1/project/reload Заново прочитать текущий проект и проверить базу; тело не требуется
GET /api/v1/openapi.json Точные схемы запросов и ответов этой сборки
GET /api/v1/metrics Счётчики HTTP-ответов, конечных состояний задач и времени выполнения

В project/status отдельно проверяйте isConfigured, isValid и isDatabaseReachable. Состояние кэшируется; для новой проверки вызовите project/reload. Изменение проекта не перенаправляет уже принятые задачи на другую базу.

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

Дождаться результата операции

Команды печати, кодов, синхронизации и управления ARNI возвращают 202 с jobId. Это означает, что задача принята. Импорт макета и чтение данных имеют обычный ответ 200; для них ждать задачу не нужно.

  1. Сохраните jobId из ответа.
  2. Получайте GET /api/v1/jobs/{jobId}, например раз в 2–5 секунд.
  3. Дождитесь одного из конечных состояний и прочитайте результат.
state Что делать
Queued Задача ожидает выполнения; продолжайте опрос
Running Задача выполняется; продолжайте опрос
Succeeded Прочитайте result и проверьте результат нужной операции
Failed Прочитайте errorCode, message и result; не повторяйте команду автоматически
Rejected Исправьте причину отказа, указанную в errorCode и message

Ответ также содержит command, resourceKey, createdUtc и finishedUtc. Время указано в UTC. result — словарь строк с результатом конкретной команды; состав полей описан в её главе.

После перезапуска незавершённые задачи получают Failed с кодом service_restarted: служба не может доказать, какие действия успели выполниться. Завершённые задачи хранятся 30 дней. После удаления записи запрос вернёт 404; заранее сохраняйте нужные результаты у клиента.

Повторить запрос без новой задачи

Для повторной доставки той же команды передайте X-LabelRedo-Idempotency-Key с ключом, созданным клиентом. Тот же маршрут, ключ и содержимое запроса возвращают исходную задачу. Другое содержимое с тем же ключом даёт 409 idempotency_conflict.

Это правило действует для команд с задачами, а также принятия и удаления привязки ARNI. Оно не превращает повторный labels/import в безопасную операцию. После удаления старой задачи исчезает и запись её ключа.

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

Разобрать ошибку

Ошибка HTTP содержит code, message, details и correlationId. Идентификатор также приходит в X-Correlation-Id; передайте его администратору для поиска записи в журнале. Тела запросов и токены в журнал запросов не записываются.

Код или группа Что проверить
401 unauthorized Токен и заголовок авторизации
400 invalid_json, invalid_request, validation_error JSON, типы, положительные ID и ошибки полей в details
400 invalid_project Путь и формат проекта
404 not_found Маршрут, ID объекта или срок хранения задачи
409 job_conflict Другая задача уже использует тот же принтер, линию или коды
409 project_schema_upgrade_required Обновите структуру базы через GUI; API не показывает окно обновления
project_schema_version_missing, project_schema_version_unreadable Строку версии схемы и доступ к ней
501 provider_not_implemented, not_implemented Поддержку выбранного типа базы и операции
502 provider_error Подключение к БД и права учётной записи службы
503 printer_unavailable Адрес, сеть и состояние принтера
500 internal_error Журнал службы по correlationId

Ошибка HTTP возникает до принятия задачи. После 202 отказ приходит в JobResponse.errorCode; проверка только HTTP-кода опроса пропустит такую ошибку. Журнал Linux можно открыть командой journalctl -u labelredo4-api.service; каталоги журналов описаны отдельно.

Проверить поддержку базы

База проекта Доступные операции
SQLite, PostgreSQL, Microsoft SQL Server Каталог, коды, результаты, импорт макетов и поддерживаемые режимы печати
MySQL Списки макетов, товаров, принтеров, заданий и линий; чтение отдельных объектов и сохранённого состояния линии

Для MySQL недоступны проверка доступности базы через project/status, состояние принтера, операции ARNI, печать, коды, результаты и синхронизация. Предпросмотр импорта работает без записи в базу. Для полного переноса данных используйте отдельную миграцию MySQL в PostgreSQL.

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