Эти запросы работают с принтером ARNI, уже настроенным в проекте API. Сначала настройте службу и получите ID из списка принтеров. Перед изменением параметров или очисткой очереди согласуйте действие с другими пользователями устройства.

В таблицах {id} — положительный ID принтера в проекте. API обращается к HTTP-порту 80 его настроенного адреса. Передать произвольный URL или команды прошивки в теле запроса нельзя. Подключение проекта через MySQL для этих операций не поддерживается.

Подтвердить привязку

Привязка помогает проверить, что по настроенному адресу отвечает нужное устройство. Проверка адреса сама по себе не подтверждает привязку.

Запрос Действие
GET /api/v1/printers/{id}/arni/info Прочитать возможности и сведения о привязке из проекта
GET /api/v1/printers/{id}/arni/binding Прочитать сохранённую привязку
POST /api/v1/printers/{id}/arni/binding/probe Проверить устройство; тело {}
PUT /api/v1/printers/{id}/arni/binding Подтвердить найденное устройство
DELETE /api/v1/printers/{id}/arni/binding Удалить локальную привязку; настройки принтера не меняются
  1. Выполните binding/probe.
  2. Сверьте observedDeviceId с нужным устройством.
  3. Передайте в PUT binding его значение как expectedObservedDeviceId, а projectRevision скопируйте из того же ответа.
  4. Проверьте результат привязки.

expectedObservedDeviceId содержит идентификатор принтера из 24 шестнадцатеричных символов. projectRevision связывает подтверждение с версией данных проекта, по которой API проверил принтер. Берите оба значения из одного ответа binding/probe. Перед сохранением привязки API повторно проверяет устройство. Чтение info и binding не обращается к принтеру.

После изменения адреса или устройства подтвердите привязку заново. Если API вернул 409, прочитайте код ошибки и сверьте устройство и проект перед повторным подтверждением.

Прочитать состояние и очередь

Для чтения устройства нужна действующая привязка.

Запрос Результат и параметры
GET /api/v1/printers/{id}/arni/status Состояние, ошибка, счётчики очереди pending и printed, актуальность данных freshness
GET /api/v1/printers/{id}/arni/config dhcp, servicePort, ip, mask, gateway, dns
GET /api/v1/printers/{id}/arni/queue Очередь; limit от 1 до 100, по умолчанию 25; offset от 0
GET /api/v1/printers/{id}/arni/jobs История обработки заданий в принтере ARNI; limit от 1 до 16, по умолчанию 16
GET /api/v1/printers/{id}/arni/jobs/{jobId} Одна запись: latest либо R и ненулевой номер UInt32

В ответе status поле freshness показывает актуальность данных состояния: Fresh — актуальны на момент проверки, Stale — устарели, Unknown — актуальность не удалось определить. Успешный HTTP-ответ сам по себе не подтверждает актуальность.

pending и printed — счётчики ожидающей и выполненной печати из очереди принтера. Они не подтверждают число копий отдельной задачи API.

Пример с условным ID принтера:

GET /api/v1/printers/1/arni/queue?limit=25&offset=0

История обработки заданий в принтере ARNI хранится отдельно от задач службы /api/v1/jobs/{jobId}. При found=false нужной записи нет в доступной истории; результат печати неизвестен.

isFinalized=true означает, что принтер завершил обработку задания. Так бывает и после отмены или ошибки: состояние completed не означает, что все копии напечатаны. История не содержит подтверждённого количества отпечатков, поэтому physicalOutcomeKnown=false.

Проверить доступность диагностики

GET /api/v1/printers/{id}/arni/diagnostics/{kind} принимает один из видов:

kind Область
render-last Формирование последнего изображения этикетки
parser Разбор команд
ethernet Сетевой обмен
datamatrix DataMatrix
tph-health Термоголовка
latency Задержки
service Сервисная диагностика
error-journal Журнал ошибок

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

Приостановить или продолжить печать

Запрос Тело
POST /api/v1/printers/{id}/arni/commands/pause {}
POST /api/v1/printers/{id}/arni/commands/resume {}

После 202 дождитесь завершения задачи службы. API отправляет команду и проверяет, перешёл ли принтер в нужный режим. Если подтверждения нет, задача может завершиться как Failed с arni_unconfirmed; проверьте принтер до повторного действия.

Изменить параметры устройства

Изменение адреса может прервать связь с устройством. До запроса сохраните текущие параметры и проверьте, как подключиться к принтеру после изменения.

POST /api/v1/printers/{id}/arni/commands/config принимает JSON только с изменяемыми полями:

Поле Допустимое значение
dhcp, dhcpFillMissing true или false
ip, mask, gateway, dns IPv4 в записи с точками; для статических адресов DHCP должен быть выключен
servicePort Только 9100; это TCP-порт печати, не HTTP-порт
offsetX Целое число 0–200
shiftX, offsetY Целое число −100–200
renderOverscanMm Целое число 0–5
printSpeed Целое число 2–12
backfeedSpeed Целое число 2–8
darkness Целое число 0–19

Пример изменения одного параметра; значение условное, подберите его для своего материала:

{"darkness": 8}

Передайте хотя бы один параметр из таблицы. Параметры, которые не нужно менять, не включайте в запрос. Для ip, mask, gateway и dns DHCP должен быть выключен в текущем состоянии или этим же запросом через dhcp=false.

Тело запроса ограничено 4 КиБ и 16 уровнями вложенности. Неизвестные и повторяющиеся имена полей запрещены. Такие же ограничения действуют для JSON-тел проверки и подтверждения привязки, паузы, продолжения и очистки очереди. После завершения задачи проверьте состояние устройства. GET config возвращает только сетевые поля из таблицы чтения, а не весь набор параметров печати.

Очистить очередь

Команда прерывает загрузку данных и запрашивает остановку активной печати и отмену ожидающих заданий, включая задания других пользователей. Очистка не отменяет уже выполненную печать. До запроса убедитесь, что выбрано нужное устройство.

Отправьте POST /api/v1/printers/{id}/arni/commands/clear-queue:

{"confirmClear": true}

После 202 проверьте результат задачи и состояние принтера. Приём команды принтером ещё не подтверждает завершение очистки.

Обработать неопределённый результат

Команды ARNI возвращают задачу службы. При arni_unconfirmed и safeToRetry=false нельзя автоматически посылать новую команду, даже с новым ключом идемпотентности. Проверьте устройство и результат предыдущего действия.

503 означает, что связаться с принтером не удалось. При 502 проверьте code: API не смог обработать ответ принтера либо прочитать, сохранить или удалить привязку.

Если API вернул arni_identitymismatch, сверьте адрес и идентификатор принтера. При arni_project_changed, arni_target_changed или arni_probe_stale проверьте привязку заново. Для подтверждения возьмите идентификатор принтера и projectRevision из нового успешного ответа binding/probe.

В одном процессе службы запросы управления к одному адресу ARNI выполняются по очереди. Эта очередь не блокирует команды от другого экземпляра GUI, API, CLI или сторонней программы. Для копий через HTTP ARNI используется отдельный сценарий print/copies с собственными ограничениями и подтверждением количества.