Rejestrowanie próby dostępu lub odmowy

Rejestruje próbę dostępu lub odmowę, o której Twój system już zdecydował. Kontroler drzwi/bramy nie jest kontaktowany, a drzwi nie zostają otwarte.

Używaj tego, gdy Twój system odmawia wejścia lub gdy próba ma się pojawić w Rejestry dostępu modułu Door & Gate Access bez otwierania drzwi. Performance Hub nie ocenia stanu członkostwa, godzin dostępu ani innych reguł dostępu.

Zdarzenie odmowy pojawia się w Rejestry dostępu modułu Door & Gate Access z wynikiem Denied, nazwą partnera, drzwiami, identyfikatorem członka (jeśli go przesyłasz) oraz kodem przyczyny w czytelnej postaci. Na przykład membership_expired jest wyświetlany jako „Membership Expired”. Wartości reason_display_text i user_email są zapisywane razem ze zdarzeniem.

Parametry

• door_id string wymagany

  Identyfikator kontrolera drzwi/bramy zwrócony przez punkt końcowy listy.

• facility_id string jedno z dwóchPodaj typ identyfikatora obiektu skonfigurowany dla Twojej integracji: facility_id w przypadku integracji z bezpośrednim łączeniem lub linking_identifier w przypadku integracji z identyfikatorem łączącym. Nie wysyłaj obu; API używa typu identyfikatora skonfigurowanego dla Twojego konta partnera i ignoruje drugi. Więcej informacji

  Identyfikator obiektu w Performance Hub. Wymagany w przypadku integracji z bezpośrednim łączeniem.

• linking_identifier string jedno z dwóchPodaj typ identyfikatora obiektu skonfigurowany dla Twojej integracji: facility_id w przypadku integracji z bezpośrednim łączeniem lub linking_identifier w przypadku integracji z identyfikatorem łączącym. Nie wysyłaj obu; API używa typu identyfikatora skonfigurowanego dla Twojego konta partnera i ignoruje drugi. Więcej informacji

  Identyfikator obiektu partnera. Wymagany w przypadku integracji z identyfikatorem łączącym.

• outcome string wymagany

  denied lub attempted.

• reason string opcjonalny

  Kod przyczyny zapisany małymi literami w formacie snake_case, do 64 znaków. Wymagany, gdy outcome ma wartość denied. Przykład: membership_expired.

• reason_display_text string opcjonalny

  Czytelny opis przyczyny, do 256 znaków. Przykład: Membership expired on 2026-04-01.

• member_id string opcjonalny

  Identyfikator członka u partnera. Pomiń go, gdy poświadczenie nie pasowało do żadnego członka, np. w przypadku nieznanej karty.

• user_email string opcjonalny

  Adres e-mail osoby, która próbowała uzyskać dostęp.

• timestamp string opcjonalny

  Czas próby w formacie ISO 8601 ze strefą czasową. Przykład: 2026-05-18T10:15:30Z. Domyślnie jest to czas otrzymania żądania. Nie może wypadać więcej niż 5 minut w przyszłości ani być starszy niż 30 dni.

• idempotency_key string opcjonalny

  Klucz chroniący przed ponownym odtworzeniem, do 128 znaków. Ponowne użycie tego samego klucza dla tego samego partnera, obiektu i drzwi zwraca pierwotny wynik.

Zwracane wartości

Zwraca 201, gdy zdarzenie zostanie zarejestrowane. Ponowne przesłanie tego samego idempotency_key zwraca 200 z polem idempotent ustawionym na true i nie tworzy kolejnego zdarzenia.

Klucz dry-run zwraca 200 z polem dry_run ustawionym na true. Nic nie jest rejestrowane.

Typowe błędy:

• 400 — treść żądania jest nieprawidłowa, odmowa nie ma reason, znacznik czasu jest poza dozwolonym zakresem lub facility_id / linking_identifier nie pasuje do połączonego obiektu.
• 403 — klucz jest tylko do odczytu.
• 403 integration_not_enabled — Twoja integracja nie jest włączona dla obiektu. Przyczynę podaje pole message.
• 404 — nie znaleziono kontrolera drzwi/bramy dla połączonego obiektu.

Żądanie

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"
  }'

Odpowiedź

{
  "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"
}

Ponowne odtworzenie idempotentne

{
  "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
}