Создание и управление аккаунтами клиентов
Создавайте отдельный аккаунт CloudPrint для каждого клиента и сохраняйте связь между идентификатором клиента в вашей системе, Partner Account Relationship и App Installation, которые вернул CloudPrint.
Авторизуйте Partner API
Для каждого вызова Partner API создавайте новое одноразовое JWT-подтверждение RS256. Поля iss и sub указывают Developer Application, kid выбирает активный открытый ключ, а aud должен совпадать с адресом Partner API. Передавайте подтверждение как Bearer-токен в /partner-api/v1/*. Installation Access Token предназначен для печати, а не для управления аккаунтами.
Безопасно повторяйте создание аккаунта
До вызова POST /partner-api/v1/accounts сохраните данные незавершённой операции: Idempotency-Key, state, имя, разрешения и адрес возврата. После тайм-аута повторите то же тело запроса с тем же ключом, заменив только JWT-подтверждение приложения. Не создавайте нового клиента, новое значение state или новый ключ.
Сохраните стабильные связи
Храните external_customer_id, relationship_id, installation_id, статус и время изменений в одной записи интеграции. CloudPrint ищет клиента и защищает от дублей по external_customer_id в пределах авторизованного Developer Application, поэтому отдельные приложения для staging и production могут использовать одинаковый идентификатор клиента. relationship_id используйте для управления клиентом через Partner API, а installation_id — для выпуска токенов Print API. cloudprint_account_id нужен только для необязательной сверки с account_id из ответа токена.
Получайте данные нужного клиента напрямую
Если relationship_id известен, используйте GET /partner-api/v1/accounts/{relationshipId}. Для поиска по идентификатору клиента вызовите GET /partner-api/v1/accounts?external_customer_id={tenantId}. Общий список GET /partner-api/v1/accounts использует limit, непрозрачный cursor и next_cursor; поиск по external_customer_id нельзя совмещать с курсором. В показатели доступности не входят отозванные агенты и их принтеры. Агент считается доступным только при статусе online и сигнале heartbeat за последнюю минуту. Для принтера также необходим собственный статус online. Значение onboarding_status=ready появляется после первого подтверждённого heartbeat, даже если агент ещё не передал ни одного принтера. Включайте печать только при status=active, online_agent_count > 0 и online_printer_count > 0.
Приостанавливайте и закрывайте аккаунты явно
Используйте POST /partner-api/v1/accounts/{relationshipId}/{action} со значениями suspend, resume или close. Приостановка отзывает токены установки, после возобновления нужно получить новый токен, а закрытие необратимо. Для приостановленного аккаунта затронутые операции Print API возвращают 403 remote_printing.account.service_suspended.
Восстановите потерянный ответ
Повторите POST /partner-api/v1/accounts с исходным телом, прежним Idempotency-Key и новым JWT-подтверждением приложения. Пока хранится зашифрованная запись идемпотентности, повтор вернёт существующую связь и исходную ссылку для подключения агента. Позже связь можно найти по external_customer_id. Новый Enrollment создавайте только после истечения исходной ссылки.
Контролируйте использование и оплату
Запрашивайте данные за календарный месяц UTC через GET /partner-api/v1/usage?period=YYYY-MM. Ответ содержит количество управляемых аккаунтов, активных агентов и заданий печати для контроля работы и подготовки акта, но не меняет согласованную сумму счёта. Если доступ Developer Account к production приостановлен, операции управления и затронутые операции печати возвращают 403 до восстановления доступа.