Создание и управление аккаунтами клиентов
Создавайте отдельный аккаунт CloudPrint для каждого клиента и сохраняйте связь между идентификатором клиента в вашей системе, Partner Account Relationship и App Installation, которые вернул CloudPrint.
Авторизуйте Partner API
Для каждого вызова Partner API создавайте новый одноразовый RS256 assertion. Поля iss и sub указывают Developer Application, kid выбирает активный открытый ключ, а aud должен совпадать с Partner Management audience. Передавайте assertion как Bearer-токен в /partner-api/v1/*; Installation Access Token предназначен для печати, а не для управления аккаунтами.
Безопасно повторяйте создание аккаунта
До вызова POST /partner-api/v1/accounts сохраните данные незавершённой операции: Idempotency-Key, state, имя, permissions и callback. После тайм-аута повторите то же тело запроса и ключ, изменив только assertion приложения; не создавайте нового клиента, state или ключ.
Сохраните стабильные связи
Храните external_customer_id, relationship_id, installation_id, статус и время изменений в одной записи интеграции. relationship_id используйте для управления клиентом через Partner API, а installation_id — для выпуска токенов Print API. cloudprint_account_id нужен только для необязательной сверки с account_id из ответа токена.
Получайте одного клиента без перебора
Используйте GET /partner-api/v1/accounts/{relationshipId}, если relationship уже известен. Для точной сверки по tenant вызовите GET /partner-api/v1/accounts?external_customer_id={tenantId}. Общий GET /partner-api/v1/accounts использует limit, непрозрачный cursor и next_cursor; точный поиск нельзя совмещать с cursor. Health не учитывает отозванные Agents и их принтеры. Agent считается online только при статусе online и heartbeat за последнюю минуту. Принтер считается online только при собственном статусе online и доступном Agent, к которому он относится. onboarding_status=ready устанавливается после первого аутентифицированного heartbeat, даже если Agent не передал ни одного принтера. Включайте печать только при status=active, online_agent_count > 0 и online_printer_count > 0.
Приостанавливайте и закрывайте явно
Используйте POST /partner-api/v1/accounts/{relationshipId}/{action} со значениями suspend, resume или close. Suspension отзывает Installation tokens, после resume нужен новый token, а close необратим. Для приостановленного аккаунта затронутые операции Print API отвечают 403 remote_printing.account.service_suspended.
Восстанавливайтесь после потери ответа
Повторите POST /partner-api/v1/accounts с исходным body, исходным Idempotency-Key и новым application assertion. Пока хранится зашифрованная idempotency-запись, replay вернёт существующий relationship и исходный hosted onboarding URL. Позже relationship можно найти по external_customer_id; новый Enrollment создавайте только после истечения исходной ссылки.
Контролируйте usage и оплату
Получайте UTC-месяц через GET /partner-api/v1/usage?period=YYYY-MM. Ответ показывает managed accounts, active Agents и print jobs для эксплуатации и акта, но не меняет фиксированную сумму счёта. При приостановке Partner Program из-за неоплаты management и затронутые операции печати отвечают 403 до восстановления услуги.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.