Настройка агента для управляемого аккаунта
Agent Enrollment подключает один или несколько локальных CloudPrint Agents к нужному клиентскому аккаунту без регистрации и входа клиента в CloudPrint.
Безопасно повторяйте создание Enrollment
При создании аккаунта CloudPrint возвращает одноразовую ссылку agent_onboarding_url. Второй компьютер можно подключить через POST /partner-api/v1/accounts/{relationshipId}/agent-enrollments с обязательным Idempotency-Key. Точный повтор возвращает прежние Enrollment ID, срок действия и ссылку. До первого запроса сохраните ключ, state, имя, адрес возврата и необязательный replaces_enrollment_id; при повторе меняется только JWT-подтверждение приложения. Для замены известного неиспользованного Enrollment передайте replaces_enrollment_id.
Отслеживайте конкретный Enrollment
Сохраните agent_enrollment_id из ответа и проверяйте GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Продолжайте опрос при статусе pending; когда он сменится на claimed, сохраните возвращённый agent_id. Остановитесь при expired или revoked. Ответы GET и списка не повторяют секретную ссылку подключения, поэтому до завершения процесса храните ответ на создание в защищённом месте. Проверка конкретного Enrollment также не позволит принять ранее подключённый агент за компьютер, использовавший новую ссылку.
Получайте список и отзывайте Enrollment
GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments возвращает записи со статусами pending, claimed, expired и revoked без секретных кодов. Отзовите неиспользованный код через DELETE /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Повторный отзыв безопасен.
Получайте список и отзывайте агентов
Показывайте подключённые компьютеры с помощью GET /partner-api/v1/accounts/{relationshipId}/agents. Потерянный, сломанный или заменённый компьютер отзовите через DELETE /partner-api/v1/accounts/{relationshipId}/agents/{agentId}, после чего создайте Enrollment для нового компьютера. Принтеры отозванного агента перейдут в статус offline.
Восстановите потерянный ответ
Повторите тот же запрос с новым одноразовым JWT-подтверждением и прежним Idempotency-Key для Enrollment. Пока хранится запись идемпотентности, CloudPrint вернёт исходную ссылку подключения. Другое тело или другой путь с тем же ключом вернёт 409 partner.idempotency.conflict. Не создавайте новый ключ, если результат предыдущего запроса неизвестен.
Откройте страницу подключения
По умолчанию открывайте полную ссылку agent_onboarding_url, включая фрагмент #token. Если connect.cloudprint.me недоступен из сети клиента, замените только имя хоста на connect.cloudprint.by, сохранив схему https, путь /setup и весь фрагмент #token без изменений. Например, https://connect.cloudprint.me/setup#token=… превращается в https://connect.cloudprint.by/setup#token=…. Это официальное зеркало страницы подключения, а не выбор региона хранения данных. Не подставляйте другие хосты, не разбирайте, не проксируйте и не записывайте ссылку в логи. Список установщиков доступен через GET /agent-download-api/v1/releases, а загрузка файла — через GET /agent-download-api/v1/installers/{filename}. После возврата проверьте state. result=ready подтверждает первый авторизованный heartbeat агента, но не наличие принтера. Обновите данные управляемого аккаунта, агентов и принтеров; включайте печать только при status=active, online_agent_count > 0 и online_printer_count > 0.
Собирайте данные для поддержки
Храните идентификатор клиента, relationship_id, installation_id, Enrollment ID, Agent ID, версию агента, время последнего подключения и связанные значения X-Request-Id. Эти данные помогут отличить проблему аккаунта от ошибки Enrollment, подключения агента, обнаружения принтера или Print API — без запроса секретных данных.