Подключение агента и выбор принтера
Агент через исходящее соединение сообщает CloudPrint о системных очередях принтеров. Интеграция читает их состояние из Public API, сохраняет `printer_id` CloudPrint и проверяет возможности перед печатью.
Проверьте агент
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"
}
}
],
"next_cursor": null
}Сохраните правильный ID
Храните printer_id в настройке филиала, упаковочного места или процесса. Администратору показывайте name, agent_name и статус, но не маршрутизируйте по имени. После пересоздания системной очереди требуйте повторное назначение и тест.
Возможности принтера — это контракт
Для RAW требуется совпадение language_profiles[*].language и raw_passthrough_available=true. Для PDF требуется системная печать или доступный маршрут преобразования. Перед использованием нестандартных параметров цвета, двусторонней печати, ориентации, числа копий, носителя, масштаба, смещения и DPI проверяйте возможности принтера.
Пагинация и недоступные принтеры
Оба списка возвращают next_cursor. Запрашивайте ?limit=100&cursor=VALUE, пока не получите null. Не создавайте автоматическое задание для принтера, который не в сети, если продукт явно не поддерживает очередь; не выбирайте молча принтер другого филиала.
Что означают данные подключения
Поля драйвера, порта, операционной системы и типа подключения описывают локальную очередь печати и нужны для диагностики. Это не адрес, который должен вызывать ваш сервер. Учётные данные в URI устройства скрываются перед выдачей ответа.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.