Przy tworzeniu zadania liczą się ochrona przed duplikatem i zgodność drukarki. Wszystkie opcje są polami najwyższego poziomu, a rekord zadania należy śledzić do statusu końcowego.
## Utwórz zadanie ```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-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" }' ``` Sukces zwraca HTTP 201: ```json { "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 } ``` ## Obsługiwane pola | Pole | Dozwolone wartości | | --- | --- | | `copies` | liczba całkowita, minimum 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` | liczba od -2000 do 2000 | | `margin_*_mm` | liczba od 0 do 2000 | | `media_width_mm`, `media_height_mm` | opcjonalna liczba od 1 do 2000 | | `dpi` | opcjonalna liczba całkowita od 72 do 2400 | Każda opcja niestandardowa musi być obsługiwana. Zła wartość daje `422`; niemożliwa trasa `409 ...unsupported` z `details.reason`. ## Idempotencja i ponowny wydruk Zawsze wysyłaj `Idempotency-Key`. Ten sam klucz i te same dane zwracają pierwotne zadanie; zmienione dane powodują `409 ...idempotency_key_conflict`. Ponowienie żądania zachowuje klucz, a świadomy ponowny wydruk otrzymuje nowy klucz i osobną informację audytową. ## Odczytaj wynik ```bash curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` Końcowe statusy to `printed`, `failed` i `cancelled`; pośrednie to `pending`, `reserved` i `printing`. `printed` potwierdza przyjęcie dokumentu przez kolejkę systemową, ale nie potwierdza fizycznego wydruku. Nieznane statusy traktuj jako pośrednie. Obecne Public API nie ma webhooka z wynikiem: odpytuj zapisany URL w ograniczonym, konfigurowalnym odstępie, dodaj niewielkie losowe przesunięcie, wydłużaj odstęp przy długim oczekiwaniu i respektuj `Retry-After`. Przy `failed` zachowaj `failure_reason`; `cancelled` oznacza brak przyjęcia przez kolejkę. Odpowiedź 2xx również nie potwierdza fizycznego wydruku. ## Lista i uzgadnianie ```bash curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ```json { "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 } ``` Lista służy do uzgadniania historii, nie zastępuje zapisanego ID. Przekazuj nieprzezroczysty `next_cursor` jako `cursor` do `null`; zwykły status czytaj po `print_job_id`. ## Strategia błędów ```json { "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 | Znaczenie | Działanie klienta | | --- | --- | --- | | `400` | błędne dane OAuth2, przesyłanie pliku lub JSON | poprawić żądanie; nie ponawiać go bez zmian | | `401` | błędne dane dostępowe albo wygasły lub nieprawidłowy token | odświeżyć token jeden raz i jeden raz ponowić żądanie | | `403` | ważny token bez wymaganego uprawnienia | zmienić uprawnienia aplikacji API; samo odświeżenie tokenu nie pomoże | | `404` | brak zasobu lub inne konto | sprawdzić konto i zapisany identyfikator | | `409` | konflikt idempotencji albo nieobsługiwana trasa | sprawdzić `error_code` i `details.reason`; nie tworzyć nowego klucza | | `413` | dokument jest za duży | zmniejszyć go lub wybrać inny transport | | `415` | typ dokumentu nie jest obsługiwany | wysłać gotowy PDF lub obsługiwany RAW | | `422` | błąd walidacji albo dokument nie przeszedł kontroli bezpieczeństwa | zmienić dokument lub żądanie przed ponowieniem | | `429` | przekroczony limit | czekać zgodnie z `Retry-After` | | `500` | nieoczekiwany błąd CloudPrint | ponowić z ograniczonym, rosnącym opóźnieniem i pierwotnym kluczem idempotencji | | `503` | kontrola bezpieczeństwa dokumentów jest tymczasowo niedostępna | ponowić z ograniczonym, rosnącym opóźnieniem i pierwotnym kluczem idempotencji | HTTP daje klasę, `error/error_code` gałąź, a `message` jest diagnostyczny. Każda odpowiedź ma `X-Request-Id`; zapisuj go obok biznesowego ID. ## Następne kroki