Utwórz zadanie druku

Wyślij przesłany dokument CloudPrint na wybraną drukarkę z idempotencją i jawnymi opcjami.

POST/api/v1/print-jobsWersja API: v1operationId: createPrintJobOtwórz w Markdown

Działanie metody

Wyślij przesłany dokument CloudPrint na wybraną drukarkę z idempotencją i jawnymi opcjami.

Uwierzytelnianie

Przekaż krótkotrwały token w Authorization: Bearer <access_token>.

Wymagane uprawnienia: print_jobs:write

Żądanie

Podstawowy adres API: https://public-api.cloudprint.me/api/v1/print-jobs

Parametry

Nazwa	Położenie	Typ	Wymagane	Opis	Ograniczenia
`Idempotency-Key`	header	`string`	nie	Pole kontraktu API; uwzględnij podany typ i ograniczenia.	maxLength: 128

Treść żądania

Typ zawartości: application/json

Nazwa	Typ	Wymagane	Opis	Ograniczenia
`document_id`	`string (uuid)`	tak	Stabilny UUID zwracany po pomyślnym przesłaniu dokumentu.	—
`printer_id`	`string (uuid)`	tak	Stabilny UUID drukarki docelowej w CloudPrint.	—
`copies`	`integer`	nie	Liczba kopii, które CloudPrint zleci drukarce.	min: 1; max: 99; example: `1`
`intent`	`string`	nie	Cel biznesowy zadania, używany w diagnostyce i doborze rozsądnych ustawień domyślnych.	enum: `document`, `shipping_label`, `product_label`, `invoice`, `packing_slip`, `a4_document`, `receipt`; example: `"shipping_label"`
`color_mode`	`string`	nie	Tryb koloru; `default` pozostawia wybór konfiguracji drukarki.	enum: `default`, `monochrome`, `color`; example: `"default"`
`duplex_mode`	`string`	nie	Żądany tryb druku jednostronnego lub dwustronnego.	enum: `default`, `simplex`, `duplex_long_edge`, `duplex_short_edge`; example: `"default"`
`media_width_mm`	`number \| null`	nie	Żądana szerokość nośnika lub etykiety w milimetrach.	min: 1; max: 2000; example: `58`
`media_height_mm`	`number \| null`	nie	Żądana wysokość nośnika lub etykiety w milimetrach.	min: 1; max: 2000; example: `40`
`dpi`	`integer \| null`	nie	Docelowa rozdzielczość druku w punktach na cal; użyj wartości obsługiwanej przez drukarkę.	min: 72; max: 2400; example: `203`
`scale_mode`	`string`	nie	Określa, czy zachować rozmiar dokumentu, czy dopasować go do nośnika.	enum: `none`, `fit`; example: `"none"`
`orientation`	`string`	nie	Orientacja strony; `default` używa ustawień drukarki.	enum: `default`, `portrait`, `landscape`; example: `"default"`
`offset_x_mm`	`number`	nie	Poziome przesunięcie druku w milimetrach.	min: -2000; max: 2000; example: `0`
`offset_y_mm`	`number`	nie	Pionowe przesunięcie druku w milimetrach.	min: -2000; max: 2000; example: `0`
`margin_top_mm`	`number`	nie	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_right_mm`	`number`	nie	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_bottom_mm`	`number`	nie	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_left_mm`	`number`	nie	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`

Przykładowe żądania

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);

Odpowiedź

Status HTTP: 201 — Zasób został utworzony.

Pola odpowiedzi

Nazwa	Typ	Wymagane	Opis	Ograniczenia
`print_job_id`	`string (uuid)`	tak	Stabilny UUID zadania druku; zapisz go do sprawdzania statusu i obsługi.	—
`document_id`	`string (uuid)`	tak	Stabilny UUID zwracany po pomyślnym przesłaniu dokumentu.	—
`document_mime_type`	`string`	tak	Typ MIME przekazanego dokumentu.	example: `"application/pdf"`
`document_format`	`string`	tak	Jawny format druku, na przykład `pdf` albo `raw`.	enum: `pdf`, `raw`; example: `"pdf"`
`document_raw_language`	`string \| null`	tak	Język poleceń danych RAW, na przykład ZPL lub EPL.	enum: `tspl`, `zpl`, `cpcl`, `escpos`; example: `null`
`printer_id`	`string (uuid)`	tak	Stabilny UUID drukarki docelowej w CloudPrint.	—
`status`	`string`	tak	Bieżący stan zasobu lub procesu; użyj wartości dozwolonych dla danej metody.	enum: `pending`, `reserved`, `printing`, `printed`, `failed`, `cancelled`; example: `"pending"`
`copies`	`integer`	tak	Liczba kopii, które CloudPrint zleci drukarce.	min: 1; max: 99; example: `1`
`intent`	`string`	tak	Cel biznesowy zadania, używany w diagnostyce i doborze rozsądnych ustawień domyślnych.	enum: `document`, `shipping_label`, `product_label`, `invoice`, `packing_slip`, `a4_document`, `receipt`; example: `"shipping_label"`
`color_mode`	`string`	tak	Tryb koloru; `default` pozostawia wybór konfiguracji drukarki.	enum: `default`, `monochrome`, `color`; example: `"default"`
`duplex_mode`	`string`	tak	Żądany tryb druku jednostronnego lub dwustronnego.	enum: `default`, `simplex`, `duplex_long_edge`, `duplex_short_edge`; example: `"default"`
`media_width_mm`	`number \| null`	tak	Żądana szerokość nośnika lub etykiety w milimetrach.	min: 1; max: 2000; example: `58`
`media_height_mm`	`number \| null`	tak	Żądana wysokość nośnika lub etykiety w milimetrach.	min: 1; max: 2000; example: `40`
`dpi`	`integer \| null`	tak	Docelowa rozdzielczość druku w punktach na cal; użyj wartości obsługiwanej przez drukarkę.	min: 72; max: 2400; example: `203`
`scale_mode`	`string`	tak	Określa, czy zachować rozmiar dokumentu, czy dopasować go do nośnika.	enum: `none`, `fit`; example: `"none"`
`orientation`	`string`	tak	Orientacja strony; `default` używa ustawień drukarki.	enum: `default`, `portrait`, `landscape`; example: `"default"`
`offset_x_mm`	`number`	tak	Poziome przesunięcie druku w milimetrach.	min: -2000; max: 2000; example: `0`
`offset_y_mm`	`number`	tak	Pionowe przesunięcie druku w milimetrach.	min: -2000; max: 2000; example: `0`
`margin_top_mm`	`number`	tak	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_right_mm`	`number`	tak	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_bottom_mm`	`number`	tak	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`margin_left_mm`	`number`	tak	Dodatkowy margines druku w milimetrach.	min: 0; max: 2000; example: `0`
`created_at`	`string (date-time)`	tak	Znacznik czasu CloudPrint w formacie ISO 8601.	—
`reserved_at`	`string \| null (date-time)`	tak	Znacznik czasu CloudPrint w formacie ISO 8601.	—
`started_at`	`string \| null (date-time)`	tak	Znacznik czasu CloudPrint w formacie ISO 8601.	—
`completed_at`	`string \| null (date-time)`	tak	Znacznik czasu CloudPrint w formacie ISO 8601.	—
`failure_reason`	`string \| null`	tak	Maszynowo czytelna lub diagnostyczna przyczyna nieudanego druku.	—

Przykładowa odpowiedź

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
}

Błędy

Status HTTP	Opis
`401`	Brak uwierzytelnienia albo jest ono nieprawidłowe.
`403`	Brak uprawnień wymaganych do tej operacji.
`409`	Żądanie jest sprzeczne z bieżącym stanem zasobu.
`422`	Pola żądania nie przeszły walidacji.
`429`	Przekroczono limit żądań; zastosuj Retry-After.
`500`	Wewnętrzny błąd CloudPrint.

Wskazówki integracyjne

Wysyłaj stabilny Idempotency-Key dla każdego żądania, które może zostać ponowione.
Odpowiedź 201 oznacza utworzenie zadania, a nie fizyczny wydruk. Sprawdzaj je aż do stanu printed albo failed.
Porównaj opcje druku z możliwościami wybranej drukarki.

Powiązana dokumentacja

Prześlij dokument do drukuPrześlij gotowy PDF lub jawne dane RAW języka drukarki przed utworzeniem zadania CloudPrint.Pobierz status zadania drukuOdczytuj zadanie CloudPrint, aż osiągnie końcowy status printed albo failed.Idempotentne tworzenie zadańZapobiegaj podwójnemu drukowi podczas ponawiania żądań po przekroczeniu limitu czasu lub błędzie sieci.

Utwórz zadanie druku ​

Działanie metody ​

Uwierzytelnianie ​

Żądanie ​

Parametry ​

Treść żądania ​

Przykładowe żądania ​

cURL ​

PHP ​

Odpowiedź ​

Pola odpowiedzi ​

Przykładowa odpowiedź ​

Błędy ​

Wskazówki integracyjne ​

Powiązana dokumentacja ​