Tworzenie i zarządzanie kontami klientów
Utwórz osobne konto CloudPrint dla każdego klienta i zapisz powiązanie między identyfikatorem klienta w swoim systemie, Partner Account Relationship oraz App Installation zwróconymi przez CloudPrint.
Uwierzytelnij Partner API
Dla każdego wywołania Partner API twórz nowy jednorazowy assertion RS256. Pola iss i sub wskazują Developer Application, kid wybiera aktywny klucz publiczny, a aud musi odpowiadać Partner Management audience. Prześlij assertion jako Bearer do /partner-api/v1/*; Installation Access Token jest przeznaczony do drukowania, a nie do zarządzania kontami.
Bezpiecznie ponawiaj tworzenie konta
Przed wywołaniem POST /partner-api/v1/accounts zapisz dane oczekującej operacji: Idempotency-Key, state, nazwę, permissions i callback. Po przekroczeniu czasu powtórz to samo body i klucz, zmieniając tylko assertion aplikacji; nie twórz drugiego klienta, state ani klucza.
Zapisz stabilne powiązania
Przechowuj external_customer_id, relationship_id, installation_id, stan i czas zmian w jednym rekordzie integracji. relationship_id służy do zarządzania klientem przez Partner API, a installation_id do wydawania tokenów Print API. cloudprint_account_id zachowaj tylko do opcjonalnego porównania z account_id w odpowiedzi tokenu.
Pobierz jednego klienta bez przeglądania listy
Użyj GET /partner-api/v1/accounts/{relationshipId}, jeśli znasz relację. Do dokładnego uzgodnienia przez tenant wywołaj GET /partner-api/v1/accounts?external_customer_id={tenantId}. Zwykły GET /partner-api/v1/accounts używa limit, nieprzezroczystego cursor i next_cursor; dokładnego wyszukiwania nie łącz z cursor. Dane health nie uwzględniają odwołanych Agents ani ich drukarek. Agent jest online tylko przy statusie online i heartbeat z ostatniej minuty. Drukarka jest online tylko wtedy, gdy sama ma status online, a obsługujący ją Agent jest dostępny na tych samych zasadach. onboarding_status=ready jest ustawiany po pierwszym uwierzytelnionym heartbeat, nawet gdy Agent nie zgłosił żadnej drukarki. Włącz drukowanie dopiero przy status=active, online_agent_count > 0 i online_printer_count > 0.
Jawnie zawieszaj i zamykaj
Używaj POST /partner-api/v1/accounts/{relationshipId}/{action} z suspend, resume albo close. Suspension odwołuje Installation tokens, po resume potrzebny jest nowy token, a close jest nieodwracalne. Dla zawieszonego konta objęte operacje Print API zwracają 403 remote_printing.account.service_suspended.
Odzyskaj odpowiedź utraconą podczas tworzenia konta
Powtórz POST /partner-api/v1/accounts z tym samym body, Idempotency-Key i nowym assertion aplikacji. Dopóki istnieje zaszyfrowany rekord idempotency, odpowiedź zwróci istniejącą relację i pierwotny hosted onboarding URL. Później odczytaj relację przez external_customer_id; nowy Enrollment utwórz dopiero po wygaśnięciu pierwotnego URL.
Monitoruj usage i płatności
Pobieraj miesiąc UTC przez GET /partner-api/v1/usage?period=YYYY-MM. Odpowiedź raportuje managed accounts, active Agents i print jobs dla operacji oraz dokumentu rozliczeniowego, ale nie zmienia stałej kwoty faktury. Po zawieszeniu Partner Program za brak płatności management i objęte operacje drukowania zwracają 403 do przywrócenia usługi.
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.