Создание и отслеживание заданий печати
При создании задания критичны защита от дублей и совместимость принтера. Все параметры находятся на верхнем уровне 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 возвращают исходное задание; изменённый input даёт 409 ...idempotency_key_conflict. Retry сохраняет ключ, осознанная перепечатка получает новый ключ и audit record.
Получите результат
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \
-H "Authorization: Bearer $ACCESS_TOKEN"Конечные статусы: printed, failed. Промежуточные: pending, reserved, printing. Неизвестные считайте промежуточными. В текущем Public API нет result webhook: опрашивайте сохранённый URL с ограниченным настраиваемым интервалом и jitter, замедляйтесь при долгом ожидании и соблюдайте Retry-After. При failed храните failure_reason; HTTP 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, upload или JSON-запрос | исправить запрос, не повторять без изменений |
401 | неверные credentials либо истёкший/неверный token | один раз обновить API token и один раз повторить |
403 | действующий token без нужного scope | изменить grants client app; refresh не поможет |
404 | ресурс отсутствует или принадлежит другому аккаунту | проверить аккаунт и сохранённый ID |
409 | конфликт идемпотентности или неподдерживаемый маршрут | проверить error_code и details.reason; не создавать новый ключ |
413 | документ слишком большой | уменьшить или выбрать другой способ передачи |
415 | тип документа не поддерживается | отправить готовый PDF или поддерживаемый RAW |
422 | неверные ID, metadata или параметры печати | исправить validation перед retry |
429 | превышен rate limit | ждать согласно Retry-After |
500 | неожиданная ошибка CloudPrint | ограниченный backoff с исходным ключом идемпотентности |
HTTP задаёт класс, error/error_code — ветку логики, а message предназначен для диагностики. Каждый ответ содержит X-Request-Id; записывайте его рядом с бизнес-ID.
Чек-лист перед запуском
- Используйте исходящее подключение агента и не открывайте порты принтера в интернет.
- Сохраняйте стабильный идентификатор принтера, а не только отображаемое имя.
- Проверяйте формат документа, размер страницы и ориентацию до создания задания.
- Явно задайте обработку конечных статусов, повторов и защиту от двойной печати.