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 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
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
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 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.