Local Printer API для веб-приложений и SaaS
Агент подключается к CloudPrint сам и передаёт сведения о доступных системных очередях печати. Ваша система получает их состояние через Public API, сохраняет выбранный `printer_id` и перед печатью проверяет возможности принтера.
Проверьте состояние агента
curl -sS 'https://public-api.cloudprint.me/api/v1/agents?limit=50' \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"agents": [
{
"agent_id": "22222222-2222-4222-8222-222222222222",
"name": "Warehouse PC agent",
"status": "online",
"hostname": "warehouse-pc",
"version": "0.1.1",
"update": {
"status": "up_to_date",
"current_version": "0.1.1",
"latest_version": "0.1.1",
"minimum_supported_version": "0.1.0",
"channel": "stable",
"required": false
},
"last_seen_at": "2026-06-08T10:10:00+00:00"
}
],
"next_cursor": null
}Для получения списка нужно разрешение agents:read. Агент должен иметь статус online. При диагностике также проверяйте update.required и сведения о версии.
Получите принтеры
curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \
-H "Authorization: Bearer $ACCESS_TOKEN"Сокращённый ответ с полями выбора:
{
"printers": [
{
"printer_id": "11111111-1111-4111-8111-111111111111",
"agent_id": "22222222-2222-4222-8222-222222222222",
"name": "Warehouse Label Printer",
"status": "online",
"agent_name": "Warehouse PC agent",
"agent_status": "online",
"capabilities": {
"backend": "windows_native",
"language_profiles": [
{
"language": "zpl",
"version": "zpl2"
}
],
"supports_custom_media": true,
"supports_orientation": true,
"supports_copies": true,
"supported_dpi": [
203
]
},
"endpoint": {
"system_print_available": true,
"raw_passthrough_available": true,
"os": "windows",
"driver_name": "ZDesigner ZD421-203dpi ZPL",
"connection_type": "windows_spooler"
},
"status_evidence": {
"source": "windows_spooler",
"reasons": [
"paper_out"
],
"accepting_jobs": true,
"queued_jobs": 3
}
}
],
"next_cursor": null
}Сохраните правильный ID
Храните printer_id в настройке филиала, упаковочного места или процесса. Администратору показывайте name, agent_name и статус, но не маршрутизируйте по имени. После пересоздания системной очереди требуйте повторное назначение и тест.
Разделяйте состояние устройства и готовность очереди
status описывает физическое или настроенное состояние принтера. status_evidence содержит последнее наблюдение очереди: source принимает cups_ipp, windows_spooler, configured или unknown; reasons перечисляет нормализованные состояния устройства и службы печати; accepting_jobs показывает, может ли системная служба печати надёжно принять новое задание; queued_jobs — снимок системной очереди, а не число ожидающих заданий CloudPrint. Значения null не подтверждают готовность. При агенте со статусом online и системном accepting_jobs=true очередь может принимать задания во время временного предупреждения устройства, но это предупреждение нужно показывать оператору.
Проверьте возможности принтера
Для RAW нужен подходящий language_profiles[*].language и значение raw_passthrough_available=true. Для PDF должна быть доступна системная печать или поддерживаемое CloudPrint преобразование. Перед использованием нестандартного режима цвета, двусторонней печати, ориентации, количества копий, размера носителя, масштаба, смещения или DPI проверьте соответствующие поля возможностей.
Пагинация и недоступные очереди
Оба списка возвращают next_cursor. Запрашивайте ?limit=100&cursor=VALUE, пока не получите null. Остановите автоматическую маршрутизацию, если агент не в сети или данные системной очереди не подтверждают приём заданий. Не выбирайте молча принтер другого филиала.
Что означают данные подключения
Поля драйвера, порта, операционной системы и типа подключения описывают локальную очередь печати и нужны для диагностики. Это не адрес, который должен вызывать ваш сервер. Учётные данные в URI устройства скрываются перед выдачей ответа.