Zacznij od jednego testu całego procesu. Każdy krok API zwraca identyfikator potrzebny w następnym żądaniu, a fizyczny wydruk sprawdza się niezależnie od końcowego statusu zadania.
## Zanim zaczniesz Potrzebujesz konta CloudPrint, komputera z dostępem do docelowej drukarki, zainstalowanego na nim CloudPrint Agent ze statusem `online` oraz serwera, który bezpiecznie przechowa `client_secret`. Serwer wysyła żądania wyłącznie do `https://public-api.cloudprint.me` i nie łączy się bezpośrednio z lokalnym agentem. Utwórz aplikację API z uprawnieniami `printers:read`, `documents:write`, `print_jobs:write` i `print_jobs:read`. Istniejące `documents:write` obejmuje gotowe PDF i sprawdzane dokumenty RAW. ## 1. Pobierz i sprawdź token ```bash curl -sS https://public-api.cloudprint.me/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \ --data-urlencode 'scope=printers:read documents:write print_jobs:write print_jobs:read' ``` Odpowiedź zawiera token i okres jego ważności: ```json { "token_type": "Bearer", "expires_in": 900, "access_token": "eyJ..." } ``` Ustaw `ACCESS_TOKEN` w testowej powłoce i wywołaj `/api/v1/me`, aby wykryć niewłaściwe konto lub brakujące uprawnienie: ```bash curl -sS https://public-api.cloudprint.me/api/v1/me \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` ## 2. Wybierz stabilny printer_id ```bash curl -sS 'https://public-api.cloudprint.me/api/v1/printers?limit=100' \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` Agent musi być `online`. Do ostrożnego routingu automatycznego wybierz drukarkę ze stanem `online` albo natywnymi danymi `cups_ipp`/`windows_spooler` i `accepting_jobs=true`. Ostrzeżenie o stanie fizycznym nadal pokaż operatorowi. Zapisz `printer_id`; nazwa nie jest kluczem. Przed RAW przeczytaj [Agenci i drukarki](../api/agents-and-printers/). ## 3. Prześlij gotowy dokument ```bash curl -sS https://public-api.cloudprint.me/api/v1/documents \ -H "Authorization: Bearer $ACCESS_TOKEN" \ -F 'file=@invoice.pdf;type=application/pdf' ``` Odpowiedź dostarcza ID dla zadania: ```json { "document_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa", "original_filename": "invoice.pdf", "mime_type": "application/pdf", "document_format": "pdf", "document_raw_language": null, "size_bytes": 1024 } ``` Akceptowane są gotowe PDF oraz jawne dane RAW w językach ZPL, TSPL, CPCL lub ESC/POS. Skróty bez osobnego przesyłania opisuje strona [Dokumenty](../api/documents/). ## 4. Utwórz idempotentne 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" }' ``` Opcje są polami najwyższego poziomu; kontrakt nie ma obiektu `options`. Zapisz `print_job_id` obok zamówienia lub faktury: ```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 } ``` ## 5. Czekaj na status końcowy ```bash curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \ -H "Authorization: Bearer $ACCESS_TOKEN" ``` Kontynuuj dla `pending`, `reserved` i `printing`. Zakończ dla `printed`, `failed` lub `cancelled`. `printed` oznacza, że kolejka systemowa przyjęła dokument; ten status nie potwierdza fizycznego wydruku. Przy `failed` zapisz `failure_reason`; `cancelled` oznacza brak przyjęcia przez kolejkę. Nieznany status traktuj jako pośredni. Test przedwdrożeniowy kończy się, gdy właściwa drukarka fizycznie wydrukuje dokładnie jedną kopię, a zadanie ma status `printed`. ## 6. Zapisz dane operacyjne Łącz `X-Request-Id` z identyfikatorem biznesowym. Możesz wysłać własną bezpieczną wartość tego nagłówka; CloudPrint ją zwróci albo zastąpi wartość niebezpieczną. Przechowuj `print_job_id`, `printer_id`, klucz idempotencji i zmiany statusu. Ponowienie żądania po przekroczeniu limitu czasu zachowuje te same dane i klucz; świadomy ponowny wydruk otrzymuje nowy klucz. Przed uruchomieniem przeczytaj [Zadania druku](../api/print-jobs/). ## Następne kroki