Introduction

La Partner API de Performance Hub permet aux plateformes de partenaires externes de s'intégrer facilement aux modules principaux de Performance Hub. L'API prend en charge la vision par ordinateur, l'analyse, la journalisation des accès des membres et les informations sur les installations.

Format des requêtes

L'API accepte des corps de requête encodés en JSON et renvoie des réponses encodées en JSON.

Limitation du débit

Pour garantir une utilisation équitable et la stabilité du système, les comptes Partner API démarrent avec les limites par défaut suivantes :

• 5 requêtes par seconde par endpoint
• Recommandé : 1000 éléments maximum par requête par lot pour des performances optimales
• Taille de charge utile de 10MB maximum

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 votre intégration nécessite un débit plus élevé pour un lancement, des migrations, des importations rétroactives de données de reporting ou des installations à fort volume, signalez-le lors de l'intégration ou avant la fenêtre de modification prévue.

Authentification

L'accès à la Partner API nécessite une authentification au moyen de clés secrètes API. Générez et gérez vos clés depuis la Partner Console.

Les clés API constituent vos identifiants d'accès aux ressources partenaires. Chaque clé dispose d'un accès restreint à des données d'organisation spécifiques et peut être désactivée instantanément si nécessaire.

Manipulez vos clés API avec précaution : elles donnent un accès complet à votre compte ! N'exposez jamais ces clés dans des dépôts publics, des applications côté client ou tout autre endroit où elles pourraient être compromises.

Authentifiez les requêtes avec l'authentification HTTP Basic en transmettant votre clé API comme nom d'utilisateur. Laissez le mot de passe vide.

L'API n'accepte que les connexions HTTPS sécurisées. Les requêtes HTTP non chiffrées sont rejetées, de même que toute requête dépourvue d'identifiants d'authentification valides.

Liste de contrôle de mise en production

Utilisez cette liste de contrôle avant d'activer une intégration partenaire pour des installations en production.

Configuration de la Partner Console

• Votre profil de partenaire est complet.
• L'URL de votre logo, votre site web, votre catégorie et votre description sont exacts.
• Votre méthode de liaison des données est configurée : Direct Link ou Linking Identifier.
• La liaison des installations a été testée avec au moins une installation réelle.
• Le bon type de clé est utilisé :
  • Dryrun pour les tests d'écriture non destructifs.
  • Read-only pour une consommation des données en toute sécurité.
  • Live uniquement lorsque vous êtes prêt à modifier des données de production.

Authentification et gestion des clés

• Les clés secrètes sont stockées uniquement côté serveur.
• Les clés ne sont pas intégrées dans des applications côté client, des applications mobiles, des dépôts publics ou des tickets d'assistance.
• La rotation et la révocation des clés ont été testées.
• Votre équipe sait quelle clé est utilisée par chaque environnement.

Validation des données

• Les champs obligatoires sont présents pour chaque endpoint que vous appelez.
• Les identifiants d'installation correspondent à la méthode de liaison configurée.
• Les ID provenant de votre système sont stables et ne changent pas d'une synchronisation à l'autre.
• Les importations volumineuses sont divisées en lots respectant les limites documentées.
• Les éléments de lot en échec peuvent être identifiés et renvoyés.

Test des endpoints

Avant le lancement, testez chaque endpoint dont dépend votre intégration :

• Les organisations et les installations peuvent être lues.
• Les membres peuvent être enregistrés et mis à jour.
• Les formules d'abonnement, les zones d'accès et les heures d'accès se synchronisent correctement.
• Les enregistrements d'entrée sont acceptés et peuvent être rapprochés de votre système.
• Les instantanés de rapports utilisent la période de reporting et les indicateurs attendus.
• Les flux des contrôleurs de porte/portail sont testés sur du matériel réel, le cas échéant.

Préparation des Access Time Windows

Si l'intégration fournit des Access Time Windows :

• Les exemples absolus et hebdomadaires satisfont à la liste de contrôle de certification des producteurs.
• Les epochs sont des secondes Unix entières non entourées de guillemets ; les limites exactes [from, to) ont été testées.
• Les valeurs UTC par défaut, les fuseaux horaires IANA personnalisés de l'intégration et les changements d'heure d'été pertinents ont été vérifiés.
• Un flux de révisions par membre/source unique, durable et croissant coordonne les mises à jour incrémentielles, le rapprochement et les nouvelles tentatives.
• Les opérateurs comprennent les comportements en cas d'omission, de remplacement complet, d'idempotence, de conflit, d'obsolescence et de [] explicite.
• Chaque scope_key, y compris default, dispose d'une correspondance Performance Hub approuvée ; il a été vérifié que les clés inconnues entraînent un refus par défaut.
• La fréquence d'actualisation attendue de l'intégration, l'ancienneté maximale des sources, le comportement en cas de source obsolète et les alertes sont configurés.
• Il a été démontré qu'un échec de récupération en amont n'émet pas d'instantané vide ou partiel.
• La convergence du flux de staging, l'annulation/la révocation et les limites de début et de fin sur les portes physiques respectent les objectifs convenus.
• Les règles habituelles et les autorisations permanentes ont été vérifiées comme solutions de repli, et les plages ne peuvent pas contourner la désactivation d'un utilisateur, blockAllAccess, la maintenance ou le géorepérage.

Préparation du contrôle d'accès

Pour les intégrations de contrôle d'accès :

• Votre système prend la décision d'accès avant d'appeler Performance Hub.
• L'intégration gère device_offline, maintenance_mode_active et unlock_confirmation_timeout.
• Les opérateurs savent qu'un délai d'expiration signifie que le déverrouillage n'a pas été confirmé.
• Vos journaux stockent l'event_id et le command_id renvoyés.
• Vous disposez d'une procédure de repli manuelle pour le personnel de l'installation.

Gestion des erreurs et nouvelles tentatives

• Les réponses 400, 401, 403, 404, 409 et 422 sont remontées aux opérateurs ou aux équipes d'assistance au lieu d'être réessayées aveuglément.
• Les réponses 429, 500, 502, 503 et 504 utilisent une logique de nouvelles tentatives limitée avec backoff.
• Les échecs répétés déclenchent une alerte dans votre système.
• L'intégration n'abandonne jamais silencieusement les enregistrements en échec.

Observabilité

• Vos journaux incluent l'endpoint, l'horodatage, l'identifiant d'installation, l'ID de l'enregistrement source, le résultat de la requête et le corps de la réponse.
• Votre équipe d'assistance peut effectuer des recherches par ID de membre, ID d'installation, ID d'enregistrement d'entrée ou ID d'événement de déverrouillage.
• Vous disposez d'un moyen de rejouer ou de rapprocher les synchronisations en échec.

Lancement en production

• Performance Hub a confirmé votre accès en production.
• Au moins une installation en production a activé votre intégration.
• Votre clé de production est active.
• Vos contacts opérationnels et techniques sont à jour.
• Votre procédure d'assistance est documentée pour les clients.

Une fois ces vérifications terminées, votre intégration configurée apparaîtra dans l'annuaire des partenaires Performance Hub, au sein de la plateforme principale Performance Hub.

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 à :

1. Réessayer après 1 seconde.
2. Réessayer après 2 secondes.
3. Réessayer après 4 secondes.
4. 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é.

Organisations

Représente l'entité commerciale de premier niveau qui exploite une ou plusieurs installations intégrées à la plateforme Performance Hub.

L'objet Organisation

Attributs

• org_id string obligatoire

  Identifiant unique de l'organisation.

• name string obligatoire

  Nom de l'organisation.

Lister toutes les organisations

Renvoie la liste des organisations accessibles à votre compte partenaire.

Valeur renvoyée

Renvoie un objet JSON dont la propriété data contient un tableau d'objets Organisation.

Installations

Représente un lieu physique, comme un bureau, un magasin, une salle de spectacle, un campus, une clinique ou une salle de sport, où les membres peuvent accéder à des services.

L'objet installation

Attributs

• facility_id string obligatoire

  Identifiant unique de l'installation.

• org_id string obligatoire

  Identifiant unique de l'organisation parente.

• name string obligatoire

  Nom de l'installation.

• brand string facultatif

  Nom de la marque utilisée par l'installation.

• website_url string facultatif

  URL du site web de l'installation.

• place_data object facultatif

  Données de localisation issues de l'API Google Places contenant le pays, l'adresse formatée, le Google Place ID, la province et la ville.

• social_links object facultatif

  Liens vers les réseaux sociaux de l'installation.

• timezone string facultatif

  Identifiant de fuseau horaire IANA (par exemple, "Australia/Sydney", "America/New_York").

Lister toutes les installations

Renvoie la liste des installations accessibles à votre compte partenaire.

Valeur renvoyée

Renvoie un objet JSON dont la propriété data contient un tableau d'objets installation.

Formules d'abonnement

Définit une offre achetable proposée par une organisation ou une installation, y compris les services, les droits, le calendrier et les tarifs.

L'objet Membership Plan

Attributs

• membership_plan_id string obligatoire

  Identifiant unique de la formule d'abonnement.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant unique de l'installation dans Performance Hub.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Valeur d'identifiant unique que le partenaire utilise pour chaque site (par exemple, « Branch ID », « Location Code », « Store Number »). En savoir plus

• name string obligatoire

  Nom lisible de la formule (par exemple, "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").

• billing_cycle string facultatif

  Fréquence de facturation. L'une des valeurs weekly, fortnightly, monthly, annually ou one_time.

• price integer facultatif

  Coût de base dans la plus petite unité monétaire (cents pour USD/AUD).

• currency string facultatif

  Code de devise ISO 4217 (par exemple, "AUD", "USD").

• description string facultatif

  Description marketing ou interne facultative.

• active_members integer facultatif

  Nombre de membres actifs utilisant cette formule d'abonnement

• is_recurring boolean facultatif

  Indique si la formule est renouvelée automatiquement.

• is_trial boolean facultatif

  Indique s'il s'agit d'une offre d'essai.

• visible_to_public boolean facultatif

  Indique si la formule peut être achetée en libre-service.

• duration_days integer facultatif

  Nombre de jours de validité de la formule d'abonnement.

• access_zones array facultatif

  Tableau des zones d'accès incluses dans la formule d'abonnement. Chaque zone peut définir ses propres heures d'accès. Consultez Zones d'accès pour plus de détails.

• class_limit integer facultatif

  Nombre maximal de cours autorisés (null pour un nombre illimité).

Zones d'accès

Les zones d'accès définissent les espaces précis d'une installation auxquels une formule d'abonnement donne accès. Chaque zone peut avoir ses propres heures d'accès, ce qui permet d'appliquer des restrictions horaires différentes selon l'espace.

Structure

Chaque zone d'accès comprend :

• name string obligatoire

  Le nom de la zone (par exemple, « Level 3 Tenancy », « Library », « Guest Floors », « Main Gym Floor »).

• description string facultatif

  Description de ce qui est inclus dans cette zone.

• access_hours object facultatif

  Heures d'accès propres à cette zone. Consultez Heures d'accès pour le format des plages horaires.

Heures d'accès

Les heures d'accès indiquent quand les membres peuvent accéder à une zone donnée pour chaque jour de la semaine. Elles sont définies par zone d'accès, ce qui permet d'appliquer des restrictions horaires différentes aux différents espaces d'une installation.

Enregistrer une formule d'abonnement

Crée ou met à jour des fiches de formules d'abonnement. L'API détermine s'il faut créer ou mettre à jour la fiche en fonction du membership_plan_id.

Paramètres

• membership_plans array obligatoire

  Tableau d'objets Membership Plan à enregistrer. Maximum recommandé : 1000 éléments par requête pour des performances optimales. L'API regroupe automatiquement les éléments en lots pour leur traitement. Chaque élément doit inclure soit facility_id (obligatoire si vous n'utilisez pas linking_identifier), soit linking_identifier (obligatoire si vous n'utilisez pas facility_id).

Valeur renvoyée

Renvoie un message simple confirmant l'opération de synchronisation.

Membres

Représente un client individuel d'une installation. Il peut s'agir d'un lead, d'un prospect, d'un client régulier, d'un membre expiré ou d'un utilisateur bloqué.

Les upserts de membres peuvent également contenir un instantané access_time_windows complet et révisionné, comprenant des accès absolus et hebdomadaires récurrents. Consultez Access Time Windows avant de produire ces champs. Il s'agit d'autorisations supplémentaires qui ne remplacent pas les règles habituelles ni les autorisations permanentes de l'installation.

L'objet Member

Attributs

• member_id string obligatoire

  Identifiant unique du membre.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant unique de l'installation dans Performance Hub.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Valeur d'identifiant unique que le partenaire utilise pour chaque site (par exemple, « Branch ID », « Location Code », « Store Number »). En savoir plus

• first_name string obligatoire

  Prénom du membre.

• last_name string obligatoire

  Nom de famille du membre.

• email string facultatif

  Adresse e-mail.

• mobile_phone string facultatif

  Numéro de téléphone mobile au format E.123 (par exemple, "+1 415 555 2671").

• address object facultatif

  Objet d'adresse physique doté des propriétés suivantes :

  • address_line_1 (string) - Adresse principale (rue)
  • address_line_2 (string, optional) - Ligne d'adresse secondaire
  • city (string) - Nom de la ville
  • state (string) - Code de l'État/de la province
  • postal_code (string) - Code postal/ZIP
  • country (string) - Code pays ISO 3166-1 alpha-2 (par exemple, « AU », « US »)
  • country_name (string, optional) - Nom complet du pays

• date_of_birth string facultatif

  Date de naissance au format YYYY-MM-DD.

• gender string facultatif

  L'une des valeurs male, female, non_binary, prefer_not_to_say ou unknown.

• type string facultatif

  Type de membre (par exemple, staff, member, prospect).

• tags array facultatif

  Chaînes ou textes d'aide rapide permettant de classer et d'identifier des membres spécifiques (par exemple, ["vip", "personal-training", "student"]).

• membership_status string facultatif

  Statut d'adhésion actuel (par exemple, active, expired, on_hold).

• membership_plans array facultatif

  Tableau des formules d'abonnement associées au membre.

• profile_picture string facultatif

  Photo de profil encodée en Base64 (facultatif).

• created string facultatif

  Horodatage ISO 8601 de la création du membre.

• updated string facultatif

  Horodatage ISO 8601 de la dernière mise à jour du membre.

• access_time_windows array facultatif

  Instantané complet, appartenant à la source, des Access Time Windows absolues et/ou hebdomadaires récurrentes. Omettez le champ pour conserver l'instantané tel quel ; envoyez un tableau vide avec une révision plus récente pour le révoquer. Consultez Access Time Windows pour les formes, la validation, la correspondance des portées et la sémantique de remplacement.

• access_time_windows_revision integer obligatoire avec access_time_windows

  Entier non négatif, strictement croissant et compatible JSON, propre au flux de ce membre/cette source. Obligatoire dès que access_time_windows est présent.

Plages horaires d'accès

Les Access Time Windows permettent à un membre partenaire de bénéficier d'un accès temporaire ou récurrent fourni par un système externe. Cette page est le guide de référence pour les producteurs de access_time_windows et de access_time_windows_revision.

Les Access Time Windows sont des autorisations supplémentaires qui ne peuvent qu'accorder l'accès. Une plage active peut autoriser l'accès, mais une plage inactive, expirée, obsolète ou sans correspondance ne refuse pas un accès déjà autorisé par une règle habituelle ou une autorisation permanente. La désactivation d'un utilisateur, le blocage explicite d'une porte, le mode de maintenance, le géorepérage, les limites de débit et la disponibilité du contrôleur continuent de s'appliquer.

Les implémentations destinées à des systèmes en amont particuliers sont des adaptateurs distincts. Elles doivent traduire leurs données sources dans ce contrat indépendant des fournisseurs sans modifier la signification de ses champs.

Champs de l'instantané de membre

• access_time_windows array facultatif

  L'instantané complet des Access Time Windows pour ce membre et cette source partenaire. Un instantané peut combiner des plages absolute et weekly. Omettez le champ pour conserver l'instantané stocké tel quel ; envoyez [] pour révoquer toutes les plages appartenant à cette source.

• access_time_windows_revision integer obligatoire avec access_time_windows

  Un entier non négatif, strictement croissant et compatible JSON, propre au flux de révisions de ce membre/cette source. Il est obligatoire dès que access_time_windows est présent et ne doit pas dépasser 9007199254740991.

Chaque instantané accepte au maximum 50 plages. external_id, scope_key et label acceptent au maximum 120 caractères. Une plage absolue peut couvrir au maximum 90 jours. Un jour de la semaine accepte au maximum huit blocs sans chevauchement. Les données invalides sont rejetées au lieu d'être tronquées ou interprétées.

Formes des plages

Une plage absolue désigne un intervalle exact unique :

Requête mixte complète

Cette requête remplace l'instantané précédent du membre appartenant à la source par une plage absolue et une plage hebdomadaire :

Règles relatives aux heures et aux limites

from, to, active_from et active_until sont des entiers JSON exprimés en secondes Unix, qui désignent des instants UTC :

• Envoyez un entier JSON sans guillemets. Les chaînes numériques, les nombres à virgule flottante, les chaînes RFC 3339 et les millisecondes Unix sont rejetés.
• Chaque intervalle est semi-ouvert : [from, to). L'accès peut commencer exactement à from ; il n'est plus actif exactement à to.
• from doit être inférieur à to. Lorsque les deux bornes hebdomadaires sont présentes, active_from doit être inférieur à active_until.
• Ne calculez pas d'epochs à partir d'une date/heure locale sans fuseau horaire. Convertissez d'abord l'heure source en instant UTC, puis divisez les millisecondes Unix par 1000 et vérifiez que le résultat est un entier.

Fuseaux horaires et heure d'été

timezone doit être un fuseau horaire IANA valide, comme UTC, Australia/Perth ou America/New_York. Sa valeur par défaut est UTC lorsqu'il est omis.

• Plages absolues : from et to désignent déjà des instants UTC exacts. timezone n'est qu'une métadonnée d'affichage et d'audit ; la modifier ne décale jamais aucun des deux instants.
• Plages hebdomadaires : timezone définit l'heure locale et les règles d'heure d'été utilisées pour évaluer access_hours. Ne convertissez pas les blocs hebdomadaires en UTC au préalable.
• Lors du passage à l'heure d'été, une heure locale sautée par le fuseau horaire ne se produit jamais.
• Lors du retour à l'heure d'hiver, les deux instants réels correspondant à l'heure locale répétée correspondent au bloc hebdomadaire.
• active_from et active_until restent des instants UTC, même lorsqu'une plage hebdomadaire utilise un fuseau horaire autre qu'UTC.

access_hours utilise les valeurs en minuscules sun à sat. Chaque valeur est un tableau de paires [start, end] au format HH:mm sur 24 heures, complété par des zéros. Les blocs doivent être non vides, ordonnés et sans chevauchement. end est exclusif. Un bloc ne peut pas franchir minuit ; scindez un intervalle source de nuit en un bloc tardif le premier jour et un bloc matinal le jour suivant.

ID stables et correspondance des portées

external_id doit rester stable pendant toute la durée de vie d'une plage logique et être unique au sein de l'instantané du membre. Conservez-le lorsque les heures ou les libellés changent, afin que les opérateurs et les enregistrements d'audit puissent rapprocher les révisions. Ne le réutilisez pas pour une plage sans rapport.

scope_key est votre cible d'accès logique stable. Sa valeur par défaut est default. Un administrateur de l'installation associe chaque clé autorisée à des cibles Performance Hub : l'ensemble de l'installation, une porte ou une Portée d'accès :

Instantanés complets et révisions

Traitez ces deux champs comme une partition versionnée séparément au sein de l'upsert de membre :

Un instantané est complet, ce n'est pas un correctif partiel. Si la révision 1842 contient les plages A et B, alors la révision 1843 qui ne contient que B supprime A.

Maintenez un flux de révisions coordonné unique par partenaire/membre pour l'ensemble des processus de webhook, d'interrogation périodique, de relecture et de rapprochement complet. Une séquence de base de données durable est préférable. Une valeur en millisecondes Unix ne peut servir de révision que si tous les processus d'écriture se coordonnent et garantissent un ordre strict et l'unicité ; il s'agit d'une valeur de révision, et non d'un champ d'epoch.

Conservez la requête et la révision exactes jusqu'à ce que la réponse de l'API soit connue. Après un délai d'expiration ou une erreur temporaire, renvoyez le même instantané normalisé avec la même révision. N'attribuez pas une nouvelle révision au seul motif que la livraison est incertaine.

Annulation, expiration et échecs en amont

• Annuler une plage : récupérez avec succès l'état de référence de la source, supprimez cette plage et envoyez l'instantané complet restant avec une révision plus récente.
• Annuler toutes les plages : envoyez access_time_windows: [] avec une révision plus récente.
• Laisser expirer une plage absolue : elle cesse d'autoriser l'accès à to ; envoyez ultérieurement un rapprochement sans l'entrée expirée pour garder des instantanés propres.
• Mettre fin à une plage hebdomadaire : supprimez-la dans un instantané plus récent, ou utilisez active_until lorsque la source connaît l'instant de fin.
• La récupération depuis la source échoue ou est incomplète : n'envoyez pas [] et ne publiez pas d'instantané partiel. Déclenchez une alerte et relancez la récupération. Transformer un échec en amont en instantané vide revient à révoquer l'accès involontairement.
• La requête Partner API échoue à la validation : corrigez les données et n'envoyez une révision plus récente que si l'instantané normalisé change. Relancez les échecs temporaires avec la révision d'origine.

La fraîcheur des sources est configurée pour chaque intégration en fonction de la fréquence de livraison et de rapprochement qu'elle garantit. Avant l'activation, convenez de l'ancienneté maximale des sources, de ce qui se passe lorsqu'elle est dépassée, des seuils d'alerte et de la possibilité pour les opérateurs d'accepter de ne s'appuyer que sur les bornes propres à chaque plage. Une plage provenant d'une source obsolète ne devient jamais une règle de refus ; les règles habituelles et les autorisations permanentes restent des solutions de repli.

Algorithme du producteur

Utilisez cette procédure indépendante du langage pour chaque mise à jour de membre :

Liste de contrôle de certification

Effectuez ces vérifications dans une installation de staging en utilisant la correspondance scope_key définitive :

• Une plage absolue sans fuseau horaire est acceptée et évaluée en UTC.
• Une plage absolue avec un fuseau IANA personnalisé conserve les mêmes instants from/to.
• Une plage hebdomadaire avec un fuseau IANA personnalisé suit l'heure locale lors du passage à l'heure d'été et du retour à l'heure d'hiver.
• Un instantané mixte absolu/hebdomadaire remplace entièrement l'instantané précédent.
• L'accès commence exactement à from et s'arrête exactement à to ; les fins de blocs hebdomadaires sont également exclusives.
• La modification des heures sous le même external_id avec une révision plus récente prend effet.
• L'omission de access_time_windows modifie les autres champs du membre sans modifier les plages.
• La relecture de la même révision/charge utile est idempotente.
• La même révision avec une charge utile différente renvoie un conflit et ne modifie pas l'instantané.
• Une révision plus ancienne reçue dans le désordre est signalée comme obsolète et ne peut pas rétablir un état antérieur.
• Un [] plus récent révoque les plages appartenant à la source ; un échec de récupération en amont n'envoie rien.
• Un scope_key inconnu ou sans correspondance entraîne un refus par défaut et génère un avertissement visible par les opérateurs.
• Les alertes d'ancienneté des sources et la politique configurée pour les sources obsolètes fonctionnent au seuil convenu.
• Les chemins de webhook et de rapprochement complet convergent vers le même instantané et le même ordre de révisions.
• La livraison du flux atteint Door & Gate Access dans le délai convenu.
• Une plage active peut autoriser l'accès à la porte physique associée, mais ne peut pas contourner la désactivation d'un utilisateur, blockAllAccess, la maintenance ou le géorepérage.
• Avant, en dehors et après une plage, les règles habituelles et les autorisations permanentes continuent d'autoriser les utilisateurs qui remplissent par ailleurs les conditions.

Ressources associées

• L'objet Member
• Enregistrer un membre
• Bonnes pratiques
• Erreurs
• Liste de contrôle de mise en production

Enregistrer un membre

Crée ou met à jour des fiches de membres. L'API détermine s'il faut créer ou mettre à jour la fiche en fonction du member_id.

Paramètres

• members array obligatoire

  Tableau d'objets Member à enregistrer. Maximum recommandé : 1000 éléments par requête pour des performances optimales. L'API regroupe automatiquement les éléments en lots pour leur traitement. Chaque élément doit inclure soit facility_id (obligatoire si vous n'utilisez pas linking_identifier), soit linking_identifier (obligatoire si vous n'utilisez pas facility_id).

  Lorsqu'un membre inclut access_time_windows, il doit également inclure access_time_windows_revision. Le tableau est un instantané complet de la source, et non un correctif partiel. Omettez-le pour conserver l'instantané existant, ou envoyez [] avec une révision plus récente pour révoquer toutes les plages appartenant à la source. Lisez le guide des Access Time Windows avant d'activer ce champ.

Valeur renvoyée

Renvoie un message simple confirmant l'opération de synchronisation.

Les champs du profil du membre restent des upserts normaux, même lorsqu'un instantané de plages est signalé comme une relecture idempotente ou ignoré car obsolète. Un instantané en conflit (même révision, charge utile différente) ne peut pas être renvoyé tel quel ; rapprochez l'état de la source et envoyez une révision plus récente.

Enregistrements d'entrée

Représente l'enregistrement de la présence d'une personne dans une installation, à un cours ou à une activité. Utilisé pour le suivi de la fréquentation, l'analyse de l'utilisation et l'amélioration de la précision de la détection visuelle.

L'objet Check-In

Attributs

• check_in_id string facultatif

  Identifiant unique de l'enregistrement d'entrée. Facultatif : généré automatiquement à partir de la paire member_id et timestamp s'il n'est pas fourni.

• member_id string obligatoire

  Identifiant unique du membre.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant unique de l'installation dans Performance Hub.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Valeur d'identifiant unique que le partenaire utilise pour chaque site (par exemple, « Branch ID », « Location Code », « Store Number »). En savoir plus

• check_in_type string facultatif

  Type de visite. L'une des valeurs member, class, staff, guest ou trial.

• source string facultatif

  Mode de saisie de l'enregistrement d'entrée. Les valeurs courantes sont manual, tag, rfid, kiosk, app. D'autres valeurs comme door_reader ou booking peuvent également être utilisées.

• class_id string facultatif

  Facultatif. À renseigner si l'enregistrement est lié à une réservation ou à une participation à un cours.

• timestamp string obligatoire

  Horodatage au format ISO 8601 du moment où l'enregistrement d'entrée a eu lieu.

Enregistrer des entrées

Crée des enregistrements d'entrée. L'API dédoublonne automatiquement les enregistrements en fonction du membre, de l'installation et de l'horodatage.

Paramètres

• check_ins array obligatoire

  Tableau d'objets Check-In à enregistrer. Maximum recommandé : 1000 éléments par requête pour des performances optimales. L'API regroupe automatiquement les éléments en lots pour leur traitement. Chaque élément doit inclure soit facility_id (obligatoire si vous n'utilisez pas linking_identifier), soit linking_identifier (obligatoire si vous n'utilisez pas facility_id).

Valeur renvoyée

Renvoie un message simple confirmant l'opération de synchronisation.

Contrôle d'accès

La Partner API peut déclencher le matériel de contrôleur de porte/portail Performance Hub pour les installations où votre intégration est activée.

Utilisez cette API lorsque votre système de gestion des membres a déjà décidé qu'une personne est autorisée à entrer. Performance Hub n'évalue pas le statut d'adhésion, les heures d'accès, les règles de zones de portes, les contrôles antifraude ni la logique de suspension. Votre système reste l'autorité pour ces décisions.

La requête de déverrouillage est synchrone. Performance Hub envoie la commande au contrôleur sur site en temps réel et ne renvoie 200 qu'après que l'appareil a confirmé le déverrouillage physique du relais. La plupart des confirmations devraient aboutir en 3 à 5 secondes. Si aucune confirmation n'est reçue dans le délai imparti, l'API renvoie un échec explicite.

Vous pouvez également enregistrer une tentative d'accès ou un refus qui n'a jamais atteint le contrôleur. Cet appel ne déverrouille pas la porte. Il écrit un événement dans les Journaux d'accès de Door & Gate Access.

L'objet contrôleur de porte/portail

Attributs

• door_id string obligatoire

  Identifiant unique du contrôleur de porte/portail. Stockez-le dans votre système après la découverte et utilisez-le lorsque vous appelez l'endpoint de déverrouillage.

• facility_id string obligatoire

  ID d'installation Performance Hub.

• linking_identifier string facultatif

  Identifiant d'installation du partenaire lorsque votre intégration utilise des identifiants de liaison. En savoir plus

• name string obligatoire

  Nom lisible de l'appareil configuré dans Performance Hub.

• zone string facultatif

  Zone ou emplacement de la porte, par exemple Entrance.

• status string obligatoire

  online ou offline.

• relay_state string facultatif

  Dernier état connu du relais, par exemple locked ou unlocked.

• maintenance_mode string obligatoire

  Mode de maintenance actuel. L'une des valeurs off, force-open ou force-closed.

• hold_time_seconds integer obligatoire

  Durée de maintien du déverrouillage configurée par défaut pour la porte.

• last_seen string facultatif

  Horodatage ISO de la dernière mise à jour des métadonnées de l'appareil.

Lister les contrôleurs de porte/portail

Renvoie les contrôleurs de porte/portail disponibles pour votre intégration.

Si ni facility_id ni linking_identifier n'est fourni, l'API renvoie les contrôleurs de porte/portail de toutes les installations liées à votre compte partenaire.

Paramètres

• facility_id string facultatif l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  ID d'installation Performance Hub. À utiliser pour les intégrations à liaison directe.

• linking_identifier string facultatif l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Votre propre identifiant d'installation/de site. À utiliser lorsque votre intégration est configurée pour les identifiants de liaison.

Valeur renvoyée

Renvoie un tableau d'objets contrôleur de porte/portail.

Obtenir l'état d'un contrôleur de porte/portail

Récupère le dernier état connu et la configuration de base d'un contrôleur de porte/portail.

Fournissez un identifiant d'installation afin que Performance Hub puisse vérifier que la porte appartient à une installation à laquelle votre intégration a accès.

Paramètres

• door_id string obligatoire

  ID du contrôleur de porte/portail renvoyé par l'endpoint de liste.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  ID d'installation Performance Hub. Obligatoire pour les intégrations à liaison directe.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant d'installation du partenaire. Obligatoire pour les intégrations à identifiant de liaison.

Valeur renvoyée

Renvoie un objet contrôleur de porte/portail.

Déverrouiller un contrôleur de porte/portail

Envoie une commande de déverrouillage au contrôleur de porte/portail et attend que le relais physique confirme le déverrouillage.

Votre système doit décider si la personne est autorisée avant d'appeler cet endpoint. Performance Hub vérifie uniquement la clé partenaire, l'accès à l'installation, l'appartenance de la porte et l'état de l'appareil.

Paramètres

• door_id string obligatoire

  ID du contrôleur de porte/portail renvoyé par l'endpoint de liste.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  ID d'installation Performance Hub. Obligatoire pour les intégrations à liaison directe.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant d'installation du partenaire. Obligatoire pour les intégrations à identifiant de liaison.

• member_id string obligatoire

  ID du membre chez le partenaire. Utilisé pour la journalisation d'audit et la liaison ultérieure des données.

• first_name string obligatoire

  Prénom de la personne qui ouvre la porte.

• last_name string obligatoire

  Nom de famille de la personne qui ouvre la porte.

• full_name string facultatif

  Facultatif. S'il est omis, Performance Hub combine first_name et last_name.

• check_in_id string facultatif

  ID d'enregistrement d'entrée facultatif provenant de votre système, pour la corrélation.

• idempotency_key string facultatif

  Clé facultative de protection contre la relecture. 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.

Valeur renvoyée

Renvoie 200 uniquement lorsque l'appareil confirme le déverrouillage physique du relais. La porte utilise la durée de maintien configurée dans Gestion d'appareils de Performance Hub ; les partenaires ne peuvent pas modifier la temporisation du relais pour chaque requête. La plupart des confirmations devraient aboutir en 3 à 5 secondes. Considérez le délai d'expiration documenté comme un échec explicite du déverrouillage et ne réessayez que conformément à vos propres règles de sécurité.

Échecs courants :

• 403 integration_not_enabled - votre intégration n'est pas activée pour l'installation.
• 409 maintenance_mode_active - le personnel de l'installation a activé le mode de maintenance pour la porte.
• 503 device_offline - le contrôleur de porte/portail est hors ligne ou ses données sont obsolètes.
• 504 unlock_confirmation_timeout - la commande a été envoyée, mais aucune confirmation correspondante n'a été reçue avant l'expiration du délai.

Enregistrer une tentative d'accès ou un refus

Enregistre une tentative d'accès ou un refus déjà décidé par votre système. Le contrôleur de porte/portail n'est pas contacté et la porte ne se déverrouille pas.

Utilisez cet endpoint lorsque votre système refuse l'entrée, ou lorsqu'une tentative doit apparaître dans les Journaux d'accès de Door & Gate Access sans déverrouillage. Performance Hub n'évalue pas le statut d'adhésion, les heures d'accès ni les autres règles d'accès.

Un événement refusé apparaît dans les Journaux d'accès de Door & Gate Access avec le résultat Denied, le nom de votre entreprise partenaire, la porte, l'identifiant du membre lorsque vous en envoyez un, et le code de motif sous une forme lisible. Par exemple, membership_expired s'affiche sous la forme « Membership Expired ». reason_display_text et user_email sont stockés avec l'événement.

Paramètres

• door_id string obligatoire

  ID du contrôleur de porte/portail renvoyé par l'endpoint de liste.

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  ID d'installation Performance Hub. Obligatoire pour les intégrations à liaison directe.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant d'installation du partenaire. Obligatoire pour les intégrations à identifiant de liaison.

• outcome string obligatoire

  denied ou attempted.

• reason string facultatif

  Code de motif en snake_case minuscule, 64 caractères maximum. Obligatoire lorsque outcome vaut denied. Exemple : membership_expired.

• reason_display_text string facultatif

  Motif lisible, 256 caractères maximum. Exemple : Membership expired on 2026-04-01.

• member_id string facultatif

  ID du membre chez le partenaire. Omettez-le lorsque l'identifiant d'accès ne correspond à aucun membre, par exemple une carte inconnue.

• user_email string facultatif

  Adresse e-mail de la personne qui a tenté d'accéder.

• timestamp string facultatif

  Moment de la tentative, au format ISO 8601 avec fuseau horaire. Exemple : 2026-05-18T10:15:30Z. Par défaut, l'heure de réception de la requête. Ne doit pas être située plus de 5 minutes dans le futur ni dater de plus de 30 jours.

• idempotency_key string facultatif

  Clé de protection contre la relecture, 128 caractères maximum. Réutiliser la même clé pour le même partenaire, la même installation et la même porte renvoie le résultat d'origine.

Valeur renvoyée

Renvoie 201 lorsque l'événement est enregistré. Rejouer la même idempotency_key renvoie 200 avec idempotent défini sur true et ne crée pas de nouvel événement.

Une clé dry-run renvoie 200 avec dry_run défini sur true. Rien n'est enregistré.

Échecs courants :

• 400 - le corps est invalide, un refus n'a pas de reason, l'horodatage est hors plage, ou facility_id / linking_identifier ne correspond à aucune installation liée.
• 403 - la clé est en lecture seule.
• 403 integration_not_enabled - votre intégration n'est pas activée pour l'installation. message en indique la raison.
• 404 - le contrôleur de porte/portail est introuvable pour l'installation liée.

Rapports d'installation

Un enregistrement ponctuel qui capture les principaux indicateurs opérationnels et financiers d'une installation pour une période donnée.

L'objet Report Snapshot

Attributs

• facility_id string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Identifiant unique de l'installation dans Performance Hub.

• linking_identifier string l'un ou l'autreIndiquez le type d'identifiant d'installation configuré pour votre intégration : utilisez facility_id pour les intégrations à liaison directe, ou linking_identifier pour les intégrations à identifiant de liaison. N'envoyez pas les deux ; l'API utilise le type d'identifiant configuré pour votre compte partenaire et ignore l'autre. En savoir plus

  Valeur d'identifiant unique que le partenaire utilise pour chaque site (par exemple, « Branch ID », « Location Code », « Store Number »). En savoir plus

• start_date string obligatoire

  Date de début de la période de l'instantané au format YYYY-MM-DD.

• end_date string obligatoire

  Date de fin de la période de l'instantané au format YYYY-MM-DD.

• metrics object obligatoire

  Objet d'indicateurs contenant les données sur les membres et le chiffre d'affaires pour la période.

Enregistrer des instantanés de rapports

Soumet les indicateurs opérationnels et financiers d'une installation pour une période donnée.

Paramètres

• snapshots array obligatoire

  Tableau d'objets Report Snapshot à enregistrer. 25 éléments maximum par requête. Chaque élément doit inclure soit facility_id (obligatoire si vous n'utilisez pas linking_identifier), soit linking_identifier (obligatoire si vous n'utilisez pas facility_id).

Valeur renvoyée

Renvoie un message simple confirmant l'opération de synchronisation.

Erreurs

La Partner API utilise des codes de statut HTTP standard et des corps de réponse JSON pour expliquer pourquoi une requête a échoué.

Structure des réponses d'erreur

La plupart des erreurs de l'API renvoient un corps JSON contenant un message et, le cas échéant, des détails structurés.

Codes de statut

Échecs liés aux Access Time Windows

La validation des plages échoue avant l'écriture de l'instantané invalide. Les causes courantes qui ne justifient pas une nouvelle tentative sont notamment :

• L'absence de access_time_windows_revision lorsque access_time_windows est présent.
• Des valeurs d'epoch sous forme de chaîne, de nombre à virgule flottante ou probablement exprimées en millisecondes.
• Un fuseau horaire IANA invalide, un intervalle inversé, un external_id en double, des blocs hebdomadaires qui se chevauchent ou un bloc de nuit qui n'a pas été scindé.
• Une valeur qui dépasse les limites documentées de nombre, de longueur ou d'étendue.

Une révision répétée avec un contenu normalisé différent renvoie une erreur 409 Conflict. Effectuez un rapprochement avec le dernier état de référence et attribuez une révision plus récente ; ne continuez pas à réessayer la paire en conflit. Une révision plus ancienne est signalée comme un instantané obsolète ignoré au lieu d'être autorisée à écraser un état plus récent. Un scope_key inconnu ou sans correspondance entraîne un refus d'autorisation par défaut et doit être traité comme une alerte de configuration.

Si la livraison expire ou reçoit une erreur 5xx temporaire, renvoyez exactement le même instantané normalisé avec la même révision. Si la récupération depuis la source en amont a échoué, omettez entièrement le champ des plages ; ne le remplacez jamais par un tableau vide.

Recommandations pour les nouvelles tentatives

Réessayez les codes suivants avec un backoff exponentiel limité :

• 429
• 500
• 502
• 503
• 504

Ne réessayez pas aveuglément les codes suivants :

• 400
• 401
• 403
• 404
• 409
• 422

Pour le contrôle d'accès, considérez toujours les réponses d'expiration de délai et d'appareil hors ligne comme des déverrouillages en échec, sauf si vos propres règles d'accès et processus de sécurité en disposent autrement.

Informations à fournir à l'assistance

Lorsque vous contactez l'assistance, indiquez :

• L'endpoint et la méthode HTTP.
• L'horodatage et le fuseau horaire.
• L'ID de la clé partenaire, et non la clé secrète.
• L'identifiant d'installation utilisé.
• L'ID de l'enregistrement source dans votre système.
• Le statut et le corps de la réponse.
• L'event_id ou le command_id, le cas échéant.

Gestion des versions

La version de la Partner API est indiquée dans l'URL. La version actuelle est :

Politique de modification

Performance Hub s'efforce, dans la mesure du possible, d'apporter des modifications additives et rétrocompatibles.

Exemples de modifications rétrocompatibles :

• L'ajout d'un nouveau champ facultatif à une requête.
• L'ajout d'un nouveau champ à une réponse.
• L'ajout d'un nouvel endpoint.
• L'ajout d'une nouvelle valeur d'énumération lorsque les clients sont censés gérer les valeurs inconnues.
• L'amélioration des messages de validation sans modifier le contrat des codes de statut.

access_time_windows et access_time_windows_revision sont des champs additifs des requêtes Member. Les clients existants qui les omettent conservent tel quel l'instantané des Access Time Windows stocké. Cette règle d'omission préserve la compatibilité des upserts partiels ; l'omission n'équivaut pas à l'envoi d'un tableau vide.

Exemples de modifications non rétrocompatibles :

• La suppression ou le renommage d'un champ.
• La modification du type d'un champ.
• Le passage d'un champ de requête facultatif à obligatoire.
• La suppression d'un endpoint.
• La modification de la signification d'un code de statut existant ou d'un reason propre à un domaine.

Obsolescences

Lorsqu'une modification non rétrocompatible est nécessaire, Performance Hub évite, dans la mesure du possible, de modifier la version existante en place. Nous introduisons plutôt une nouvelle version ou un chemin de migration et communiquons la modification aux partenaires concernés.

Les avis d'obsolescence peuvent prendre la forme de :

• Une entrée dans le journal des modifications.
• Une communication directe aux partenaires.
• Des notes dans la Partner Console.
• Des conseils de migration dans la documentation.

Recommandations pour les clients

Concevez des clients qui tolèrent les modifications additives :

• Ignorez les champs de réponse que vous n'utilisez pas.
• Traitez les valeurs d'énumération inconnues comme non prises en charge au lieu de provoquer un plantage.
• Évitez les contrôles d'égalité stricts sur les réponses.
• Journalisez les valeurs non reconnues afin de pouvoir mettre à jour votre intégration de façon délibérée.

Pour les partitions Member révisionnées telles que les Access Time Windows, conservez la révision soumise et la charge utile normalisée jusqu'à ce que le résultat soit connu. Réutiliser une révision pour un contenu modifié constitue un conflit, tandis que rejouer le même contenu est idempotent. Consultez Access Time Windows.

Spécifications OpenAPI

Utilisez les spécifications OpenAPI publiées pour générer des clients, valider les requêtes et suivre l'évolution de la structure de l'API au fil du temps.

Consultez Spécifications OpenAPI.

Journal des modifications

Ce journal des modifications recense les changements notables de la Partner API et de la Partner Console qui affectent le comportement des intégrations.

2026-09-09

2026-05-06

2026-05-01

Catégories de modifications

Les prochaines entrées utiliseront ces catégories :

• Ajouts - nouvel endpoint, champ, guide ou fonctionnalité.
• Modifications - comportement ou documentation modifiés sans suppression de la prise en charge.
• Obsolescences - fonctionnalité toujours disponible, mais faisant l'objet d'un plan de migration.
• Suppressions - fonctionnalité ou endpoint supprimé.
• Corrections - correction de bug ou de documentation.
• Sécurité - modification touchant l'authentification, les autorisations, le traitement des données ou la gestion des clés.