Создание и отслеживание заданий печати
При создании задания критичны защита от дублей и совместимость принтера. Все параметры находятся на верхнем уровне JSON. Возвращённую запись нужно отслеживать до конечного статуса.
Создайте задание
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:
{
"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. При повторе запроса сохраняйте ключ, а осознанной перепечатке назначайте новый ключ и отдельную запись в журнале аудита.
Получите результат
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 на создание задания также не означает физическую печать.
Список и сверка
curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"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.
Стратегия ошибок
{
"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.