Здесь описан 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. ## Подробные руководства О токенах и разрешениях читайте в [Авторизации](../authentication/), о выборе принтера — в [Агентах и принтерах](../agents-and-printers/), о входных файлах — в [Документах](../documents/), о повторах и статусах — в [Заданиях печати](../print-jobs/). Точные операции и схемы приведены в [справочнике API v1](../v1/). ## Следующие шаги