Bonnes pratiques

Appliquez ces modèles pour que les intégrations partenaires restent prévisibles, observables et sûres pour les installations.

Identifier les installations de manière cohérente

Choisissez la méthode de liaison configurée pour votre compte partenaire et utilisez-la de manière cohérente :

Direct Link - utilisez le facility_id Performance Hub renvoyé par l'endpoint des installations.
Linking Identifier - utilisez votre propre identifiant de site, comme un ID d'agence, un code de site ou un numéro de magasin.

N'envoyez pas les deux identifiants dans la même requête. Performance Hub résout les requêtes à l'aide de la méthode de liaison configurée pour votre compte partenaire.

Consultez Méthodes de liaison des partenaires pour obtenir des conseils de configuration.

Écrire par lots avec précaution

La Partner API accepte des corps de requête JSON et est conçue pour des procédures de synchronisation par lots, lorsque cela est documenté. Limitez la taille des lots et faites en sorte qu'ils puissent être relancés.

Recommandations par défaut :

Utilisez jusqu'à 1000 éléments par requête par lot pour des performances optimales.
Maintenez les charges utiles sous 10MB.
Ne dépassez pas 5 requêtes par seconde et par endpoint.

Les limites de débit sont ajustables et peuvent être configurées au cas par cas par votre responsable de compte partenaire Performance Hub. Si vous prévoyez des importations volumineuses, du trafic lié à un lancement ou des importations rétroactives de données de reporting, convenez du débit nécessaire avant la fenêtre de modification.

Si vous devez synchroniser un jeu de données volumineux, divisez-le en blocs déterministes et journalisez l'ID de chaque bloc de votre côté. Il est ainsi plus facile d'analyser les nouvelles tentatives en échec.

Réessayer en toute sécurité

Utilisez un backoff exponentiel pour les échecs temporaires tels que 429, 500, 502, 503 et 504.

Évitez les boucles de nouvelles tentatives rapprochées. Un bon point de départ consiste à :

Réessayer après 1 seconde.
Réessayer après 2 secondes.
Réessayer après 4 secondes.
Arrêter et déclencher une alerte si l'opération échoue toujours.

Pour les échecs de validation tels que 400 ou 422, corrigez la requête avant de réessayer.

Utiliser l'idempotence lorsqu'elle est prise en charge

L'endpoint de déverrouillage des contrôleurs de porte/portail prend en charge une idempotency_key facultative. Réutiliser la même clé pour le même partenaire, la même installation et la même porte renvoie le résultat existant lorsqu'il est disponible.

Utilisez une clé stable pour l'action effectuée, par exemple un ID d'enregistrement d'entrée ou un ID d'événement d'accès provenant de votre système.

Ne supposez pas que tous les endpoints d'écriture prennent en charge l'idempotence, sauf si cela est documenté pour l'endpoint concerné.

Maintenir des données sources propres

Envoyez des valeurs stables et normalisées dans la mesure du possible :

Utilisez des ID de membres, de formules, d'installations et d'enregistrements d'entrée cohérents provenant de votre système source.
Utilisez des horodatages ISO 8601 pour les dates et les heures.
Envoyez les numéros de téléphone au format international lorsqu'ils sont disponibles.
Envoyez les devises à l'aide des champs documentés pour chaque endpoint.
Évitez de surcharger les champs de texte libre avec des données qui ont leur place dans des champs structurés.

Prévoir des synchronisations incrémentielles et complètes

La plupart des intégrations partenaires ont besoin des deux :

Synchronisations incrémentielles pour les modifications quotidiennes.
Synchronisations de rapprochement complètes pour corriger les événements manqués, les importations historiques ou les dérives de données.

Votre intégration doit pouvoir renvoyer l'état actuel d'un membre, d'une formule d'abonnement ou d'un instantané de rapport sans dépendre de la réussite d'une requête précédente.

Publier les Access Time Windows en toute sécurité

Traitez la valeur access_time_windows de chaque membre comme un instantané complet, doté de sa propre révision indépendante :

Coordonnez un flux unique et strictement croissant de access_time_windows_revision entre les processus incrémentiels et de rapprochement.
Relancez une livraison incertaine ou temporairement en échec avec la même révision et la même charge utile normalisée.
Omettez access_time_windows lorsque vous ne le mettez pas à jour.
N'envoyez [] qu'après qu'une récupération réussie depuis la source de référence a prouvé qu'il ne reste aucune plage. Ne transformez jamais un délai d'expiration en amont, un résultat partiel ou un échec d'analyse en révocation.
Gardez external_id et scope_key stables, et certifiez chaque correspondance de portée avant la mise en production.
Surveillez l'ancienneté des données sources par rapport à la politique de fraîcheur convenue pour cette intégration.

Consultez le guide de référence pour les producteurs d'Access Time Windows pour les instantanés complets, les fuseaux horaires, l'heure d'été, l'annulation et les vecteurs de test.

Traiter le contrôle d'accès comme critique pour la sécurité

Pour les déverrouillages de contrôleurs de porte/portail :

Votre système doit décider si la personne est autorisée à entrer avant d'appeler Performance Hub.
Performance Hub ne renvoie 200 qu'après que le contrôleur sur site a confirmé le déverrouillage physique du relais.
La plupart des confirmations aboutissent en 3 à 5 secondes.
Un délai d'expiration correspond à un échec explicite du déverrouillage, et non à une réussite en arrière-plan.
Ne réessayez que conformément à vos propres règles d'accès et de sécurité.

Journalisez toujours l'event_id et le command_id renvoyés par l'endpoint de déverrouillage.

Surveiller votre intégration

Utilisez les journaux de requêtes de la Partner Console pendant le développement et le lancement. En production, tenez également vos propres journaux avec :

L'horodatage de la requête.
L'endpoint.
L'ID de l'enregistrement source.
L'identifiant d'installation.
Le code de statut HTTP.
Le corps de la réponse ou le message d'erreur de Performance Hub.

Ces champs accélèrent considérablement l'assistance et le rapprochement lorsqu'un client demande ce qui s'est passé.