Einführung

Die Partner API des Performance Hub ermöglicht es externen Partnerplattformen, sich nahtlos in die Kernmodule des Performance Hub zu integrieren. Die API unterstützt Computer Vision, Analysen, die Protokollierung des Mitgliederzutritts und Einblicke in Einrichtungen.

Anfrageformat

Die API akzeptiert JSON-codierte Anfragetexte und gibt JSON-codierte Antworten zurück.

Ratenbegrenzung

Um eine faire Nutzung und die Systemstabilität sicherzustellen, gelten für Partner API-Konten zu Beginn folgende Standardgrenzen:

• 5 Anfragen pro Sekunde pro Endpunkt
• Empfohlen: maximal 1000 Elemente pro Batch-Anfrage für optimale Leistung
• Maximal 10MB Payload-Größe

Ratenbegrenzungen sind anpassbar und können von Ihrem Partner Account Manager beim Performance Hub im Einzelfall konfiguriert werden. Wenn Ihre Integration für den Launch, Migrationen, Nachbefüllungen von Berichtsdaten oder Einrichtungen mit hohem Volumen einen höheren Durchsatz benötigt, sprechen Sie dies während des Onboardings oder vor dem geplanten Änderungsfenster an.

Authentifizierung

Der Zugriff auf die Partner API erfordert eine Authentifizierung mit geheimen API-Schlüsseln. Erstellen und verwalten Sie Ihre Schlüssel über die Partner Console.

API-Schlüssel dienen als Ihre Anmeldedaten für den Zugriff auf Partnerressourcen. Jeder Schlüssel hat eingeschränkten Zugriff auf bestimmte Organisationsdaten und kann bei Bedarf sofort deaktiviert werden.

Gehen Sie sorgfältig mit Ihren API-Schlüsseln um – sie gewähren vollen Zugriff auf Ihr Konto! Legen Sie diese Schlüssel niemals in öffentlichen Repositorys, clientseitigen Anwendungen oder an anderen Stellen offen, an denen sie kompromittiert werden könnten.

Authentifizieren Sie Anfragen per HTTP Basic Auth, indem Sie Ihren API-Schlüssel als Benutzernamen übergeben. Lassen Sie das Passwort leer.

Die API akzeptiert ausschließlich sichere HTTPS-Verbindungen. Einfache HTTP-Anfragen werden abgelehnt, ebenso alle Anfragen ohne gültige Anmeldedaten.

Go-live-Checkliste

Gehen Sie diese Checkliste durch, bevor Sie eine Partnerintegration für Einrichtungen in der Produktion aktivieren.

Einrichtung der Partner Console

• Ihr Partnerprofil ist vollständig.
• Logo-URL, Website, Kategorie und Beschreibung sind korrekt.
• Ihre Datenverknüpfungsmethode ist konfiguriert: Direct Link oder Linking Identifier.
• Die Verknüpfung mit Einrichtungen wurde mit mindestens einer echten Einrichtung getestet.
• Der richtige Schlüsseltyp wird verwendet:
  • Dryrun für zerstörungsfreie Schreibtests.
  • Read-only für die sichere Datennutzung.
  • Live erst, wenn Sie bereit sind, Produktionsdaten zu verändern.

Authentifizierung und Schlüsselverwaltung

• Geheime Schlüssel werden ausschließlich serverseitig gespeichert.
• Schlüssel sind nicht in clientseitige Anwendungen, mobile Apps, öffentliche Repositorys oder Support-Tickets eingebettet.
• Rotation und Widerruf von Schlüsseln wurden getestet.
• Ihr Team weiß, welcher Schlüssel in welcher Umgebung verwendet wird.

Datenvalidierung

• Für jeden aufgerufenen Endpunkt sind die erforderlichen Felder vorhanden.
• Die Einrichtungskennungen entsprechen Ihrer konfigurierten Verknüpfungsmethode.
• Die IDs aus Ihrem System sind stabil und ändern sich zwischen Synchronisierungen nicht.
• Große Importe werden in Batches innerhalb der dokumentierten Grenzen aufgeteilt.
• Fehlgeschlagene Batch-Elemente können identifiziert und erneut gesendet werden.

Endpunkttests

Testen Sie vor dem Launch jeden Endpunkt, von dem Ihre Integration abhängt:

• Organisationen und Einrichtungen können gelesen werden.
• Mitglieder können gespeichert und aktualisiert werden.
• Mitgliedschaftstarife, Zutrittszonen und Zutrittszeiten werden korrekt synchronisiert.
• Check-ins werden akzeptiert und können Ihrem System zugeordnet werden.
• Berichts-Snapshots verwenden den erwarteten Berichtszeitraum und die erwarteten Kennzahlen.
• Abläufe mit dem Door/Gate Controller werden, sofern zutreffend, mit echter Hardware getestet.

Bereitschaft für Access Time Windows

Wenn die Integration Access Time Windows liefert:

• Absolute und wöchentliche Beispiele bestehen die Zertifizierungscheckliste für Producer.
• Epoch-Werte sind ganzzahlige Unix-Sekunden ohne Anführungszeichen; exakte [from, to)-Grenzen wurden getestet.
• UTC-Standardwerte, die benutzerdefinierten IANA-Zeitzonen der Integration und relevante Sommerzeitumstellungen wurden überprüft.
• Ein einziger dauerhafter, monotoner Revisionsstrom pro Mitglied und Quelle koordiniert inkrementelle Aktualisierungen, Abgleiche und Wiederholungen.
• Die Betreiber verstehen das Verhalten bei weggelassenen Werten, vollständigem Ersatz, idempotenten, widersprüchlichen und veralteten Snapshots sowie bei explizitem [].
• Jeder scope_key, einschließlich default, hat eine genehmigte Zuordnung im Performance Hub; es wurde getestet, dass unbekannte Schlüssel zur Verweigerung führen (fail closed).
• Die erwartete Aktualisierungsfrequenz der Integration, das maximale Alter der Quelldaten, das Verhalten bei veralteten Quellen und Warnungen sind konfiguriert.
• Es wurde nachgewiesen, dass ein fehlgeschlagener Abruf aus der Quelle keinen leeren oder unvollständigen Snapshot erzeugt.
• Konvergenz des Stage-Stroms, Stornierung/Widerruf sowie Start- und Endgrenzen an der physischen Tür erfüllen die vereinbarten Ziele.
• Reguläre Regeln und dauerhafte Berechtigungen wurden als Fallback-Pfade überprüft, und Zeitfenster können weder die Deaktivierung von Benutzern, blockAllAccess, die Wartung noch das Geofencing umgehen.

Bereitschaft für die Zutrittskontrolle

Für Integrationen zur Zutrittskontrolle:

• Ihr System trifft die Zutrittsentscheidung, bevor es den Performance Hub aufruft.
• Die Integration verarbeitet device_offline, maintenance_mode_active und unlock_confirmation_timeout.
• Die Betreiber wissen, dass eine Zeitüberschreitung bedeutet, dass die Entriegelung nicht bestätigt wurde.
• Ihre Protokolle speichern die zurückgegebenen Werte event_id und command_id.
• Sie haben einen manuellen Ausweichprozess für das Personal der Einrichtung.

Fehlerbehandlung und Wiederholungen

• Antworten mit 400, 401, 403, 404, 409 und 422 werden den Betreibern oder Support-Teams angezeigt, statt ungeprüft wiederholt zu werden.
• Bei Antworten mit 429, 500, 502, 503 und 504 wird eine begrenzte Wiederholungslogik mit Backoff verwendet.
• Wiederholte Fehler lösen in Ihrem System eine Warnung aus.
• Die Integration verwirft fehlgeschlagene Datensätze niemals stillschweigend.

Beobachtbarkeit

• Ihre Protokolle enthalten Endpunkt, Zeitstempel, Einrichtungskennung, Quelldatensatz-ID, Ergebnis der Anfrage und Antworttext.
• Ihr Support-Team kann nach Mitglieds-ID, Einrichtungs-ID, Check-in-ID oder ID des Entriegelungsereignisses suchen.
• Sie haben eine Möglichkeit, fehlgeschlagene Synchronisierungen erneut auszuführen oder abzugleichen.

Produktionsstart

• Der Performance Hub hat Ihren Produktionszugang bestätigt.
• Mindestens eine Einrichtung in der Produktion hat Ihre Integration aktiviert.
• Ihr Produktionsschlüssel ist aktiv.
• Ihre betrieblichen und technischen Ansprechpartner sind aktuell.
• Ihr Support-Prozess ist für Kunden dokumentiert.

Nachdem diese Prüfungen abgeschlossen sind, erscheint Ihre konfigurierte Integration im Partnerverzeichnis des Performance Hub innerhalb der zentralen Performance Hub-Plattform.

Bewährte Methoden

Mit diesen Mustern bleiben Partnerintegrationen vorhersehbar, nachvollziehbar und sicher für Einrichtungen.

Einrichtungen einheitlich identifizieren

Wählen Sie die für Ihr Partnerkonto konfigurierte Verknüpfungsmethode und verwenden Sie sie durchgängig:

• Direct Link - Verwenden Sie die vom Einrichtungs-Endpunkt zurückgegebene facility_id des Performance Hub.
• Linking Identifier - Verwenden Sie Ihre eigene Standortkennung, etwa eine Filial-ID, einen Standortcode oder eine Filialnummer.

Senden Sie nicht beide Kennungen in derselben Anfrage. Der Performance Hub löst Anfragen anhand der für Ihr Partnerkonto konfigurierten Verknüpfungsmethode auf.

Hinweise zur Einrichtung finden Sie unter Partner-Verknüpfungsmethoden.

Batch-Schreibvorgänge mit Bedacht

Die Partner API akzeptiert JSON-Anfragetexte und ist, wo dokumentiert, für batchorientierte Synchronisierungsabläufe ausgelegt. Halten Sie Batches begrenzt und wiederholbar.

Standardrichtwerte:

• Verwenden Sie für optimale Leistung bis zu 1000 Elemente pro Batch-Anfrage.
• Halten Sie Payloads unter 10MB.
• Bleiben Sie innerhalb von 5 Anfragen pro Sekunde pro Endpunkt.

Ratenbegrenzungen sind anpassbar und können von Ihrem Partner Account Manager beim Performance Hub im Einzelfall konfiguriert werden. Wenn Sie umfangreiche Importe, Launch-Traffic oder Nachbefüllungen von Berichtsdaten erwarten, vereinbaren Sie den benötigten Durchsatz vor dem Änderungsfenster.

Wenn Sie einen großen Datensatz synchronisieren müssen, teilen Sie ihn in deterministische Blöcke auf und protokollieren Sie die ID jedes Blocks auf Ihrer Seite. So lassen sich fehlgeschlagene Wiederholungsversuche leichter nachvollziehen.

Sicher wiederholen

Verwenden Sie exponentiellen Backoff bei vorübergehenden Fehlern wie 429, 500, 502, 503 und 504.

Vermeiden Sie enge Wiederholungsschleifen. Ein guter Ausgangspunkt ist:

1. Nach 1 Sekunde wiederholen.
2. Nach 2 Sekunden wiederholen.
3. Nach 4 Sekunden wiederholen.
4. Abbrechen und alarmieren, wenn der Vorgang weiterhin fehlschlägt.

Korrigieren Sie bei Validierungsfehlern wie 400 oder 422 die Anfrage, bevor Sie sie wiederholen.

Idempotenz nutzen, wo unterstützt

Der Entriegelungs-Endpunkt des Door/Gate Controller unterstützt einen optionalen idempotency_key. Wird derselbe Schlüssel für denselben Partner, dieselbe Einrichtung und dieselbe Tür erneut verwendet, wird das vorhandene Ergebnis zurückgegeben, sofern eines verfügbar ist.

Verwenden Sie einen stabilen Schlüssel für die ausgeführte Aktion, zum Beispiel eine Check-in-ID oder eine Zutrittsereignis-ID aus Ihrem System.

Gehen Sie nicht davon aus, dass jeder Schreib-Endpunkt Idempotenz unterstützt, sofern dies nicht für den jeweiligen Endpunkt dokumentiert ist.

Quelldaten sauber halten

Senden Sie nach Möglichkeit stabile, normalisierte Werte:

• Verwenden Sie einheitliche Mitglieder-, Tarif-, Einrichtungs- und Check-in-IDs aus Ihrem Quellsystem.
• Verwenden Sie ISO 8601-Zeitstempel für Datums- und Zeitangaben.
• Senden Sie Telefonnummern, sofern verfügbar, im internationalen Format.
• Senden Sie Währungen über die für jeden Endpunkt dokumentierten Felder.
• Überladen Sie Freitextfelder nicht mit Daten, die in strukturierte Felder gehören.

Für inkrementelle und vollständige Synchronisierungen planen

Die meisten Partnerintegrationen benötigen beides:

• Inkrementelle Synchronisierungen für tägliche Änderungen.
• Vollständige Abgleichssynchronisierungen, um verpasste Ereignisse, historische Importe oder Datenabweichungen zu korrigieren.

Ihre Integration sollte den aktuellen Zustand eines Mitglieds, eines Mitgliedschaftstarifs oder eines Berichts-Snapshots erneut senden können, ohne davon abzuhängen, dass eine vorherige Anfrage erfolgreich war.

Access Time Windows sicher veröffentlichen

Behandeln Sie den Wert access_time_windows jedes Mitglieds als vollständigen, unabhängig revisionierten Snapshot:

• Koordinieren Sie einen einzigen, monoton steigenden access_time_windows_revision-Strom über inkrementelle und Abgleichs-Worker hinweg.
• Wiederholen Sie eine unsichere oder vorübergehend fehlgeschlagene Zustellung mit derselben Revision und derselben normalisierten Payload.
• Lassen Sie access_time_windows weg, wenn Sie den Wert nicht aktualisieren.
• Senden Sie [] erst, nachdem ein erfolgreicher Abruf aus der maßgeblichen Quelle belegt, dass keine Zeitfenster mehr bestehen. Machen Sie aus einer Zeitüberschreitung, einem Teilergebnis oder einem Parsing-Fehler der Quelle niemals einen Widerruf.
• Halten Sie external_id und scope_key stabil und zertifizieren Sie jede Bereichszuordnung vor der Produktion.
• Überwachen Sie das Alter der Quelldaten anhand der für diese Integration vereinbarten Aktualitätsrichtlinie.

Im maßgeblichen Producer-Leitfaden für Access Time Windows finden Sie Informationen zu vollständigen Snapshots, Zeitzonen, Sommerzeit, Stornierung und Testvektoren.

Zutrittskontrolle als sicherheitskritisch behandeln

Für Entriegelungen über den Door/Gate Controller gilt:

• Ihr System muss entscheiden, ob die Person eintreten darf, bevor es den Performance Hub aufruft.
• Der Performance Hub gibt 200 erst zurück, nachdem der Controller vor Ort bestätigt hat, dass das Relais physisch entriegelt hat.
• Die meisten Bestätigungen erfolgen innerhalb von 3-5 Sekunden.
• Eine Zeitüberschreitung ist eine explizit fehlgeschlagene Entriegelung, kein Erfolg im Hintergrund.
• Wiederholen Sie den Vorgang nur gemäß Ihren eigenen Zutritts- und Sicherheitsregeln.

Protokollieren Sie immer die vom Entriegelungs-Endpunkt zurückgegebenen Werte event_id und command_id.

Ihre Integration überwachen

Nutzen Sie während der Entwicklung und beim Launch die Anfrageprotokolle der Partner Console. Führen Sie in der Produktion zusätzlich eigene Protokolle mit:

• Zeitstempel der Anfrage.
• Endpunkt.
• Quelldatensatz-ID.
• Einrichtungskennung.
• HTTP-Statuscode.
• Antworttext oder Fehlermeldung des Performance Hub.

Mit diesen Feldern lassen sich Support und Abgleich deutlich beschleunigen, wenn ein Kunde fragt, was passiert ist.

Organisationen

Stellt die übergeordnete Geschäftseinheit dar, die eine oder mehrere in die Performance Hub-Plattform integrierte Einrichtungen betreibt.

Das Organisationsobjekt

Attribute

• org_id string erforderlich

  Eindeutige Kennung der Organisation.

• name string erforderlich

  Name der Organisation.

Alle Organisationen auflisten

Gibt eine Liste der Organisationen zurück, auf die Ihr Partnerkonto zugreifen kann.

Rückgabe

Gibt ein JSON-Objekt mit einer Eigenschaft data zurück, die ein Array von Organisationsobjekten enthält.

Einrichtungen

Stellt einen physischen Standort dar, etwa ein Büro, ein Geschäft, einen Veranstaltungsort, einen Campus, eine Klinik oder ein Fitnessstudio, an dem Mitglieder Leistungen in Anspruch nehmen können.

Das Einrichtungsobjekt

Attribute

• facility_id string erforderlich

  Eindeutige Kennung der Einrichtung.

• org_id string erforderlich

  Eindeutige Kennung der übergeordneten Organisation.

• name string erforderlich

  Name der Einrichtung.

• brand string optional

  Von der Einrichtung verwendeter Markenname.

• website_url string optional

  URL der Website der Einrichtung.

• place_data object optional

  Standortdaten aus der Google Places API mit Land, formatierter Adresse, Google Place ID, Bundesland bzw. Provinz und Stadt.

• social_links object optional

  Social-Media-Links der Einrichtung.

• timezone string optional

  IANA-Zeitzonenkennung (z. B. "Australia/Sydney", "America/New_York").

Alle Einrichtungen auflisten

Gibt eine Liste der Einrichtungen zurück, auf die Ihr Partnerkonto zugreifen kann.

Rückgabe

Gibt ein JSON-Objekt mit einer Eigenschaft data zurück, die ein Array von Einrichtungsobjekten enthält.

Mitgliedschaftstarife

Definiert ein käufliches Angebot einer Organisation oder Einrichtung, einschließlich Leistungen, Berechtigungen, Zeitplan und Preisen.

Das Mitgliedschaftstarif-Objekt

Attribute

• membership_plan_id string erforderlich

  Eindeutige Kennung des Mitgliedschaftstarifs.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutige Kennung der Einrichtung aus dem Performance Hub.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutiger Kennungswert, den der Partner für jeden Standort verwendet (z. B. „Branch ID“, „Location Code“, „Store Number“). Weitere Informationen

• name string erforderlich

  Menschenlesbarer Tarifname (z. B. "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").

• billing_cycle string optional

  Abrechnungshäufigkeit. Einer der Werte weekly, fortnightly, monthly, annually oder one_time.

• price integer optional

  Grundpreis in der kleinsten Währungseinheit (Cent bei USD/AUD).

• currency string optional

  Währungscode nach ISO 4217 (z. B. "AUD", "USD").

• description string optional

  Optionale Marketing- oder interne Beschreibung.

• active_members integer optional

  Anzahl der aktiven Mitglieder mit diesem Mitgliedschaftstarif

• is_recurring boolean optional

  Ob sich der Tarif automatisch verlängert.

• is_trial boolean optional

  Ob es sich um ein Testangebot handelt.

• visible_to_public boolean optional

  Ob der Tarif im Self-Service gekauft werden kann.

• duration_days integer optional

  Anzahl der Tage, die der Mitgliedschaftstarif gültig ist.

• access_zones array optional

  Array der im Mitgliedschaftstarif enthaltenen Zutrittszonen. Jede Zone kann eigene Zutrittszeiten definieren. Details finden Sie unter Zutrittszonen.

• class_limit integer optional

  Maximale Anzahl zulässiger Kurse (null für unbegrenzt).

Zutrittszonen

Zutrittszonen definieren bestimmte Bereiche innerhalb einer Einrichtung, zu denen ein Mitgliedschaftstarif Zutritt gewährt. Jede Zone kann eigene Zutrittszeiten haben, sodass pro Bereich unterschiedliche zeitliche Einschränkungen gelten können.

Struktur

Jede Zutrittszone umfasst:

• name string erforderlich

  Der Name der Zone (z. B. „Level 3 Tenancy“, „Library“, „Guest Floors“, „Main Gym Floor“).

• description string optional

  Beschreibung dessen, was in dieser Zone enthalten ist.

• access_hours object optional

  Zutrittszeiten speziell für diese Zone. Das Format der Zeitbereiche finden Sie unter Zutrittszeiten.

Zutrittszeiten

Zutrittszeiten legen fest, wann Mitglieder an den einzelnen Wochentagen Zutritt zu einer bestimmten Zone haben. Zutrittszeiten werden pro Zutrittszone definiert, sodass für verschiedene Bereiche einer Einrichtung unterschiedliche zeitliche Einschränkungen gelten können.

Einen Mitgliedschaftstarif speichern

Erstellt oder aktualisiert Datensätze zu Mitgliedschaftstarifen. Die API entscheidet anhand der membership_plan_id, ob ein Datensatz erstellt oder aktualisiert wird.

Parameter

• membership_plans array erforderlich

  Array der zu speichernden Mitgliedschaftstarif-Objekte. Empfohlenes Maximum für optimale Leistung: 1000 Elemente pro Anfrage. Die API fasst Elemente für die Verarbeitung automatisch in Batches zusammen. Jedes Element muss entweder facility_id (erforderlich, wenn linking_identifier nicht verwendet wird) oder linking_identifier (erforderlich, wenn facility_id nicht verwendet wird) enthalten.

Rückgabe

Gibt eine einfache Meldung zurück, die den Synchronisierungsvorgang bestätigt.

Mitglieder

Stellt einen einzelnen Kunden einer Einrichtung dar. Kann ein Lead, ein Interessent, ein wiederkehrender Kunde, ein abgelaufenes Mitglied oder ein gesperrter Benutzer sein.

Upserts von Mitgliedern können auch einen vollständigen, revisionierten access_time_windows-Snapshot mit absoluten und wöchentlich wiederkehrenden Zutrittszeiten enthalten. Lesen Sie Access Time Windows, bevor Sie diese Felder erzeugen. Es handelt sich um zusätzliche Berechtigungen, die die regulären Regeln oder dauerhaften Berechtigungen der Einrichtung nicht ersetzen.

Das Mitgliederobjekt

Attribute

• member_id string erforderlich

  Eindeutige Kennung des Mitglieds.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutige Kennung der Einrichtung aus dem Performance Hub.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutiger Kennungswert, den der Partner für jeden Standort verwendet (z. B. „Branch ID“, „Location Code“, „Store Number“). Weitere Informationen

• first_name string erforderlich

  Vorname des Mitglieds.

• last_name string erforderlich

  Nachname des Mitglieds.

• email string optional

  E-Mail-Adresse.

• mobile_phone string optional

  Mobiltelefonnummer im Format E.123 (z. B. "+1 415 555 2671").

• address object optional

  Objekt mit der Postanschrift und folgenden Eigenschaften:

  • address_line_1 (string) - Hauptadresse (Straße und Hausnummer)
  • address_line_2 (string, optional) - Zusätzliche Adresszeile
  • city (string) - Name der Stadt
  • state (string) - Code des Bundeslands bzw. der Provinz
  • postal_code (string) - Postleitzahl
  • country (string) - Ländercode nach ISO 3166-1 alpha-2 (z. B. „AU“, „US“)
  • country_name (string, optional) - Vollständiger Name des Landes

• date_of_birth string optional

  Geburtsdatum im Format YYYY-MM-DD.

• gender string optional

  Einer der Werte male, female, non_binary, prefer_not_to_say oder unknown.

• type string optional

  Mitgliedertyp (z. B. staff, member, prospect).

• tags array optional

  Kurze Hilfs-Strings oder -Texte, um bestimmte Mitglieder zu kategorisieren und zu identifizieren (z. B. ["vip", "personal-training", "student"]).

• membership_status string optional

  Aktueller Mitgliedschaftsstatus (z. B. active, expired, on_hold).

• membership_plans array optional

  Array der Mitgliedschaftstarife, die dem Mitglied zugeordnet sind.

• profile_picture string optional

  Base64-codiertes Profilbild (optional).

• created string optional

  ISO 8601-Zeitstempel der Erstellung des Mitglieds.

• updated string optional

  ISO 8601-Zeitstempel der letzten Aktualisierung des Mitglieds.

• access_time_windows array optional

  Vollständiger quelleigener Snapshot absoluter und/oder wöchentlich wiederkehrender Access Time Windows. Lassen Sie das Feld weg, um den Snapshot unverändert zu lassen; senden Sie ein leeres Array mit einer neueren Revision, um ihn zu widerrufen. Formen, Validierung, Bereichszuordnung und Ersetzungssemantik finden Sie unter Access Time Windows.

• access_time_windows_revision integer erforderlich mit access_time_windows

  Monoton steigende, nicht negative, JSON-sichere Ganzzahl für diesen Strom aus Mitglied und Quelle. Immer dann erforderlich, wenn access_time_windows vorhanden ist.

Zugriffszeitfenster

Mit Access Time Windows kann ein Partnermitglied befristete oder wiederkehrende Zutrittsberechtigungen tragen, die von einem externen System geliefert werden. Diese Seite ist der maßgebliche Producer-Leitfaden für access_time_windows und access_time_windows_revision.

Access Time Windows sind zusätzliche, ausschließlich erlaubende Berechtigungen. Ein aktives Zeitfenster kann den Zutritt erlauben, aber ein inaktives, abgelaufenes, veraltetes oder nicht zugeordnetes Zeitfenster verweigert keinen Zutritt, den eine reguläre Regel oder eine dauerhafte Berechtigung bereits erlaubt. Die Deaktivierung von Benutzern, explizite Türsperren, der Wartungsmodus, Geofencing, Ratenbegrenzungen und die Verfügbarkeit des Controllers gelten weiterhin.

Implementierungen für bestimmte Quellsysteme sind separate Adapter. Sie müssen ihre Quelldaten in diesen herstellerneutralen Vertrag übersetzen, ohne die Bedeutung seiner Felder zu verändern.

Snapshot-Felder des Mitglieds

• access_time_windows array optional

  Der vollständige Access Time Windows-Snapshot für dieses Mitglied und diese Partnerquelle. Ein Snapshot kann absolute- und weekly-Zeitfenster mischen. Lassen Sie das Feld weg, um den gespeicherten Snapshot unverändert zu lassen; senden Sie [], um alle Zeitfenster dieser Quelle zu widerrufen.

• access_time_windows_revision integer erforderlich mit access_time_windows

  Eine monoton steigende, nicht negative, JSON-sichere Ganzzahl für diesen Revisionsstrom aus Mitglied und Quelle. Sie ist immer dann erforderlich, wenn access_time_windows vorhanden ist, und darf 9007199254740991 nicht überschreiten.

Jeder Snapshot akzeptiert höchstens 50 Zeitfenster. external_id, scope_key und label akzeptieren höchstens 120 Zeichen. Absolute Zeitfenster dürfen höchstens 90 Tage umfassen. Ein Wochentag akzeptiert höchstens acht sich nicht überschneidende Blöcke. Ungültige Daten werden abgelehnt, statt gekürzt oder erraten zu werden.

Formen von Zeitfenstern

Ein absolutes Zeitfenster bezeichnet genau ein Intervall:

Vollständige gemischte Anfrage

Diese Anfrage ersetzt den bisherigen quelleigenen Snapshot des Mitglieds durch ein absolutes und ein wöchentliches Zeitfenster:

Regeln für Zeiten und Grenzen

from, to, active_from und active_until sind JSON-Ganzzahlen in Unix-Sekunden, die UTC-Zeitpunkte bezeichnen:

• Senden Sie eine JSON-Ganzzahl ohne Anführungszeichen. Numerische Strings, Gleitkommazahlen, RFC 3339-Strings und Unix-Millisekunden werden abgelehnt.
• Jedes Intervall ist halboffen: [from, to). Der Zutritt kann genau bei from beginnen; genau bei to ist er nicht mehr aktiv.
• from muss kleiner als to sein. Wenn beide wöchentlichen Grenzen vorhanden sind, muss active_from kleiner als active_until sein.
• Leiten Sie Epoch-Werte nicht aus einem lokalen Datum bzw. einer lokalen Uhrzeit ohne Zeitzone ab. Lösen Sie die Quellzeit zunächst in einen UTC-Zeitpunkt auf, teilen Sie dann die Unix-Millisekunden durch 1000 und prüfen Sie, ob das Ergebnis eine Ganzzahl ist.

Zeitzonen und Sommerzeit

timezone muss eine gültige IANA-Zeitzone sein, etwa UTC, Australia/Perth oder America/New_York. Wird sie weggelassen, gilt standardmäßig UTC.

• Absolute Zeitfenster: from und to bezeichnen bereits exakte UTC-Zeitpunkte. timezone dient nur als Metadatum für Anzeige und Audit; eine Änderung verschiebt keinen der beiden Zeitpunkte.
• Wöchentliche Zeitfenster: timezone legt die lokale Uhrzeit und die Sommerzeitregeln fest, nach denen access_hours ausgewertet wird. Rechnen Sie wöchentliche Blöcke nicht vorab in UTC um.
• Bei der Umstellung auf Sommerzeit tritt eine lokale Uhrzeit, die in der Zeitzone übersprungen wird, nie ein.
• Bei der Umstellung auf Winterzeit entsprechen beide realen Zeitpunkte mit der wiederholten lokalen Uhrzeit dem wöchentlichen Block.
• active_from und active_until bleiben UTC-Zeitpunkte, auch wenn ein wöchentliches Zeitfenster eine andere Zeitzone als UTC verwendet.

access_hours verwendet die Kleinbuchstaben sun bis sat. Jeder Wert ist ein Array von [start, end]-Paaren im 24-Stunden-Format HH:mm mit führenden Nullen. Blöcke müssen nicht leer, geordnet und überschneidungsfrei sein. end ist exklusiv. Ein Block darf nicht über Mitternacht reichen; teilen Sie ein Quellintervall über Nacht in einen späten Block am ersten Tag und einen frühen Block am folgenden Tag auf.

Stabile IDs und Bereichszuordnung

external_id muss während der gesamten Lebensdauer eines logischen Zeitfensters stabil und innerhalb des Mitglieder-Snapshots eindeutig sein. Halten Sie sie stabil, wenn sich Zeiten oder Bezeichnungen ändern, damit Betreiber und Audit-Datensätze Revisionen einander zuordnen können. Verwenden Sie sie nicht für ein unabhängiges Zeitfenster wieder.

scope_key ist Ihr stabiles logisches Zutrittsziel. Standardwert ist default. Ein Administrator der Einrichtung ordnet jeden zulässigen Schlüssel einem Ziel im Performance Hub zu: der gesamten Einrichtung, einer Tür oder einem Zugriffsbereich:

Vollständige Snapshots und Revisionen

Behandeln Sie die beiden Felder als separat versionierte Partition innerhalb des Mitglieder-Upserts:

Ein Snapshot ist vollständig, kein Patch. Wenn Revision 1842 die Zeitfenster A und B enthält, entfernt Revision 1843, die nur B enthält, das Zeitfenster A.

Führen Sie pro Partner und Mitglied einen einzigen koordinierten Revisionsstrom über Webhook-Worker, Polling, Wiederholung und vollständigen Abgleich hinweg. Eine dauerhafte Datenbanksequenz wird bevorzugt. Ein Unix-Millisekundenwert kann nur dann als Revision verwendet werden, wenn alle Schreiber sich abstimmen und eine strikte Reihenfolge und Eindeutigkeit garantieren; es handelt sich um einen Revisionswert, nicht um ein Epoch-Feld.

Speichern Sie die exakte Anfrage und Revision, bis die API-Antwort bekannt ist. Wiederholen Sie nach einer Zeitüberschreitung oder einem vorübergehenden Fehler denselben normalisierten Snapshot mit derselben Revision. Vergeben Sie keine neue Revision, nur weil die Zustellung auf Transportebene unsicher ist.

Stornierung, Ablauf und Fehler der Quelle

• Ein Zeitfenster stornieren: Rufen Sie den maßgeblichen Quellzustand erfolgreich ab, entfernen Sie dieses Zeitfenster und senden Sie den verbleibenden vollständigen Snapshot mit einer neueren Revision.
• Alle Zeitfenster stornieren: Senden Sie access_time_windows: [] mit einer neueren Revision.
• Ein absolutes Zeitfenster ablaufen lassen: Es erlaubt ab to keinen Zutritt mehr; senden Sie später einen Abgleich ohne den abgelaufenen Eintrag, um die Snapshots sauber zu halten.
• Ein wöchentliches Zeitfenster beenden: Entfernen Sie es in einem neueren Snapshot oder verwenden Sie active_until, wenn die Quelle einen bekannten Endzeitpunkt hat.
• Abruf aus der Quelle schlägt fehl oder ist unvollständig: Senden Sie kein [] und veröffentlichen Sie keinen unvollständigen Snapshot. Lösen Sie eine Warnung aus und wiederholen Sie den Abruf. Wird ein Fehler der Quelle in einen leeren Snapshot umgewandelt, führt das zu einem unbeabsichtigten Widerruf des Zutritts.
• Anfrage an die Partner API besteht die Validierung nicht: Korrigieren Sie die Daten und senden Sie nur dann eine neuere Revision, wenn sich der normalisierte Snapshot ändert. Wiederholen Sie vorübergehende Fehler mit der ursprünglichen Revision.

Die Aktualität der Quelle wird pro Integration anhand der zugesagten Liefer- und Abgleichsfrequenz konfiguriert. Vereinbaren Sie vor der Aktivierung das maximale Alter der Quelldaten, was bei Überschreitung geschieht, Schwellenwerte für Warnungen und ob Betreiber bestätigen dürfen, sich nur auf die eigenen Grenzen jedes Zeitfensters zu verlassen. Ein veraltetes Quellzeitfenster wird nie zu einer Verweigerungsregel; reguläre Regeln und dauerhafte Berechtigungen bleiben Fallback-Pfade.

Producer-Algorithmus

Verwenden Sie diesen sprachunabhängigen Ablauf für jede Mitgliederaktualisierung:

Zertifizierungscheckliste

Führen Sie diese Prüfungen in einer Stage-Einrichtung mit der endgültigen scope_key-Zuordnung durch:

• Ein absolutes Zeitfenster ohne Zeitzone wird akzeptiert und als UTC ausgewertet.
• Ein absolutes Zeitfenster mit benutzerdefinierter IANA-Zeitzone behält dieselben from/to-Zeitpunkte bei.
• Ein wöchentliches Zeitfenster mit benutzerdefinierter IANA-Zeitzone folgt der lokalen Uhrzeit über die Umstellungen auf Sommer- und Winterzeit hinweg.
• Ein gemischter Snapshot aus absoluten und wöchentlichen Zeitfenstern ersetzt den vorherigen Snapshot vollständig.
• Der Zutritt beginnt genau bei from und endet genau bei to; auch die Enden wöchentlicher Blöcke sind exklusiv.
• Die Aktualisierung von Zeiten unter derselben external_id mit einer neueren Revision wird wirksam.
• Das Weglassen von access_time_windows ändert andere Mitgliederfelder, ohne die Zeitfenster zu ändern.
• Die Wiederholung derselben Revision bzw. Payload ist idempotent.
• Gleiche Revision mit abweichender Payload gibt einen Konflikt zurück und ändert den Snapshot nicht.
• Eine ältere Revision, die außerhalb der Reihenfolge eintrifft, wird als veraltet gemeldet und kann den Zustand nicht zurücksetzen.
• Ein neueres [] widerruft quelleigene Zeitfenster; bei einem fehlgeschlagenen Abruf aus der Quelle wird nichts gesendet.
• Ein unbekannter oder nicht zugeordneter scope_key führt zur Verweigerung (fail closed) und erzeugt eine für Betreiber sichtbare Warnung.
• Warnungen zum Alter der Quelldaten und die konfigurierte Richtlinie für veraltete Quellen funktionieren beim vereinbarten Schwellenwert.
• Webhook- und vollständige Abgleichspfade führen zum selben Snapshot und zur selben Revisionsreihenfolge.
• Die Zustellung über den Strom erreicht Door & Gate Access innerhalb des vereinbarten Ziels.
• Ein aktives Zeitfenster kann den Zutritt zur zugeordneten physischen Tür erlauben, aber weder die Deaktivierung von Benutzern, blockAllAccess, die Wartung noch das Geofencing umgehen.
• Vor, außerhalb und nach einem Zeitfenster erlauben reguläre Regeln und dauerhafte Berechtigungen weiterhin Benutzern den Zutritt, die ansonsten berechtigt sind.

Weiterführende Hinweise

• Das Mitgliederobjekt
• Ein Mitglied speichern
• Best Practices
• Fehler
• Go-live-Checkliste

Ein Mitglied speichern

Erstellt oder aktualisiert Mitgliederdatensätze. Die API entscheidet anhand der member_id, ob ein Datensatz erstellt oder aktualisiert wird.

Parameter

• members array erforderlich

  Array der zu speichernden Mitgliederobjekte. Empfohlenes Maximum für optimale Leistung: 1000 Elemente pro Anfrage. Die API fasst Elemente für die Verarbeitung automatisch in Batches zusammen. Jedes Element muss entweder facility_id (erforderlich, wenn linking_identifier nicht verwendet wird) oder linking_identifier (erforderlich, wenn facility_id nicht verwendet wird) enthalten.

  Wenn ein Mitglied access_time_windows enthält, muss es auch access_time_windows_revision enthalten. Das Array ist ein vollständiger Quell-Snapshot, kein Patch. Lassen Sie es weg, um den vorhandenen Snapshot beizubehalten, oder senden Sie [] mit einer neueren Revision, um alle quelleigenen Zeitfenster zu widerrufen. Lesen Sie den Leitfaden zu Access Time Windows, bevor Sie dieses Feld aktivieren.

Rückgabe

Gibt eine einfache Meldung zurück, die den Synchronisierungsvorgang bestätigt.

Die Profilfelder des Mitglieds werden weiterhin normal per Upsert verarbeitet, auch wenn ein Zeitfenster-Snapshot als idempotente Wiederholung oder als veraltet übersprungen gemeldet wird. Ein widersprüchlicher Snapshot mit gleicher Revision und abweichender Payload kann nicht unverändert wiederholt werden; gleichen Sie den Quellzustand ab und senden Sie eine neuere Revision.

Check-ins

Stellt einen Datensatz über die Anwesenheit einer Person in einer Einrichtung, einem Kurs oder bei einer Aktivität dar. Wird zur Erfassung der Anwesenheit, für Nutzungsanalysen und zur Verbesserung der Genauigkeit der visuellen Erkennung verwendet.

Das Check-in-Objekt

Attribute

• check_in_id string optional

  Eindeutige Kennung des Check-ins. Optional – wird aus dem Paar member_id und timestamp automatisch erzeugt, wenn sie nicht angegeben wird.

• member_id string erforderlich

  Eindeutige Kennung des Mitglieds.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutige Kennung der Einrichtung aus dem Performance Hub.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutiger Kennungswert, den der Partner für jeden Standort verwendet (z. B. „Branch ID“, „Location Code“, „Store Number“). Weitere Informationen

• check_in_type string optional

  Art des Besuchs. Einer der Werte member, class, staff, guest oder trial.

• source string optional

  Wie der Check-in erfasst wurde. Gängige Werte sind manual, tag, rfid, kiosk, app. Weitere Werte wie door_reader oder booking können ebenfalls verwendet werden.

• class_id string optional

  Optional. Wenn der Check-in mit einer Kursbuchung oder Kursteilnahme verknüpft ist.

• timestamp string erforderlich

  Zeitstempel im Format ISO 8601, zu dem der Check-in erfolgte.

Check-ins speichern

Erstellt Check-in-Datensätze. Die API dedupliziert automatisch anhand von Mitglied, Einrichtung und Zeitstempel.

Parameter

• check_ins array erforderlich

  Array der zu speichernden Check-in-Objekte. Empfohlenes Maximum für optimale Leistung: 1000 Elemente pro Anfrage. Die API fasst Elemente für die Verarbeitung automatisch in Batches zusammen. Jedes Element muss entweder facility_id (erforderlich, wenn linking_identifier nicht verwendet wird) oder linking_identifier (erforderlich, wenn facility_id nicht verwendet wird) enthalten.

Rückgabe

Gibt eine einfache Meldung zurück, die den Synchronisierungsvorgang bestätigt.

Zutrittskontrolle

Die Partner API kann die Hardware des Door/Gate Controller des Performance Hub in Einrichtungen auslösen, in denen Ihre Integration aktiviert ist.

Verwenden Sie diese API, wenn Ihr Mitgliederverwaltungssystem bereits entschieden hat, dass eine Person eintreten darf. Der Performance Hub prüft weder Mitgliedschaftsstatus, Zutrittszeiten, Türzonenregeln, Betrugsprüfungen noch Sperrlogik. Ihr System bleibt für diese Entscheidungen maßgeblich.

Die Entriegelungsanfrage ist synchron. Der Performance Hub sendet den Befehl in Echtzeit an den Controller vor Ort und gibt 200 erst zurück, nachdem das Gerät bestätigt hat, dass das Relais physisch entriegelt hat. Die meisten Bestätigungen sollten innerhalb von 3-5 Sekunden erfolgen. Wenn innerhalb des Zeitlimits keine Bestätigung eingeht, gibt die API einen expliziten Fehler zurück.

Sie können auch einen Zutrittsversuch oder eine Ablehnung erfassen, die den Controller nie erreicht hat. Dieser Aufruf entriegelt die Tür nicht. Er schreibt ein Ereignis in die Zugriffsprotokolle von Door & Gate Access.

Das Door/Gate Controller-Objekt

Attribute

• door_id string erforderlich

  Eindeutige Kennung des Door/Gate Controller. Speichern Sie sie nach der Erkennung in Ihrem System und verwenden Sie sie beim Aufruf des Entriegelungs-Endpunkts.

• facility_id string erforderlich

  Einrichtungs-ID des Performance Hub.

• linking_identifier string optional

  Einrichtungskennung des Partners, wenn Ihre Integration Linking Identifier verwendet. Weitere Informationen

• name string erforderlich

  Im Performance Hub konfigurierter, menschenlesbarer Gerätename.

• zone string optional

  Türzone oder Standort, etwa Entrance.

• status string erforderlich

  online oder offline.

• relay_state string optional

  Zuletzt bekannter Relaiszustand, etwa locked oder unlocked.

• maintenance_mode string erforderlich

  Aktueller Wartungsmodus. Einer der Werte off, force-open oder force-closed.

• hold_time_seconds integer erforderlich

  Für die Tür konfigurierte Standard-Haltezeit der Entriegelung.

• last_seen string optional

  ISO-Zeitstempel der letzten Aktualisierung der Gerätemetadaten.

Door/Gate Controller auflisten

Gibt die Door/Gate Controller zurück, die für Ihre Integration verfügbar sind.

Wenn weder facility_id noch linking_identifier angegeben ist, gibt die API die Door/Gate Controller aller Einrichtungen zurück, die mit Ihrem Partnerkonto verknüpft sind.

Parameter

• facility_id string optional entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungs-ID des Performance Hub. Verwenden Sie diese für Direct-Link-Integrationen.

• linking_identifier string optional entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Ihre eigene Einrichtungs-/Standortkennung. Verwenden Sie diese, wenn Ihre Integration für Linking Identifier konfiguriert ist.

Rückgabe

Gibt ein Array von Door/Gate Controller-Objekten zurück.

Status eines Door/Gate Controller abrufen

Ruft den zuletzt bekannten Zustand und die Basiskonfiguration eines einzelnen Door/Gate Controller ab.

Geben Sie eine Einrichtungskennung an, damit der Performance Hub prüfen kann, ob die Tür zu einer Einrichtung gehört, auf die Ihre Integration zugreifen darf.

Parameter

• door_id string erforderlich

  Die vom Listen-Endpunkt zurückgegebene ID des Door/Gate Controller.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungs-ID des Performance Hub. Erforderlich für Direct-Link-Integrationen.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungskennung des Partners. Erforderlich für Linking-Identifier-Integrationen.

Rückgabe

Gibt ein Door/Gate Controller-Objekt zurück.

Einen Door/Gate Controller entriegeln

Sendet einen Entriegelungsbefehl an den Door/Gate Controller und wartet, bis das physische Relais die Entriegelung bestätigt.

Ihr System muss entscheiden, ob die Person berechtigt ist, bevor es diesen Endpunkt aufruft. Der Performance Hub prüft nur den Partnerschlüssel, den Einrichtungszugriff, die Zugehörigkeit der Tür und den Gerätezustand.

Parameter

• door_id string erforderlich

  Die vom Listen-Endpunkt zurückgegebene ID des Door/Gate Controller.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungs-ID des Performance Hub. Erforderlich für Direct-Link-Integrationen.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungskennung des Partners. Erforderlich für Linking-Identifier-Integrationen.

• member_id string erforderlich

  Mitglieds-ID des Partners. Wird für die Audit-Protokollierung und die spätere Datenverknüpfung verwendet.

• first_name string erforderlich

  Vorname der Person, die die Tür öffnet.

• last_name string erforderlich

  Nachname der Person, die die Tür öffnet.

• full_name string optional

  Optional. Wenn das Feld fehlt, kombiniert der Performance Hub first_name und last_name.

• check_in_id string optional

  Optionale Check-in-ID aus Ihrem System zur Zuordnung.

• idempotency_key string optional

  Optionaler Schlüssel zum Schutz vor Wiederholungen. Wird derselbe Schlüssel für denselben Partner, dieselbe Einrichtung und dieselbe Tür erneut verwendet, wird das vorhandene Ergebnis zurückgegeben, sofern verfügbar.

Rückgabe

Gibt 200 nur zurück, wenn das Gerät bestätigt, dass das Relais physisch entriegelt hat. Die Tür verwendet die in der Geräteverwaltung des Performance Hub konfigurierte Haltezeit; Partner können das Relais-Timing nicht pro Anfrage überschreiben. Die meisten Bestätigungen sollten innerhalb von 3-5 Sekunden erfolgen. Behandeln Sie das dokumentierte Zeitlimit als explizit fehlgeschlagene Entriegelung und wiederholen Sie den Vorgang nur gemäß Ihren eigenen Sicherheitsregeln.

Häufige Fehler:

• 403 integration_not_enabled - Ihre Integration ist für die Einrichtung nicht aktiviert.
• 409 maintenance_mode_active - Das Personal der Einrichtung hat den Wartungsmodus für die Tür aktiviert.
• 503 device_offline - Der Door/Gate Controller ist offline oder seine Daten sind veraltet.
• 504 unlock_confirmation_timeout - Der Befehl wurde gesendet, aber vor Ablauf des Zeitlimits ging keine passende Bestätigung ein.

Einen Zutrittsversuch oder eine Ablehnung erfassen

Erfasst einen Zutrittsversuch oder eine Ablehnung, über die Ihr System bereits entschieden hat. Der Door/Gate Controller wird nicht kontaktiert, und die Tür wird nicht entriegelt.

Verwenden Sie diesen Aufruf, wenn Ihr System den Zutritt verweigert oder wenn ein Versuch ohne Entriegelung in den Zugriffsprotokollen von Door & Gate Access erscheinen soll. Der Performance Hub prüft weder Mitgliedschaftsstatus, Zutrittszeiten noch andere Zutrittsregeln.

Ein abgelehntes Ereignis erscheint in den Zugriffsprotokollen von Door & Gate Access mit dem Ergebnis Denied, Ihrem Partnernamen, der Tür, der Mitgliedskennung (sofern Sie eine senden) und dem Grundcode in lesbarer Form. Beispielsweise wird membership_expired als „Membership Expired“ angezeigt. reason_display_text und user_email werden mit dem Ereignis gespeichert.

Parameter

• door_id string erforderlich

  Die vom Listen-Endpunkt zurückgegebene ID des Door/Gate Controller.

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungs-ID des Performance Hub. Erforderlich für Direct-Link-Integrationen.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Einrichtungskennung des Partners. Erforderlich für Linking-Identifier-Integrationen.

• outcome string erforderlich

  denied oder attempted.

• reason string optional

  Grundcode in Kleinbuchstaben im snake_case-Format, bis zu 64 Zeichen. Erforderlich, wenn outcome den Wert denied hat. Beispiel: membership_expired.

• reason_display_text string optional

  Menschenlesbarer Grund, bis zu 256 Zeichen. Beispiel: Membership expired on 2026-04-01.

• member_id string optional

  Mitglieds-ID des Partners. Lassen Sie sie weg, wenn die Zugangsdaten keinem Mitglied zugeordnet werden konnten, etwa bei einer unbekannten Karte.

• user_email string optional

  E-Mail-Adresse der Person, die den Zutritt versucht hat.

• timestamp string optional

  Zeitpunkt des Versuchs im Format ISO 8601 mit Zeitzone. Beispiel: 2026-05-18T10:15:30Z. Standardmäßig der Zeitpunkt, zu dem die Anfrage eingeht. Darf nicht mehr als 5 Minuten in der Zukunft oder mehr als 30 Tage in der Vergangenheit liegen.

• idempotency_key string optional

  Schlüssel zum Schutz vor Wiederholungen, bis zu 128 Zeichen. Wird derselbe Schlüssel für denselben Partner, dieselbe Einrichtung und dieselbe Tür erneut verwendet, wird das ursprüngliche Ergebnis zurückgegeben.

Rückgabe

Gibt 201 zurück, wenn das Ereignis erfasst wurde. Eine Wiederholung mit demselben idempotency_key gibt 200 zurück, wobei idempotent auf true gesetzt ist, und erstellt kein weiteres Ereignis.

Ein Dry-Run-Schlüssel gibt 200 zurück, wobei dry_run auf true gesetzt ist. Es wird nichts erfasst.

Häufige Fehler:

• 400 - Der Body ist ungültig, eine Ablehnung hat keinen reason, der Zeitstempel liegt außerhalb des zulässigen Bereichs oder facility_id / linking_identifier entspricht keiner verknüpften Einrichtung.
• 403 - Der Schlüssel ist schreibgeschützt.
• 403 integration_not_enabled - Ihre Integration ist für die Einrichtung nicht aktiviert. message nennt den Grund.
• 404 - Der Door/Gate Controller wurde für die verknüpfte Einrichtung nicht gefunden.

Einrichtungsberichte

Ein Datensatz zu einem bestimmten Zeitpunkt, der wichtige betriebliche und finanzielle Kennzahlen einer Einrichtung für einen bestimmten Zeitraum erfasst.

Das Berichts-Snapshot-Objekt

Attribute

• facility_id string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutige Kennung der Einrichtung aus dem Performance Hub.

• linking_identifier string entweder/oderGeben Sie den für Ihre Integration konfigurierten Typ der Einrichtungskennung an: Verwenden Sie facility_id für Direct-Link-Integrationen oder linking_identifier für Linking-Identifier-Integrationen. Senden Sie nicht beide; die API verwendet den für Ihr Partnerkonto konfigurierten Kennungstyp und ignoriert den anderen. Weitere Informationen

  Eindeutiger Kennungswert, den der Partner für jeden Standort verwendet (z. B. „Branch ID“, „Location Code“, „Store Number“). Weitere Informationen

• start_date string erforderlich

  Startdatum des Snapshot-Zeitraums im Format YYYY-MM-DD.

• end_date string erforderlich

  Enddatum des Snapshot-Zeitraums im Format YYYY-MM-DD.

• metrics object erforderlich

  Kennzahlenobjekt mit Mitglieder- und Umsatzdaten für den Zeitraum.

Berichts-Snapshots speichern

Übermittelt betriebliche und finanzielle Kennzahlen einer Einrichtung für einen bestimmten Zeitraum.

Parameter

• snapshots array erforderlich

  Array der zu speichernden Berichts-Snapshot-Objekte. Maximal 25 Elemente pro Anfrage. Jedes Element muss entweder facility_id (erforderlich, wenn linking_identifier nicht verwendet wird) oder linking_identifier (erforderlich, wenn facility_id nicht verwendet wird) enthalten.

Rückgabe

Gibt eine einfache Meldung zurück, die den Synchronisierungsvorgang bestätigt.

Fehler

Die Partner API verwendet Standard-HTTP-Statuscodes und JSON-Antworttexte, um zu erklären, warum eine Anfrage fehlgeschlagen ist.

Aufbau der Fehlerantwort

Die meisten API-Fehler geben einen JSON-Body mit einer Meldung und, sofern verfügbar, strukturierten Details zurück.

Statuscodes

Fehler bei Access Time Windows

Die Validierung der Zeitfenster schlägt fehl, bevor der ungültige Snapshot geschrieben wird. Häufige Ursachen, bei denen eine Wiederholung nicht hilft, sind:

• Fehlende access_time_windows_revision, wenn access_time_windows vorhanden ist.
• Epoch-Werte als String, als Gleitkommazahl oder vermutlich in Millisekunden.
• Eine ungültige IANA-Zeitzone, ein umgekehrtes Intervall, eine doppelte external_id, sich überschneidende wöchentliche Blöcke oder ein nicht aufgeteilter Block über Mitternacht.
• Ein Wert außerhalb der dokumentierten Grenzen für Anzahl, Länge oder Zeitspanne.

Eine wiederholte Revision mit abweichendem normalisiertem Inhalt führt zu 409 Conflict. Gleichen Sie mit dem neuesten maßgeblichen Zustand ab und vergeben Sie eine neuere Revision; wiederholen Sie das widersprüchliche Paar nicht immer wieder. Eine ältere Revision wird als veralteter, übersprungener Snapshot gemeldet, statt einen neueren Zustand überschreiben zu dürfen. Ein unbekannter oder nicht zugeordneter scope_key führt bei der Autorisierung zur Verweigerung (fail closed) und sollte als Konfigurationswarnung behandelt werden.

Wenn bei der Zustellung eine Zeitüberschreitung auftritt oder ein vorübergehender 5xx-Fehler zurückkommt, wiederholen Sie genau denselben normalisierten Snapshot mit derselben Revision. Wenn der Abruf aus der Quelle fehlgeschlagen ist, lassen Sie das Zeitfensterfeld vollständig weg; ersetzen Sie es niemals durch ein leeres Array.

Hinweise zu Wiederholungen

Wiederholen Sie diese mit begrenztem exponentiellem Backoff:

• 429
• 500
• 502
• 503
• 504

Wiederholen Sie diese nicht ungeprüft:

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

Behandeln Sie bei der Zutrittskontrolle Zeitüberschreitungs- und Offline-Antworten immer als fehlgeschlagene Entriegelungen, sofern Ihre eigenen Zutrittsregeln und Sicherheitsprozesse nichts anderes vorsehen.

Angaben für den Support

Wenn Sie sich an den Support wenden, geben Sie Folgendes an:

• Endpunkt und HTTP-Methode.
• Zeitstempel und Zeitzone.
• Partner-Schlüssel-ID, nicht den geheimen Schlüssel.
• Verwendete Einrichtungskennung.
• Quelldatensatz-ID aus Ihrem System.
• Antwortstatus und Antworttext.
• event_id oder command_id, sofern verfügbar.

Versionierung

Die Partner API wird über die URL versioniert. Die aktuelle Version ist:

Änderungsrichtlinie

Der Performance Hub ist bestrebt, nach Möglichkeit nur ergänzende, abwärtskompatible Änderungen vorzunehmen.

Beispiele für abwärtskompatible Änderungen:

• Hinzufügen eines neuen optionalen Felds zu einer Anfrage.
• Hinzufügen eines neuen Felds zu einer Antwort.
• Hinzufügen eines neuen Endpunkts.
• Hinzufügen eines neuen Enum-Werts, sofern von Clients erwartet wird, dass sie unbekannte Werte verarbeiten.
• Verbesserung von Validierungsmeldungen, ohne den Vertrag für Statuscodes zu ändern.

access_time_windows und access_time_windows_revision sind ergänzende Anfragefelder für Mitglieder. Bestehende Clients, die sie weglassen, lassen den gespeicherten Access Time Windows-Snapshot unverändert. Diese Regel zum Weglassen erhält die Kompatibilität mit partiellen Upserts; das Weglassen ist nicht gleichbedeutend mit dem Senden eines leeren Arrays.

Beispiele für Breaking Changes:

• Entfernen oder Umbenennen eines Felds.
• Ändern des Typs eines Felds.
• Ein optionales Anfragefeld zur Pflicht machen.
• Entfernen eines Endpunkts.
• Ändern der Bedeutung eines vorhandenen Statuscodes oder eines domänenspezifischen reason.

Einstellung von Funktionen

Wenn ein Breaking Change erforderlich ist, vermeidet der Performance Hub nach Möglichkeit, die bestehende Version direkt zu ändern. Stattdessen führen wir eine neue Version oder einen Migrationspfad ein und informieren die betroffenen Partner über die Änderung.

Hinweise auf eingestellte Funktionen können Folgendes umfassen:

• Einen Eintrag im Änderungsprotokoll.
• Direkte Kommunikation mit Partnern.
• Hinweise in der Partner Console.
• Migrationshinweise in der Dokumentation.

Empfehlungen für Clients

Entwickeln Sie Clients, die ergänzende Änderungen tolerieren:

• Ignorieren Sie Antwortfelder, die Sie nicht verwenden.
• Behandeln Sie unbekannte Enum-Werte als nicht unterstützt, statt abzustürzen.
• Vermeiden Sie strikte Gleichheitsprüfungen von Antworten.
• Protokollieren Sie nicht erkannte Werte, damit Sie Ihre Integration gezielt aktualisieren können.

Speichern Sie bei revisionierten Mitgliederpartitionen wie Access Time Windows die übermittelte Revision und die normalisierte Payload, bis das Ergebnis bekannt ist. Die Wiederverwendung einer Revision für geänderten Inhalt ist ein Konflikt, während die Wiederholung desselben Inhalts idempotent ist. Siehe Access Time Windows.

OpenAPI-Spezifikationen

Verwenden Sie die veröffentlichten OpenAPI-Spezifikationen, um Clients zu generieren, Anfragen zu validieren und Änderungen an der API-Struktur im Zeitverlauf nachzuverfolgen.

Siehe OpenAPI-Spezifikationen.

Änderungsprotokoll

Dieses Änderungsprotokoll erfasst wesentliche Änderungen an der Partner API und der Partner Console, die sich auf das Verhalten von Integrationen auswirken.

2026-09-09

2026-05-06

2026-05-01

Änderungskategorien

Künftige Einträge verwenden diese Kategorien:

• Hinzugefügt - neuer Endpunkt, neues Feld, neuer Leitfaden oder neue Funktion.
• Geändert - Verhalten oder Dokumentation geändert, ohne die Unterstützung zu entfernen.
• Veraltet - Funktion bleibt verfügbar, für sie ist aber ein Migrationspfad geplant.
• Entfernt - Funktion oder Endpunkt entfernt.
• Behoben - Fehlerbehebung oder Korrektur der Dokumentation.
• Sicherheit - Änderung an Authentifizierung, Autorisierung, Datenverarbeitung oder Schlüsselverwaltung.