Подключение агента клиента
Agent Enrollment подключает один или несколько локальных CloudPrint Agents к нужному клиентскому аккаунту без регистрации и входа клиента в CloudPrint.
Создавайте каждый Enrollment идемпотентно
При создании аккаунта CloudPrint возвращает одну hosted-ссылку agent_onboarding_url с одноразовым токеном. Второй компьютер можно подключить через POST /partner-api/v1/accounts/{relationshipId}/agent-enrollments с обязательным Idempotency-Key. Точный повтор возвращает исходные Enrollment ID, срок действия и URL. До первого запроса сохраните ключ, state, имя, callback и необязательный replaces_enrollment_id; при повторе меняется только assertion приложения. Для замены известного неиспользованного Enrollment передайте replaces_enrollment_id.
Отслеживайте конкретный Enrollment
Сохраните возвращённый enrollment_id и проверяйте GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Продолжайте при pending; при ready сохраните возвращённый agent_id. Остановитесь при expired, cancelled или failed. Так ранее подключённый Agent не будет ошибочно принят за компьютер, использовавший новую ссылку.
Получайте и отзывайте Enrollments
GET /partner-api/v1/accounts/{relationshipId}/agent-enrollments возвращает pending, claimed, expired и revoked records без секретных кодов. Отзовите неиспользованный код через DELETE /partner-api/v1/accounts/{relationshipId}/agent-enrollments/{enrollmentId}. Повторный revoke безопасен.
Получайте и отзывайте Agents
Показывайте подключённые компьютеры через GET /partner-api/v1/accounts/{relationshipId}/agents. Потерянный, сломанный или заменённый компьютер отзывается через DELETE /partner-api/v1/accounts/{relationshipId}/agents/{agentId}, после чего для нового компьютера создаётся Enrollment. Принтеры отозванного Agent переходят offline.
Восстанавливайте потерянный Enrollment response
Повторите точный запрос с новым одноразовым assertion и тем же Enrollment Idempotency-Key. CloudPrint вернёт исходный secret в пределах idempotency window. Другой body или route с тем же ключом дают 409 partner.idempotency.conflict; не создавайте новый ключ после ответа с неизвестным результатом.
Используйте hosted onboarding без настройки Agent API
Открывайте полный agent_onboarding_url без изменений, включая fragment #token; не разбирайте, не пересобирайте, не проксируйте и не логируйте его. CloudPrint сам управляет Agent API и резервным маршрутом. Публичный каталог установщиков доступен через GET /agent-download-api/v1/releases, а загрузка файла — через GET /agent-download-api/v1/installers/{filename}. После callback проверьте state. result=ready подтверждает первый аутентифицированный heartbeat Agent, но не наличие принтера. Перечитайте managed Account, Agents и список принтеров; включайте печать только при status=active, online_agent_count > 0 и online_printer_count > 0.
Собирайте данные для поддержки
Храните идентификатор клиента, relationship_id, installation_id, Enrollment ID, Agent ID, версию, last-seen и относящиеся X-Request-Id. Поддержка должна отличать lifecycle аккаунта, Enrollment, Agent connectivity, printer discovery и Print API без запроса credentials.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.