Создать задание печати

Отправьте загруженный документ CloudPrint на выбранный принтер с идемпотентностью и явными параметрами.

POST/api/v1/print-jobsВерсия API: v1operationId: createPrintJobОткрыть в Markdown

Назначение метода

Отправьте загруженный документ CloudPrint на выбранный принтер с идемпотентностью и явными параметрами.

Авторизация

Передавайте короткоживущий токен в Authorization: Bearer <access_token>.

Обязательные разрешения: print_jobs:write

Запрос

Основной адрес API: https://public-api.cloudprint.me/api/v1/print-jobs

Параметры

Имя	Расположение	Тип	Обязательно	Описание	Ограничения
`Idempotency-Key`	header	`string`	нет	Поле контракта API; учитывайте указанные тип и ограничения.	maxLength: 128

Тело запроса

Тип содержимого: application/json

Имя	Тип	Обязательно	Описание	Ограничения
`document_id`	`string (uuid)`	да	Стабильный UUID, возвращаемый после успешной загрузки документа.	—
`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 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-100045-label' \
  -d '{
    "document_id": "44444444-4444-4444-8444-444444444444",
    "printer_id": "11111111-1111-4111-8111-111111111111",
    "copies": 1,
    "intent": "shipping_label",
    "media_width_mm": 58,
    "media_height_mm": 40,
    "dpi": 203
  }'

PHP

php

<?php

$payload = json_encode([
    'document_id' => '44444444-4444-4444-8444-444444444444',
    'printer_id' => '11111111-1111-4111-8111-111111111111',
    'copies' => 1,
    'intent' => 'shipping_label',
    'media_width_mm' => 58,
    'media_height_mm' => 40,
    'dpi' => 203,
], JSON_THROW_ON_ERROR);

$response = file_get_contents('https://public-api.cloudprint.me/api/v1/print-jobs', false, stream_context_create([
    'http' => [
        'method' => 'POST',
        'header' => [
            'Authorization: Bearer ' . getenv('CLOUDPRINT_ACCESS_TOKEN'),
            'Content-Type: application/json',
            'Idempotency-Key: order-100045-label',
        ],
        'content' => $payload,
    ],
]));

$printJob = json_decode((string) $response, true, flags: JSON_THROW_ON_ERROR);

Ответ

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-статус	Описание
`401`	Авторизация отсутствует или недействительна.
`403`	Для операции недостаточно разрешений.
`409`	Запрос конфликтует с текущим состоянием ресурса.
`422`	Поля запроса не прошли проверку.
`429`	Превышен лимит запросов; учитывайте Retry-After.
`500`	Внутренняя ошибка CloudPrint.

Связанная документация

Загрузить документ для печатиЗагрузите готовый PDF или явные RAW-команды языка принтера перед созданием задания CloudPrint.Получить статус задания печатиПолучайте состояние задания CloudPrint, пока оно не перейдёт в конечный статус printed или failed.Идемпотентное создание заданийПредотвращайте двойную печать при повторе запросов после превышения времени ожидания или сетевого сбоя.

Создать задание печати ​

Назначение метода ​

Авторизация ​

Запрос ​

Параметры ​

Тело запроса ​

Примеры запросов ​

cURL ​

PHP ​

Ответ ​

Поля ответа ​

Пример ответа ​

Ошибки ​

Рекомендации по интеграции ​

Связанная документация ​