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