Обзор CloudPrint Public API
Эта страница — карта Public API. Учебные руководства объясняют решения и эксплуатацию, а интерактивный OpenAPI остаётся каноническим источником каждого поля и ответа.
Адрес и граница API
Все внешние backend-запросы идут на https://public-api.cloudprint.me. Владелец аккаунта подключает агенты и создаёт client apps в https://my.cloudprint.me. Внутренний протокол агента не является клиентским API.
Полная карта ресурсов
| Метод | Путь | Scope | Назначение |
|---|---|---|---|
POST | /oauth/token | — | Получить OAuth2 access token |
GET | /api/v1/me | авторизация | Проверить аккаунт, client app и scope |
GET | /api/v1/agents | agents:read | Проверить статус и версию агента |
GET | /api/v1/printers | printers:read | Получить принтеры и capabilities |
POST | /api/v1/documents | documents:write | Загрузить PDF или RAW |
POST | /api/v1/print-jobs | print_jobs:write | Создать задание для загруженного документа |
POST | /api/v1/print-jobs/from-url | print_jobs:write | Скачать публичный HTTPS-документ и создать задание |
POST | /api/v1/print-jobs/from-base64 | print_jobs:write | Декодировать inline-данные и создать задание |
GET | /api/v1/print-jobs | print_jobs:read | Получить задания с cursor pagination |
GET | /api/v1/print-jobs/{printJobId} | print_jobs:read | Получить задание и результат |
Порядок реализации
Сначала реализуйте токен и /me, затем подключение принтера, загрузку документа, идемпотентное создание задания и опрос статуса. URL/Base64 добавляйте после рабочего двухшагового сценария. /agents используйте для диагностики, список /print-jobs — для сверки истории.
Пагинация
Списки агентов, принтеров и заданий используют cursor pagination. Передайте limit от 1 до 100, затем отправляйте возвращённый непрозрачный next_cursor в параметре cursor. Остановитесь при next_cursor: null; не разбирайте и не создавайте cursor самостоятельно.
Совместимость
Стабильный путь — /api/v1. Игнорируйте неизвестные поля ответа, а неизвестные статусы задания считайте промежуточными. Используйте точные enum и лимиты из OpenAPI. Ломающие изменения требуют нового major path.
Где искать ответ
Токены и scope — в Авторизации, маршрутизация — в Агентах и принтерах, входные файлы — в Документах, retry и статусы — в Заданиях, точные схемы — в OpenAPI.
Чек-лист перед запуском
- Храните API-ключи на backend и ограничивайте их аккаунтом владельца.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.