Best practice

Segui questi schemi per mantenere le integrazioni partner prevedibili, osservabili e sicure per le strutture.

Identificare le strutture in modo coerente

Scegli il metodo di collegamento configurato per il tuo account partner e usalo in modo coerente:

• Direct Link - usa il facility_id del Performance Hub restituito dall'endpoint delle strutture.
• Linking Identifier - usa il tuo identificatore di sede, ad esempio un ID filiale, un codice di sede o un numero di negozio.

Non inviare entrambi gli identificatori nella stessa richiesta. Il Performance Hub risolve le richieste con il metodo di collegamento configurato per il tuo account partner.

Consulta Metodi di collegamento dei partner per le indicazioni sulla configurazione.

Scritture in batch con attenzione

La Partner API accetta corpi di richiesta JSON ed è progettata, dove documentato, per flussi di sincronizzazione basati su batch. Mantieni i batch di dimensioni limitate e ripetibili.

Indicazioni predefinite:

• Usa fino a 1000 elementi per richiesta batch per prestazioni ottimali.
• Mantieni i payload sotto i 10MB.
• Resta entro 5 richieste al secondo per endpoint.

I limiti di frequenza sono modificabili e possono essere configurati caso per caso dal tuo account manager partner del Performance Hub. Se prevedi importazioni ad alto volume, traffico di lancio o backfill di report, concorda il throughput necessario prima della finestra di modifica.

Se devi sincronizzare un set di dati di grandi dimensioni, suddividilo in blocchi deterministici e registra l'ID di ogni blocco dal tuo lato. In questo modo è più facile analizzare i tentativi non riusciti.

Ripetere i tentativi in sicurezza

Usa un backoff esponenziale per gli errori temporanei, come 429, 500, 502, 503 e 504.

Evita cicli di tentativi ravvicinati. Un buon punto di partenza è:

1. Riprova dopo 1 secondo.
2. Riprova dopo 2 secondi.
3. Riprova dopo 4 secondi.
4. Interrompi e invia un avviso se l'operazione continua a non riuscire.

Per gli errori di convalida, come 400 o 422, correggi la richiesta prima di riprovare.

Usare l'idempotenza dove supportata

L'endpoint di sblocco del Door/Gate Controller supporta una idempotency_key facoltativa. Riutilizzando la stessa chiave per lo stesso partner, la stessa struttura e la stessa porta si ottiene il risultato esistente, se disponibile.

Usa una chiave stabile per l'azione eseguita, ad esempio un ID di check-in o un ID di evento di accesso del tuo sistema.

Non dare per scontato che ogni endpoint di scrittura supporti l'idempotenza, a meno che non sia documentato per quell'endpoint.

Mantenere puliti i dati di origine

Invia, ove possibile, valori stabili e normalizzati:

• Usa ID coerenti per membri, piani, strutture e check-in provenienti dal tuo sistema di origine.
• Usa timestamp ISO 8601 per date e orari.
• Invia i numeri di telefono in formato internazionale, se disponibili.
• Invia le valute usando i campi documentati per ciascun endpoint.
• Evita di sovraccaricare i campi di testo libero con dati che appartengono a campi strutturati.

Progettare per sincronizzazioni incrementali e complete

La maggior parte delle integrazioni partner ha bisogno di entrambe:

• Sincronizzazioni incrementali per le modifiche quotidiane.
• Sincronizzazioni di riconciliazione complete per correggere eventi mancati, importazioni storiche o disallineamenti dei dati.

La tua integrazione deve essere in grado di inviare di nuovo lo stato attuale di un membro, di un piano di abbonamento o di un'istantanea di report senza dipendere dall'esito positivo di una richiesta precedente.

Pubblicare le Access Time Windows in sicurezza

Tratta il valore access_time_windows di ogni membro come un'istantanea completa con una revisione indipendente:

• Coordina un unico flusso monotonicamente crescente di access_time_windows_revision tra i worker incrementali e quelli di riconciliazione.
• Ripeti una consegna incerta o non riuscita temporaneamente con la stessa revisione e lo stesso payload normalizzato.
• Ometti access_time_windows quando non lo aggiorni.
• Invia [] solo dopo che un recupero riuscito dalla fonte autorevole dimostra che non restano finestre. Non trasformare mai un timeout a monte, un risultato parziale o un errore di parsing in una revoca.
• Mantieni stabili external_id e scope_key e certifica ogni mappatura degli ambiti prima della produzione.
• Monitora l'età dei dati di origine rispetto ai criteri di aggiornamento concordati per quell'integrazione.

Consulta la guida autorevole per i produttori di Access Time Windows per istantanee complete, fusi orari, ora legale, annullamento e vettori di test.

Considerare il controllo degli accessi un aspetto critico per la sicurezza

Per gli sblocchi dei Door/Gate Controller:

• Il tuo sistema deve decidere se la persona può entrare prima di chiamare il Performance Hub.
• Il Performance Hub restituisce 200 solo dopo che il controller in loco ha confermato che il relè si è fisicamente sbloccato.
• La maggior parte delle conferme arriva entro 3-5 secondi.
• Un timeout è uno sblocco esplicitamente non riuscito, non un successo in background.
• Ripeti i tentativi solo secondo le tue regole di accesso e di sicurezza.

Registra sempre l'event_id e il command_id restituiti dall'endpoint di sblocco.

Monitorare la tua integrazione

Usa i log delle richieste della Partner Console durante lo sviluppo e il lancio. In produzione, mantieni anche log propri con:

• Data e ora della richiesta.
• Endpoint.
• ID del record di origine.
• Identificatore della struttura.
• Codice di stato HTTP.
• Corpo della risposta o messaggio di errore del Performance Hub.

Questi campi rendono l'assistenza e la riconciliazione molto più rapide quando un cliente chiede cosa è successo.