Instalacje i tokeny dostępu
App Installation jest stałym powiązaniem jednego Developer Application z jednym kontem klienta. Zapisz `installation_id` i pobieraj krótkotrwały token, gdy Twój serwer potrzebuje dostępu do Print API tego konta.
Wybierz model instalacji
Użyj tego procesu zatwierdzanego przez klienta, gdy ma on już konto CloudPrint. Dla kont tworzonych przez Twój produkt użyj Partner Platform: App Installation powstaje przez Partner API bez przekierowania klienta do ekranu zgody.
Utwórz link instalacyjny
Dodaj do adresu instalacji client_id, jeden dokładnie zarejestrowany redirect_uri, nieprzewidywalny state powiązany z bieżącym użytkownikiem i klientem oraz tylko potrzebne uprawnienia. Skieruj właściciela konta pod ten adres. Account ID przesłany przez interfejs nie jest sam w sobie dowodem uprawnienia.
Uzyskaj zgodę właściciela
CloudPrint pokaże nazwę aplikacji, Developer Account, publiczne linki i żądane uprawnienia. Właściciel wybierze konto CloudPrint i zatwierdzi dostęp. Na początku proś tylko o niezbędne uprawnienia; dodatkowe funkcje powinny wymagać osobnej, czytelnej zgody.
Sprawdź powrót użytkownika
callback zawiera installation_id, setup_action i pierwotny state. Porównaj state z wartością zapisaną na serwerze, odrzuć wygasłą lub ponownie użytą próbę i powiąż instalację z klientem, który rozpoczął proces. Nie używaj CloudPrint Account ID zamiast identyfikatora klienta w swoim systemie.
Wydaj Installation Access Token
Utwórz nowy assertion RS256 aplikacji z aud równym https://public-api.cloudprint.me/developer-api/v1/app-installations/{installationId}/access-tokens. Prześlij go jako Authorization: Bearer <application_assertion> do POST /developer-api/v1/app-installations/{installationId}/access-tokens. Odpowiedź zawiera access_token, expires_in, account_id, installation_id i zatwierdzone uprawnienia.
Używaj i przechowuj token
Przekazuj Installation Access Token jako Bearer do /api/v1/*. Przechowuj go osobno dla każdej instalacji prawie do wygaśnięcia zamiast pobierać nowy dla każdego wydruku. Refresh token nie jest wydawany — kolejny krótkotrwały token uzyskasz dla tej samej instalacji.
Sprawdzaj uprawnienia i stan
Żądane uprawnienia muszą być niepustym podzbiorem uprawnień instalacji. Instalacja w stanie suspended nie może wydawać ani używać tokenów do czasu wznowienia, a stanu revoked nie można cofnąć. Po 401 usuń token z pamięci podręcznej i pobierz nowy tylko raz; po 403 sprawdź uprawnienia i stan instalacji.
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.