Установки и токены доступа
App Installation — постоянная связь одного Developer Application с одним клиентским аккаунтом CloudPrint. Сохраните `installation_id` и выпускайте короткоживущий токен, когда вашему серверу нужен доступ к Print API этого аккаунта.
Выберите модель установки
Этот сценарий с подтверждением клиента нужен, когда у него уже есть аккаунт CloudPrint. Для аккаунтов, которые создаёт ваш продукт, используйте Partner Platform: App Installation создаётся через Partner API без перенаправления клиента на экран согласия.
Создайте ссылку установки
Добавьте в URL установки client_id, один из точно зарегистрированных redirect_uri, непредсказуемый state, связанный с текущим пользователем и клиентом, и только необходимые разрешения. Перенаправьте владельца аккаунта по этому URL. Переданный вашим интерфейсом Account ID сам по себе не подтверждает право доступа.
Получите согласие владельца
CloudPrint покажет название приложения, Developer Account, публичные ссылки и запрошенные разрешения. Владелец выберет аккаунт CloudPrint и подтвердит доступ. Сразу запрашивайте только обязательные разрешения; дополнительные возможности должны требовать отдельного понятного согласия.
Проверьте возврат пользователя
В callback приходят installation_id, setup_action и исходный state. Сравните state со значением на сервере, отклоните просроченную или уже использованную попытку и свяжите установку с клиентом, который начал процесс. Не используйте CloudPrint Account ID вместо идентификатора клиента в своей системе.
Выпустите Installation Access Token
Создайте новый RS256 assertion приложения с aud, равным https://public-api.cloudprint.me/developer-api/v1/app-installations/{installationId}/access-tokens. Передайте его как Authorization: Bearer <application_assertion> в POST /developer-api/v1/app-installations/{installationId}/access-tokens. Ответ содержит access_token, expires_in, account_id, installation_id и одобренные разрешения.
Используйте и кешируйте токен
Передавайте Installation Access Token как Bearer-токен в /api/v1/*. Кешируйте его отдельно для каждой установки почти до истечения срока, а не выпускайте заново для каждого задания. Refresh token не выдаётся: следующий короткоживущий токен выпускается для той же установки.
Проверяйте разрешения и статус
Запрошенные разрешения должны быть непустым подмножеством разрешений установки. Установка со статусом suspended не может выпускать и использовать токены до возобновления, а revoked восстановить нельзя. После 401 один раз удалите кешированный токен и получите новый; после 403 проверьте разрешения и статус установки.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.