Создать задание из URL
Получите документ по публичному HTTPS URL и одним запросом создайте обычный документ и задание CloudPrint.
Назначение метода
Получите документ по публичному HTTPS URL и одним запросом создайте обычный документ и задание CloudPrint.
Авторизация
Передавайте короткоживущий токен в Authorization: Bearer <access_token>.
Обязательные разрешения: print_jobs:write
Запрос
Основной адрес API: https://public-api.cloudprint.me/api/v1/print-jobs/from-url
Параметры
| Имя | Расположение | Тип | Обязательно | Описание | Ограничения |
|---|---|---|---|---|---|
Idempotency-Key | header | string | нет | Поле контракта API; учитывайте указанные тип и ограничения. | maxLength: 128 |
Тело запроса
Тип содержимого: application/json
| Имя | Тип | Обязательно | Описание | Ограничения |
|---|---|---|---|---|
document_url | string (uri) | да | Публичный HTTPS URL, по которому CloudPrint скачает документ. | example: "https://files.example.com/labels/order-100045.pdf" |
document_filename | string | null | нет | Имя файла для определения формата и диагностики оператором. | example: "order-100045.pdf" |
document_format | string | null | нет | Явный формат печати, например pdf или raw. | enum: pdf, raw; example: "pdf" |
document_raw_language | string | null | нет | Язык команд RAW-документа, например ZPL или EPL. | enum: tspl, zpl, cpcl, escpos; example: null |
printer_id | string (uuid) | да | Стабильный UUID целевого принтера в CloudPrint. | — |
copies | integer | нет | Количество копий, которое CloudPrint передаст принтеру. | min: 1; max: 99; example: 1 |
intent | string | нет | Бизнес-назначение задания для диагностики и подходящих настроек по умолчанию. | enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label" |
color_mode | string | нет | Режим цвета; default использует настройку принтера. | enum: default, monochrome, color; example: "default" |
duplex_mode | string | нет | Запрошенный односторонний или двусторонний режим печати. | enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default" |
media_width_mm | number | null | нет | Запрошенная ширина носителя или этикетки в миллиметрах. | min: 1; max: 2000; example: 58 |
media_height_mm | number | null | нет | Запрошенная высота носителя или этикетки в миллиметрах. | min: 1; max: 2000; example: 40 |
dpi | integer | null | нет | Целевое разрешение печати в точках на дюйм; используйте значение принтера. | min: 72; max: 2400; example: 203 |
scale_mode | string | нет | Определяет, сохранять размер документа или вписать его в носитель. | enum: none, fit; example: "none" |
orientation | string | нет | Ориентация страницы; default использует настройку принтера. | enum: default, portrait, landscape; example: "default" |
offset_x_mm | number | нет | Горизонтальное смещение печати в миллиметрах. | min: -2000; max: 2000; example: 0 |
offset_y_mm | number | нет | Вертикальное смещение печати в миллиметрах. | min: -2000; max: 2000; example: 0 |
margin_top_mm | number | нет | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_right_mm | number | нет | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_bottom_mm | number | нет | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_left_mm | number | нет | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
Примеры запросов
cURL
bash
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/from-url \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-100045-label' \
-d '{
"document_url": "https://files.example.com/labels/order-100045.pdf",
"document_filename": "order-100045.pdf",
"printer_id": "11111111-1111-4111-8111-111111111111",
"copies": 1,
"intent": "shipping_label",
"media_width_mm": 58,
"media_height_mm": 40,
"dpi": 203
}'Ответ
HTTP-статус: 201 — Ресурс создан.
Поля ответа
| Имя | Тип | Обязательно | Описание | Ограничения |
|---|---|---|---|---|
print_job_id | string (uuid) | да | Стабильный UUID задания печати; сохраните его для проверки статуса и поддержки. | — |
document_id | string (uuid) | да | Стабильный UUID, возвращаемый после успешной загрузки документа. | — |
document_mime_type | string | да | MIME-тип переданного документа. | example: "application/pdf" |
document_format | string | да | Явный формат печати, например pdf или raw. | enum: pdf, raw; example: "pdf" |
document_raw_language | string | null | да | Язык команд RAW-документа, например ZPL или EPL. | enum: tspl, zpl, cpcl, escpos; example: null |
printer_id | string (uuid) | да | Стабильный UUID целевого принтера в CloudPrint. | — |
status | string | да | Текущее состояние ресурса или процесса; учитывайте допустимые значения конкретного метода. | enum: pending, reserved, printing, printed, failed, cancelled; example: "pending" |
copies | integer | да | Количество копий, которое CloudPrint передаст принтеру. | min: 1; max: 99; example: 1 |
intent | string | да | Бизнес-назначение задания для диагностики и подходящих настроек по умолчанию. | enum: document, shipping_label, product_label, invoice, packing_slip, a4_document, receipt; example: "shipping_label" |
color_mode | string | да | Режим цвета; default использует настройку принтера. | enum: default, monochrome, color; example: "default" |
duplex_mode | string | да | Запрошенный односторонний или двусторонний режим печати. | enum: default, simplex, duplex_long_edge, duplex_short_edge; example: "default" |
media_width_mm | number | null | да | Запрошенная ширина носителя или этикетки в миллиметрах. | min: 1; max: 2000; example: 58 |
media_height_mm | number | null | да | Запрошенная высота носителя или этикетки в миллиметрах. | min: 1; max: 2000; example: 40 |
dpi | integer | null | да | Целевое разрешение печати в точках на дюйм; используйте значение принтера. | min: 72; max: 2400; example: 203 |
scale_mode | string | да | Определяет, сохранять размер документа или вписать его в носитель. | enum: none, fit; example: "none" |
orientation | string | да | Ориентация страницы; default использует настройку принтера. | enum: default, portrait, landscape; example: "default" |
offset_x_mm | number | да | Горизонтальное смещение печати в миллиметрах. | min: -2000; max: 2000; example: 0 |
offset_y_mm | number | да | Вертикальное смещение печати в миллиметрах. | min: -2000; max: 2000; example: 0 |
margin_top_mm | number | да | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_right_mm | number | да | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_bottom_mm | number | да | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
margin_left_mm | number | да | Дополнительное поле печати в миллиметрах. | min: 0; max: 2000; example: 0 |
created_at | string (date-time) | да | Временная метка CloudPrint в формате ISO 8601. | — |
reserved_at | string | null (date-time) | да | Временная метка CloudPrint в формате ISO 8601. | — |
started_at | string | null (date-time) | да | Временная метка CloudPrint в формате ISO 8601. | — |
completed_at | string | null (date-time) | да | Временная метка CloudPrint в формате ISO 8601. | — |
failure_reason | string | null | да | Машиночитаемая или диагностическая причина неудачной печати. | — |
Пример ответа
json
{
"print_job_id": "11111111-1111-4111-8111-111111111111",
"document_id": "11111111-1111-4111-8111-111111111111",
"document_mime_type": "application/pdf",
"document_format": "pdf",
"document_raw_language": null,
"printer_id": "11111111-1111-4111-8111-111111111111",
"status": "pending",
"copies": 1,
"intent": "shipping_label",
"color_mode": "default",
"duplex_mode": "default",
"media_width_mm": 58,
"media_height_mm": 40,
"dpi": 203,
"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-08-06T12:00:00Z",
"reserved_at": null,
"started_at": null,
"completed_at": null,
"failure_reason": null
}Ошибки
| HTTP-статус | Описание |
|---|---|
400 | Проверьте формат и параметры запроса. |
401 | Авторизация отсутствует или недействительна. |
403 | Для операции недостаточно разрешений. |
409 | Запрос конфликтует с текущим состоянием ресурса. |
413 | Тело запроса превышает допустимый размер. |
415 | Формат содержимого не поддерживается. |
422 | Поля запроса не прошли проверку. |
429 | Превышен лимит запросов; учитывайте Retry-After. |
500 | Внутренняя ошибка CloudPrint. |
Рекомендации по интеграции
- Источник должен быть доступен по публичному HTTPS-адресу; localhost, частные сети, встроенные данные доступа и небезопасные перенаправления отклоняются.
- Используйте короткоживущую ссылку с минимальными правами и достаточным сроком действия.
- Соблюдайте те же правила идемпотентности и отслеживания статуса.
Связанная документация
Создать задание печатиОтправьте загруженный документ CloudPrint на выбранный принтер с идемпотентностью и явными параметрами.Создать задание из Base64Декодируйте небольшой Base64-документ и одним запросом создайте документ и задание CloudPrint.Получить статус задания печатиПолучайте состояние задания CloudPrint, пока оно не перейдёт в конечный статус printed или failed.