При создании задания критичны защита от дублей и совместимость принтера. Все параметры находятся на верхнем уровне JSON. Возвращённую запись нужно отслеживать до конечного статуса.
## Создайте задание ```bash curl -sS https://public-api.cloudprint.me/api/v1/print-jobs \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: order-18452-invoice-v1' \ -d '{ "document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "printer_id": "11111111-1111-4111-8111-111111111111", "copies": 1, "intent": "invoice", "color_mode": "default", "duplex_mode": "default", "scale_mode": "none", "orientation": "default" }' ``` Успешный запрос возвращает HTTP 201: ```json { "print_job_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "document_mime_type": "application/pdf", "document_format": "pdf", "document_raw_language": null, "printer_id": "11111111-1111-4111-8111-111111111111", "status": "pending", "copies": 1, "intent": "invoice", "color_mode": "default", "duplex_mode": "default", "media_width_mm": null, "media_height_mm": null, "dpi": null, "scale_mode": "none", "orientation": "default", "offset_x_mm": 0, "offset_y_mm": 0, "margin_top_mm": 0, "margin_right_mm": 0, "margin_bottom_mm": 0, "margin_left_mm": 0, "created_at": "2026-06-08T10:12:00+00:00", "reserved_at": null, "started_at": null, "completed_at": null, "failure_reason": null } ``` ## Поддерживаемые поля | Поле | Допустимые значения | | --- | --- | | `copies` | целое число, минимум 1 | | `intent` | `document`, `shipping_label`, `product_label`, `invoice`, `packing_slip`, `a4_document`, `receipt` | | `color_mode` | `default`, `monochrome`, `color` | | `duplex_mode` | `default`, `simplex`, `duplex_long_edge`, `duplex_short_edge` | | `scale_mode` | `none`, `fit` | | `orientation` | `default`, `portrait`, `landscape` | | `offset_x_mm`, `offset_y_mm` | число от -2000 до 2000 | | `margin_*_mm` | число от 0 до 2000 | | `media_width_mm`, `media_height_mm` | необязательное число от 1 до 2000 | | `dpi` | необязательное целое число от 72 до 2400 | Каждый нестандартный параметр должен поддерживаться принтером. Неверное значение даёт `422`; невозможный маршрут — `409 remote_printing.print_job.unsupported` с `details.reason`. ## Идемпотентность и перепечатка Передавайте `Idempotency-Key` всегда. Тот же ключ и эквивалентный JSON возвращают исходное задание; изменённые входные данные дают `409 ...idempotency_key_conflict`. При повторе запроса сохраняйте ключ, а осознанной перепечатке назначайте новый ключ и отдельную запись в журнале аудита. ## Получите результат ```bash curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` Конечные статусы — `printed`, `failed` и `cancelled`, промежуточные — `pending`, `reserved` и `printing`. `printed` подтверждает принятие документа системной очередью, но не подтверждает физическую печать. Неизвестный статус считайте промежуточным. Сейчас Public API не отправляет вебхук с результатом, поэтому периодически запрашивайте сохранённый URL. Добавьте небольшое случайное отклонение к интервалу, увеличивайте его при долгом ожидании и учитывайте `Retry-After`. Для `failed` сохраняйте `failure_reason`; `cancelled` означает, что очередь не приняла документ. Ответ 2xx на создание задания также не означает физическую печать. ## Список и сверка ```bash curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ```json { "print_jobs": [ { "print_job_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb", "document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "printer_id": "11111111-1111-4111-8111-111111111111", "status": "printed", "copies": 1, "intent": "invoice", "completed_at": "2026-06-08T10:12:08+00:00", "failure_reason": null } ], "next_cursor": null } ``` Используйте список для сверки истории, а не вместо сохранения ID. Передавайте непрозрачный `next_cursor` в `cursor` до `null`; обычный статус читайте по сохранённому `print_job_id`. ## Стратегия ошибок ```json { "error": "remote_printing.print_job.unsupported", "error_code": "remote_printing.print_job.unsupported", "message": "The selected printer cannot route this document.", "details": { "reason": "missing_pdf_renderer" } } ``` | HTTP | Значение | Действие клиента | | --- | --- | --- | | `400` | ошибка в OAuth-запросе, загрузке файла или JSON | исправить запрос и не повторять его без изменений | | `401` | неверные учётные данные либо истёкший или неверный токен | один раз обновить токен API и один раз повторить запрос | | `403` | действующий токен без нужного разрешения | изменить разрешения API-приложения; обновление токена не поможет | | `404` | ресурс отсутствует или принадлежит другому аккаунту | проверить аккаунт и сохранённый ID | | `409` | конфликт идемпотентности или неподдерживаемый маршрут | проверить `error_code` и `details.reason`; не создавать новый ключ | | `413` | документ слишком большой | уменьшить или выбрать другой способ передачи | | `415` | тип документа не поддерживается | отправить готовый PDF или поддерживаемый RAW | | `422` | ошибка валидации или документ не прошёл проверку безопасности | изменить документ или запрос перед повтором | | `429` | превышен лимит запросов | подождать согласно `Retry-After` | | `500` | внутренняя ошибка CloudPrint | повторить запрос с исходным ключом идемпотентности, постепенно увеличивая интервал между попытками | | `503` | проверка безопасности документов временно недоступна | повторить запрос с исходным ключом идемпотентности, постепенно увеличивая интервал между попытками | HTTP задаёт класс, `error/error_code` — ветку логики, а `message` предназначен для диагностики. Каждый ответ содержит `X-Request-Id`; записывайте его рядом с бизнес-ID. ## Следующие шаги