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 — без запроса секретных данных. ## Чек-лист перед запуском - Используйте исходящее подключение агента и не открывайте порты принтера в интернет. - Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя. - Проверяйте формат документа, размер страницы и ориентацию до создания задания. - Явно задайте обработку конечных статусов, повторов и защиту от двойной печати. ## Следующие шаги