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.

Anfrage

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/access-events \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "outcome": "denied",
    "reason": "membership_expired",
    "reason_display_text": "Membership expired on 2026-04-01",
    "member_id": "mem_12345",
    "user_email": "member@example.com",
    "timestamp": "2026-05-18T10:15:30Z",
    "idempotency_key": "evt_abc12345"
  }'

Antwort

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z"
}

Idempotente Wiederholung

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z",
  "idempotent": true
}