Przegląd CloudPrint Public API
Ta strona jest mapą Public API. Przewodniki wyjaśniają decyzje, a interaktywne OpenAPI pozostaje kanonicznym źródłem każdego pola i odpowiedzi.
Adres i granica API
Backend używa https://public-api.cloudprint.me. Właściciel konta łączy agentów i tworzy client apps w https://my.cloudprint.me. Prywatny protokół agenta nie jest API klienta.
Pełna mapa zasobów
| Metoda | Ścieżka | Scope | Zastosowanie |
|---|---|---|---|
POST | /oauth/token | — | Pobranie tokenu OAuth2 |
GET | /api/v1/me | autoryzacja | Sprawdzenie konta, client app i scopes |
GET | /api/v1/agents | agents:read | Stan i wersja agenta |
GET | /api/v1/printers | printers:read | Drukarki i capabilities |
POST | /api/v1/documents | documents:write | Przesłanie PDF lub RAW |
POST | /api/v1/print-jobs | print_jobs:write | Utworzenie zadania dla dokumentu |
POST | /api/v1/print-jobs/from-url | print_jobs:write | Pobranie publicznego HTTPS i utworzenie zadania |
POST | /api/v1/print-jobs/from-base64 | print_jobs:write | Dekodowanie danych inline i utworzenie zadania |
GET | /api/v1/print-jobs | print_jobs:read | Lista zadań z cursor pagination |
GET | /api/v1/print-jobs/{printJobId} | print_jobs:read | Odczyt zadania i wyniku |
Kolejność implementacji
Najpierw token i /me, potem onboarding drukarki, dokument, idempotentne zadanie i polling. URL/Base64 dodaj po działającym przepływie dwuetapowym. /agents służy diagnostyce, lista /print-jobs uzgadnianiu historii.
Paginacja
Listy agentów, drukarek i zadań używają kursora. Wyślij limit 1–100, potem przekaż nieprzezroczysty next_cursor jako cursor. Zatrzymaj się przy null; nie analizuj i nie konstruuj kursora.
Zgodność
Stabilna ścieżka to /api/v1. Ignoruj nieznane pola i traktuj nieznane statusy jako pośrednie. Używaj enumów i limitów z OpenAPI. Zmiany łamiące wymagają nowej wersji major.
Gdzie szukać
Tokeny: Uwierzytelnianie, routing: Agenci i drukarki, dane: Dokumenty, retry/statusy: Zadania, schematy: OpenAPI.
Lista kontrolna przed wdrożeniem
- Przechowuj dane API na backendzie i ograniczaj je do konta właściciela.
- 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.