Szybki start z CloudPrint API
Najpierw wykonaj jeden pełny wydruk, a dopiero potem projektuj kolejki i retry. Każde żądanie zwraca identyfikator używany w następnym kroku, a status końcowy potwierdza faktyczny wynik.
Wymagania i granica odpowiedzialności
Potrzebujesz konta, agenta online przy drukarce i backendu chroniącego client_secret. System zewnętrzny wywołuje tylko https://public-api.cloudprint.me, nigdy lokalnego agenta. Utwórz client app ze scopes printers:read, documents:write, print_jobs:write, print_jobs:read.
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 czas życia:
{
"token_type": "Bearer",
"expires_in": 900,
"access_token": "eyJ..."
}Ustaw ACCESS_TOKEN w testowym shellu i wywołaj /api/v1/me, aby wykryć złe konto lub scope:
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"Wybierz rekord, w którym drukarka i agent są online. Zapisz printer_id w konfiguracji lokalizacji; nazwa nie jest kluczem. Przed RAW i opcjami 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 i jawne dane RAW. ZPL oraz skróty 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, printing. Zakończ dla printed lub failed; przy failed zapisz failure_reason. Nieznany przyszły status traktuj jako pośredni. Sukces oznacza dokładnie jedną kopię na właściwej drukarce i status printed.
6. Zapisz dane operacyjne
Łącz X-Request-Id z biznesowym ID. 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. Retry po timeout zachowuje payload i klucz; świadomy reprint dostaje nowy klucz. Przed produkcją przeczytaj Zadania druku.
Lista kontrolna przed wdrożeniem
- Przechowuj dane API na backendzie i ograniczaj je do konta właściciela.
- Korzystaj z wychodzącego połączenia agenta; nie wystawiaj portów drukarki do internetu.
- Zapisuj stabilny identyfikator drukarki, a nie tylko jej nazwę.
- Jawnie obsługuj status końcowy, ponowienia i ochronę przed podwójnym drukiem.