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 nowe jednorazowe potwierdzenie RS256. Pola iss i sub wskazują Developer Application, kid wybiera aktywny klucz publiczny, a aud musi odpowiadać Partner Management audience. Prześlij potwierdzenie 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ę, żądane uprawnienia i adres powrotu. Po przekroczeniu czasu oczekiwania powtórz tę samą treść żądania i klucz, zmieniając tylko potwierdzenie aplikacji; nie twórz drugiego klienta ani nowych wartości state i Idempotency-Key.
Zapisz stabilne powiązania
Przechowuj external_customer_id, relationship_id, installation_id, stan i czas zmian w jednym rekordzie integracji. CloudPrint wyszukuje klienta i chroni przed duplikatami według external_customer_id w obrębie uwierzytelnionej Developer Application, dlatego oddzielne aplikacje staging i production mogą używać tego samego identyfikatora klienta. 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 relationship_id. Aby znaleźć klienta po własnym identyfikatorze, wywołaj GET /partner-api/v1/accounts?external_customer_id={tenantId}. Zwykły GET /partner-api/v1/accounts używa parametrów limit, nieprzezroczystego cursor i next_cursor; wyszukiwania po external_customer_id nie łącz z kursorem. Wskaźniki dostępności nie uwzględniają odwołanych agentów ani ich drukarek. Agent jest dostępny tylko przy statusie online i sygnale heartbeat z ostatniej minuty. Drukarka musi mieć własny status online, a obsługujący ją agent także musi być dostępny. onboarding_status=ready pojawia się 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 tą samą treścią, tym samym Idempotency-Key i nowym potwierdzeniem aplikacji. Dopóki istnieje zaszyfrowany zapis idempotencji, odpowiedź zwróci istniejące powiązanie i pierwotny link do podłączenia agenta. Później odczytaj powiązanie przez external_customer_id; nowy Enrollment utwórz dopiero po wygaśnięciu pierwotnego linku.
Monitoruj wykorzystanie i płatności
Pobieraj dane za miesiąc kalendarzowy UTC przez GET /partner-api/v1/usage?period=YYYY-MM. Odpowiedź zawiera liczbę zarządzanych kont, aktywnych agentów i zadań druku potrzebną do obsługi oraz rozliczeń, ale nie zmienia uzgodnionej kwoty faktury. Po zawieszeniu dostępu produkcyjnego Developer Account operacje zarządzania i objęte ograniczeniem operacje drukowania zwracają 403 do czasu przywrócenia dostępu.