Szybki start z CloudPrint API
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
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:
{
"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:
curl -sS https://public-api.cloudprint.me/api/v1/me \
-H "Authorization: Bearer $ACCESS_TOKEN"2. Wybierz stabilny printer_id
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.
3. Prześlij gotowy dokument
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:
{
"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.
4. Utwórz idempotentne zadanie
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:
{
"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
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.