Документация CloudPrint/Интеграция API

OAuth-интеграция для сторонних приложений

Приложение разработчика нужно продукту, который подключает отдельные аккаунты разных клиентов CloudPrint. По запросу CloudPrint создаёт Developer Organization и OAuth-приложение, после чего каждый клиент сам подтверждает доступ через Authorization Code с PKCE.

Выберите правильную модель

Используйте API Credentials, если один клиент подключает собственный backend к своему аккаунту CloudPrint. Запрашивайте Developer Organization, если вы выпускаете SaaS, коннектор или интеграцию для сторонних клиентов. Приложение разработчика не работает через client_credentials: для каждого аккаунта требуется отдельное согласие пользователя.

Запросите аккаунт разработчика

Отправьте заявку через раздел контактов CloudPrint. Укажите организацию и продукт, технический контакт, сценарий интеграции, сайт, URL политики конфиденциальности, точный HTTPS callback и минимальные scope. CloudPrint создаёт OAuth-приложение и безопасно передаёт client_id и одноразовый client_secret. Самостоятельное создание таких приложений пока недоступно.

Зарегистрируйте URL приложения

Укажите публичный HTTPS-сайт, URL политики конфиденциальности и callback URI. Redirect URI сравнивается точно: схема, хост, порт, путь и завершающий слеш должны совпадать при авторизации, обмене кода и в настройках приложения. Регистрируйте только реальные callback-пути вашего продукта и отклоняйте перенаправления на другие адреса.

Начните Authorization Code с PKCE

Создайте криптографически случайные одноразовые state и PKCE code_verifier, сохраните их в короткоживущей серверной транзакции. Рассчитайте S256 challenge и перенаправьте браузер пользователя:

https://my.cloudprint.me/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fintegrations%2Fcloudprint%2Fcallback&
  scope=printers%3Aread%20documents%3Awrite%20print_jobs%3Awrite&
  state=RANDOM_SINGLE_USE_VALUE&
  code_challenge=BASE64URL_SHA256_OF_VERIFIER&
  code_challenge_method=S256

Не передавайте client_secret через браузер. В CloudPrint пользователь увидит приложение, организацию и запрошенные разрешения до подтверждения.

Проверьте callback и обменяйте код

В callback отклоняйте отсутствующий, просроченный или несовпавший state. Backend обменивает короткоживущий code вместе с исходным verifier:

curl -sS https://public-api.cloudprint.me/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'redirect_uri=https://app.example.com/integrations/cloudprint/callback' \
  --data-urlencode 'code=CODE_FROM_CALLBACK' \
  --data-urlencode 'code_verifier=ORIGINAL_PKCE_VERIFIER'

Callback должен побайтно совпадать с зарегистрированным URI. Храните токены в привязке к организации клиента, которая начала подключение, а не как один глобальный токен продукта.

Обновляйте и отзывайте безопасно

Access token живёт недолго; backend обновляет его до истечения:

curl -sS https://public-api.cloudprint.me/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'refresh_token=STORED_REFRESH_TOKEN'

Шифруйте client secret и refresh token при хранении, защищайтесь от параллельного refresh и не логируйте полные токены. Клиент может отозвать доступ в Integrations → Authorized Apps. После неуспешного refresh или API 401 считайте подключение разорванным и предложите авторизоваться заново.

Завершите подключение клиента

После первого обмена вызовите /api/v1/me и проверьте аккаунт и scope. Затем получите принтеры, дайте клиенту назначить стабильные printer_id филиалам или процессам и сохраните CloudPrint ID рядом с ID организации в вашей системе. После настройки используйте обычные API документов и заданий печати.

Чек-лист перед запуском

До подключения клиентов полностью проверьте callback и refresh, сократите scope до необходимых, опубликуйте реальную политику конфиденциальности, опишите отключение интеграции, обеспечьте идемпотентную печать и контакт поддержки. После отзыва доступа не переключайте печать на принтер другого клиента.

Чек-лист перед запуском

• Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
• Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
• Проверяйте формат документа, размер страницы и ориентацию до создания задания.
• Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.

Следующие шаги

Авторизация OAuth2 Client CredentialsСоздайте client app CloudPrint, получите короткоживущий токен и безопасно храните учётные данные с минимальными scope.Обзор CloudPrint Public APIКарта авторизации, принтеров, документов, заданий, статусов и ошибок CloudPrint для backend-интеграции.Справочник CloudPrint OpenAPIПолный контракт Public API CloudPrint: методы, схемы запросов и ответов, scope авторизации и машиночитаемый JSON.

OpenAPIОткрыть кабинетПолитика конфиденциальностиУсловияОплата и возвратDPA