Tworzenie i śledzenie zadań druku
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
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:
{
"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 reprint
Zawsze wysyłaj Idempotency-Key. Ten sam klucz i input zwracają pierwotne zadanie; zmieniony input daje 409 ...idempotency_key_conflict. Retry zachowuje klucz, świadomy reprint dostaje nowy klucz i audyt.
Odczytaj wynik
curl -sS https://public-api.cloudprint.me/api/v1/print-jobs/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb \
-H "Authorization: Bearer $ACCESS_TOKEN"Końcowe: printed, failed. Pośrednie: pending, reserved, printing. Nieznane traktuj jako pośrednie. Obecne Public API nie ma result webhook: odpytuj zapisany URL z ograniczonym konfigurowalnym interwałem i jitter, zwalniaj przy długim oczekiwaniu i respektuj Retry-After. Przy failed zachowaj failure_reason; 2xx utworzenia nie potwierdza wydruku.
Lista i uzgadnianie
curl -sS 'https://public-api.cloudprint.me/api/v1/print-jobs?limit=20' \
-H "Authorization: Bearer $ACCESS_TOKEN"{
"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
{
"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 OAuth, upload lub JSON | poprawić żądanie, nie ponawiać bez zmian |
401 | złe credentials albo wygasły/nieprawidłowy token | raz odświeżyć token i raz ponowić |
403 | ważny token bez wymaganego scope | zmienić grants client app; refresh 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łędne ID, metadata lub opcje | poprawić walidację przed retry |
429 | przekroczony limit | czekać zgodnie z Retry-After |
500 | nieoczekiwany błąd CloudPrint | ograniczony backoff z 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.
Lista kontrolna przed wdrożeniem
- Korzystaj z wychodzącego połączenia agenta; nie wystawiaj portów drukarki do internetu.
- Zapisuj stabilny identyfikator drukarki, a nie tylko jej nazwę.
- Sprawdzaj format dokumentu, rozmiar strony i orientację przed utworzeniem zadania.
- Jawnie obsługuj status końcowy, ponowienia i ochronę przed podwójnym drukiem.