Обзор CloudPrint Public API
Здесь описан Print API для печати в пределах одного аккаунта. Полный справочник OpenAPI также содержит методы Developer Platform, Partner Management и публичной загрузки агента.
Куда отправлять запросы
Основной адрес — https://public-api.cloudprint.me. Если он недоступен из сети, используйте официальное зеркало https://public-api.cloudprint.by. Зеркало поддерживает все публичные пути на этом хосте: OAuth, Print API, Developer API, Partner API и загрузку CloudPrint Agent. Настройте базовый адрес один раз для окружения или клиента; при замене имени хоста сохраняйте пути, параметры, тела запросов и токены. Не переключайте домен как новый повтор после тайм-аута: для операций с Idempotency-Key повторяйте исходный запрос с тем же ключом. Оба адреса обслуживают один API и не выбирают регион хранения данных. Установленный агент использует внутренний протокол CloudPrint и не предназначен для прямого доступа внешних систем.
Не изменяйте audience подписанных запросов
Для RS256-подтверждений Developer Application передавайте в aud точное каноническое значение, указанное в документации метода, даже если сам HTTP-запрос отправляется через public-api.cloudprint.by. Не формируйте aud автоматически из выбранного сетевого адреса: проверка подписи и сетевой маршрут — разные части интеграции.
Методы Print API
| Метод | Путь | Разрешение | Назначение |
|---|---|---|---|
POST | /oauth/token | — | Получить токен доступа OAuth2 |
GET | /api/v1/me | авторизация | Проверить аккаунт, API-приложение и разрешения |
GET | /api/v1/agents | agents:read | Проверить статус и версию агента |
GET | /api/v1/printers | printers:read | Получить принтеры и их возможности |
POST | /api/v1/documents | documents:write | Загрузить PDF или RAW |
POST | /api/v1/print-jobs | print_jobs:write | Создать задание для загруженного документа |
POST | /api/v1/print-jobs/from-url | documents:write, print_jobs:write | Скачать публичный HTTPS-документ и создать задание |
POST | /api/v1/print-jobs/from-base64 | documents:write, print_jobs:write | Декодировать встроенные данные и создать задание |
GET | /api/v1/print-jobs | print_jobs:read | Получить задания с курсорной пагинацией |
GET | /api/v1/print-jobs/{printJobId} | print_jobs:read | Получить задание и результат |
В каком порядке подключать API
Сначала реализуйте получение токена и проверку через /me, затем выбор принтера, загрузку документа, безопасное создание задания и опрос статуса. Методы для URL и Base64 добавляйте после того, как заработает основной двухшаговый сценарий. /agents пригодится для диагностики, а список /print-jobs — для сверки истории.
Пагинация
Списки агентов, принтеров и заданий используют курсорную пагинацию. Передайте limit от 1 до 100, затем отправляйте возвращённый непрозрачный next_cursor в параметре cursor. Остановитесь при next_cursor: null; не разбирайте и не создавайте курсор самостоятельно.
Совместимость
Стабильный путь — /api/v1. Игнорируйте неизвестные поля ответа, а неизвестные статусы задания считайте промежуточными. Используйте допустимые значения и ограничения из OpenAPI. Несовместимые изменения требуют нового основного пути API.
Подробные руководства
О токенах и разрешениях читайте в Авторизации, о выборе принтера — в Агентах и принтерах, о входных файлах — в Документах, о повторах и статусах — в Заданиях печати. Точные операции и схемы приведены в справочнике API v1.