Registrare un tentativo di accesso o un rifiuto

Registra un tentativo di accesso o un rifiuto già deciso dal tuo sistema. Il Door/Gate Controller non viene contattato e la porta non si sblocca.

Usa questa chiamata quando il tuo sistema rifiuta l'ingresso o quando un tentativo deve comparire nei Registri di accesso di Door & Gate Access senza uno sblocco. Il Performance Hub non valuta lo stato dell'abbonamento, gli orari di accesso o altre regole di accesso.

Un evento rifiutato compare nei Registri di accesso di Door & Gate Access con l'esito Denied, il nome del tuo partner, la porta, l'identificatore del membro se lo invii e il codice del motivo in forma leggibile. Ad esempio, membership_expired viene mostrato come "Membership Expired". reason_display_text e user_email vengono salvati con l'evento.

Parametri

• door_id string obbligatorio

  ID del Door/Gate Controller restituito dall'endpoint di elenco.

• facility_id string in alternativaIndica il tipo di identificatore della struttura configurato per la tua integrazione: usa facility_id per le integrazioni con collegamento diretto oppure linking_identifier per le integrazioni con identificatore di collegamento. Non inviarli entrambi: l'API usa il tipo di identificatore configurato per il tuo account partner e ignora l'altro. Scopri di più

  ID della struttura nel Performance Hub. Obbligatorio per le integrazioni con collegamento diretto.

• linking_identifier string in alternativaIndica il tipo di identificatore della struttura configurato per la tua integrazione: usa facility_id per le integrazioni con collegamento diretto oppure linking_identifier per le integrazioni con identificatore di collegamento. Non inviarli entrambi: l'API usa il tipo di identificatore configurato per il tuo account partner e ignora l'altro. Scopri di più

  Identificatore della struttura del partner. Obbligatorio per le integrazioni con identificatore di collegamento.

• outcome string obbligatorio

  denied o attempted.

• reason string facoltativo

  Codice del motivo in snake_case minuscolo, fino a 64 caratteri. Obbligatorio quando outcome è denied. Esempio: membership_expired.

• reason_display_text string facoltativo

  Motivo in forma leggibile, fino a 256 caratteri. Esempio: Membership expired on 2026-04-01.

• member_id string facoltativo

  ID del membro nel sistema del partner. Omettilo quando la credenziale non corrisponde a nessun membro, ad esempio nel caso di una tessera sconosciuta.

• user_email string facoltativo

  Email della persona che ha tentato l'accesso.

• timestamp string facoltativo

  Momento in cui è avvenuto il tentativo, in formato ISO 8601 con fuso orario. Esempio: 2026-05-18T10:15:30Z. Il valore predefinito è l'ora di ricezione della richiesta. Non può essere più di 5 minuti nel futuro né più vecchio di 30 giorni.

• idempotency_key string facoltativo

  Chiave di protezione dalla ripetizione, fino a 128 caratteri. Riutilizzando la stessa chiave per lo stesso partner, la stessa struttura e la stessa porta si ottiene il risultato originale.

Valore restituito

Restituisce 201 quando l'evento viene registrato. Ripetendo la richiesta con la stessa idempotency_key si ottiene 200 con idempotent impostato su true e non viene creato un altro evento.

Una chiave dry-run restituisce 200 con dry_run impostato su true. Non viene registrato nulla.

Errori comuni:

• 400 - il corpo non è valido, un rifiuto non ha un reason, il timestamp è fuori intervallo oppure facility_id / linking_identifier non corrisponde a una struttura collegata.
• 403 - la chiave è di sola lettura.
• 403 integration_not_enabled - la tua integrazione non è attivata per la struttura. message indica il motivo.
• 404 - il Door/Gate Controller non è stato trovato per la struttura collegata.

Richiesta

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

Risposta

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

Ripetizione idempotente

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