Sbloccare un Door/Gate Controller

Invia un comando di sblocco al Door/Gate Controller e attende che il relè fisico confermi lo sblocco.

Il tuo sistema deve decidere se la persona è autorizzata prima di chiamare questo endpoint. Il Performance Hub verifica solo la chiave partner, l'accesso alla struttura, l'appartenenza della porta e lo stato del dispositivo.

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.

• member_id string obbligatorio

  ID del membro nel sistema del partner. Viene usato per la registrazione di audit e per il successivo collegamento dei dati.

• first_name string obbligatorio

  Nome della persona che apre la porta.

• last_name string obbligatorio

  Cognome della persona che apre la porta.

• full_name string facoltativo

  Facoltativo. Se omesso, il Performance Hub combina first_name e last_name.

• check_in_id string facoltativo

  ID facoltativo del check-in nel tuo sistema, per la correlazione.

• idempotency_key string facoltativo

  Chiave facoltativa di protezione dalla ripetizione. Riutilizzando la stessa chiave per lo stesso partner, la stessa struttura e la stessa porta si ottiene il risultato esistente, se disponibile.

Valore restituito

Restituisce 200 solo quando il dispositivo conferma che il relè si è fisicamente sbloccato. La porta usa il tempo di mantenimento configurato in Gestione dei dispositivi del Performance Hub; i partner non possono modificare i tempi del relè per singola richiesta. La maggior parte delle conferme dovrebbe arrivare entro 3-5 secondi. Considera il timeout documentato come uno sblocco esplicitamente non riuscito e ripeti il tentativo solo secondo le tue regole di sicurezza.

Errori comuni:

• 403 integration_not_enabled - la tua integrazione non è attivata per la struttura.
• 409 maintenance_mode_active - il personale della struttura ha attivato la modalità di manutenzione per la porta.
• 503 device_offline - il Door/Gate Controller è offline o non aggiornato.
• 504 unlock_confirmation_timeout - il comando è stato inviato, ma non è stata ricevuta alcuna conferma corrispondente prima del timeout.

Richiesta

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/unlock \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "member_id": "mem_12345",
    "first_name": "Jane",
    "last_name": "S.",
    "full_name": "Jane S.",
    "source": "door_reader",
    "idempotency_key": "unlock_20260501_0001"
  }'

Risposta

{
  "status": "unlocked",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "command_id": "00000000-0000-0000-0000-000000000049",
  "hold_time_seconds": 10,
  "confirmed_at": "2026-05-01T04:30:00.000Z"
}

Risposta di errore

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}