Sprawdzone metody

Stosuj te wzorce, aby integracje partnerów były przewidywalne, łatwe do monitorowania i bezpieczne dla obiektów.

Spójna identyfikacja obiektów

Wybierz metodę łączenia skonfigurowaną dla Twojego konta partnera i stosuj ją konsekwentnie:

• Direct Link — używaj wartości facility_id Performance Hub zwracanej przez punkt końcowy obiektów.
• Linking Identifier — używaj własnego identyfikatora lokalizacji, np. identyfikatora oddziału, kodu lokalizacji lub numeru sklepu.

Nie wysyłaj obu identyfikatorów w tym samym żądaniu. Performance Hub rozpoznaje żądania na podstawie metody łączenia skonfigurowanej dla Twojego konta partnera.

Wskazówki dotyczące konfiguracji znajdziesz w sekcji Metody łączenia partnerów.

Ostrożne zapisy zbiorcze

Partner API przyjmuje treść żądań w formacie JSON i tam, gdzie zostało to udokumentowane, jest przeznaczone do procesów synchronizacji opartych na partiach. Partie powinny mieć ograniczony rozmiar i umożliwiać ponawianie.

Domyślne zalecenia:

• Używaj maksymalnie 1000 elementów na żądanie zbiorcze, aby uzyskać optymalną wydajność.
• Utrzymuj rozmiar ładunku poniżej 10MB.
• Nie przekraczaj 5 żądań na sekundę na punkt końcowy.

Limity liczby żądań można dostosować — opiekun konta partnera Performance Hub może je skonfigurować indywidualnie. Jeśli spodziewasz się dużych importów, ruchu podczas uruchomienia lub uzupełniania danych raportowych, uzgodnij wymaganą przepustowość przed oknem zmian.

Jeśli musisz zsynchronizować duży zbiór danych, podziel go na deterministyczne fragmenty i rejestruj po swojej stronie identyfikator każdego fragmentu. Ułatwia to analizę nieudanych ponowień.

Bezpieczne ponawianie

W przypadku przejściowych błędów, takich jak 429, 500, 502, 503 i 504, stosuj wykładnicze wydłużanie odstępów między ponowieniami.

Unikaj ciasnych pętli ponowień. Dobry punkt wyjścia:

1. Ponów po 1 sekundzie.
2. Ponów po 2 sekundach.
3. Ponów po 4 sekundach.
4. Zatrzymaj się i wygeneruj alert, jeśli operacja nadal kończy się niepowodzeniem.

W przypadku błędów walidacji, takich jak 400 lub 422, popraw żądanie przed ponowieniem.

Korzystanie z idempotencji tam, gdzie jest obsługiwana

Punkt końcowy otwierania kontrolera drzwi/bramy obsługuje opcjonalny idempotency_key. Ponowne użycie tego samego klucza dla tego samego partnera, obiektu i drzwi zwraca istniejący wynik, jeśli jest dostępny.

Używaj stabilnego klucza dla wykonywanej akcji, np. identyfikatora wejścia lub identyfikatora zdarzenia dostępu z Twojego systemu.

Nie zakładaj, że każdy punkt końcowy zapisu obsługuje idempotencję, chyba że zostało to udokumentowane dla danego punktu końcowego.

Dbanie o czystość danych źródłowych

W miarę możliwości wysyłaj stabilne, znormalizowane wartości:

• Używaj spójnych identyfikatorów członków, planów, obiektów i wejść z systemu źródłowego.
• Używaj znaczników czasu ISO 8601 dla dat i godzin.
• Wysyłaj numery telefonów w formacie międzynarodowym, jeśli są dostępne.
• Wysyłaj waluty w polach udokumentowanych dla poszczególnych punktów końcowych.
• Nie przeciążaj pól tekstowych danymi, które należą do pól strukturalnych.

Projektowanie pod kątem synchronizacji przyrostowych i pełnych

Większość integracji partnerów potrzebuje obu rodzajów synchronizacji:

• Synchronizacji przyrostowych do codziennych zmian.
• Pełnych synchronizacji uzgadniających do korygowania pominiętych zdarzeń, importów historycznych lub rozbieżności danych.

Integracja powinna umożliwiać ponowne wysłanie bieżącego stanu członka, planu członkostwa lub migawki raportu bez uzależnienia od powodzenia wcześniejszego żądania.

Bezpieczne publikowanie Access Time Windows

Traktuj wartość access_time_windows każdego członka jako kompletną migawkę z niezależną numeracją wersji:

• Koordynuj jeden monotonicznie rosnący strumień access_time_windows_revision dla procesów przyrostowych i uzgadniających.
• Ponawiaj niepewne lub przejściowo nieudane dostarczenie z tą samą wersją i znormalizowanym ładunkiem.
• Pomijaj access_time_windows, gdy nie aktualizujesz tej wartości.
• Wysyłaj [] dopiero wtedy, gdy udane, wiarygodne pobranie danych ze źródła dowodzi, że nie pozostały żadne okna. Nigdy nie zamieniaj przekroczenia limitu czasu u źródła, częściowego wyniku ani błędu parsowania w odwołanie dostępu.
• Zachowuj stałe wartości external_id i scope_key oraz certyfikuj każde mapowanie zakresu przed wdrożeniem produkcyjnym.
• Monitoruj wiek danych źródłowych w odniesieniu do zasad aktualności uzgodnionych dla danej integracji.

Kompletne migawki, strefy czasowe, czas letni, anulowanie i wektory testowe opisano w nadrzędnym przewodniku producenta Access Time Windows.

Kontrola dostępu jako funkcja krytyczna dla bezpieczeństwa

W przypadku otwierania kontrolerów drzwi/bram:

• Przed wywołaniem Performance Hub Twój system musi zdecydować, czy dana osoba może wejść.
• Performance Hub zwraca 200 dopiero wtedy, gdy kontroler w obiekcie potwierdzi, że przekaźnik fizycznie zwolnił zamek.
• Większość potwierdzeń następuje w ciągu 3-5 sekund.
• Przekroczenie limitu czasu oznacza jednoznacznie nieudane otwarcie, a nie sukces w tle.
• Ponawiaj próby wyłącznie zgodnie z własnymi zasadami dostępu i bezpieczeństwa.

Zawsze rejestruj wartości event_id i command_id zwracane przez punkt końcowy otwierania.

Monitorowanie integracji

Podczas tworzenia i uruchamiania integracji korzystaj z dzienników żądań w Partner Console. W środowisku produkcyjnym prowadź również własne dzienniki zawierające:

• Znacznik czasu żądania.
• Punkt końcowy.
• Identyfikator rekordu źródłowego.
• Identyfikator obiektu.
• Kod stanu HTTP.
• Treść odpowiedzi lub komunikat o błędzie z Performance Hub.

Te pola znacznie przyspieszają wsparcie i uzgadnianie danych, gdy klient pyta, co się stało.