Desbloquear un controlador de puertas y portones

Envía un comando de desbloqueo al controlador de puertas y portones y espera a que el relé físico confirme que se desbloqueó.

Tu sistema debe decidir si la persona está autorizada antes de llamar a este endpoint. El Performance Hub solo verifica la clave de socio, el acceso a la instalación, la pertenencia de la puerta y el estado del dispositivo.

Parámetros

• door_id string obligatorio

  ID del controlador de puertas y portones que devuelve el endpoint de lista.

• facility_id string uno u otroIndica el tipo de identificador de instalación configurado para tu integración: usa facility_id en las integraciones de vinculación directa o linking_identifier en las integraciones con identificador de vinculación. No envíes ambos; la API usa el tipo de identificador configurado para tu cuenta de socio e ignora el otro. Más información

  ID de instalación del Performance Hub. Obligatorio en las integraciones de vinculación directa.

• linking_identifier string uno u otroIndica el tipo de identificador de instalación configurado para tu integración: usa facility_id en las integraciones de vinculación directa o linking_identifier en las integraciones con identificador de vinculación. No envíes ambos; la API usa el tipo de identificador configurado para tu cuenta de socio e ignora el otro. Más información

  Identificador de instalación del socio. Obligatorio en las integraciones con identificador de vinculación.

• member_id string obligatorio

  ID del miembro en el sistema del socio. Se usa para los registros de auditoría y para vincular datos más adelante.

• first_name string obligatorio

  Nombre de la persona que abre la puerta.

• last_name string obligatorio

  Apellido de la persona que abre la puerta.

• full_name string opcional

  Opcional. Si se omite, el Performance Hub combina first_name y last_name.

• check_in_id string opcional

  ID opcional del registro de entrada en tu sistema, para relacionar los datos.

• idempotency_key string opcional

  Clave opcional de protección contra repeticiones. Si reutilizas la misma clave para el mismo socio, la misma instalación y la misma puerta, se devuelve el resultado existente cuando está disponible.

Valor devuelto

Devuelve 200 solo cuando el dispositivo confirma que el relé se desbloqueó físicamente. La puerta usa el tiempo de apertura configurado en Gestión de dispositivos del Performance Hub; los socios no pueden anular la temporización del relé en cada solicitud. La mayoría de las confirmaciones deberían completarse en 3-5 segundos. Trata el tiempo de espera documentado como un desbloqueo fallido explícito y reintenta solo según tus propias reglas de seguridad.

Errores comunes:

• 403 integration_not_enabled: tu integración no está habilitada para la instalación.
• 409 maintenance_mode_active: el personal de la instalación activó el modo de mantenimiento para la puerta.
• 503 device_offline: el controlador de puertas y portones está desconectado o sus datos están desactualizados.
• 504 unlock_confirmation_timeout: el comando se envió, pero no se recibió una confirmación correspondiente antes del tiempo de espera.

Solicitud

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

Respuesta

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

Respuesta de error

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