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.