Destravar um Door/Gate Controller

Envia um comando de destravamento ao Door/Gate Controller e aguarda a confirmação do relé físico de que ele foi destravado.

Seu sistema deve decidir se a pessoa está autorizada antes de chamar este endpoint. O Performance Hub verifica apenas a chave do parceiro, o acesso à instalação, a quem a porta pertence e o estado do dispositivo.

Parâmetros

• door_id string obrigatório

  ID do Door/Gate Controller retornado pelo endpoint de listagem.

• facility_id string um ou outroInforme o tipo de identificador de instalação configurado para sua integração: use facility_id em integrações de vinculação direta ou linking_identifier em integrações com identificador de vinculação. Não envie os dois; a API usa o tipo de identificador configurado para sua conta de parceiro e ignora o outro. Saiba mais

  ID da instalação no Performance Hub. Obrigatório em integrações de vinculação direta.

• linking_identifier string um ou outroInforme o tipo de identificador de instalação configurado para sua integração: use facility_id em integrações de vinculação direta ou linking_identifier em integrações com identificador de vinculação. Não envie os dois; a API usa o tipo de identificador configurado para sua conta de parceiro e ignora o outro. Saiba mais

  Identificador da instalação no sistema do parceiro. Obrigatório em integrações com identificador de vinculação.

• member_id string obrigatório

  ID do membro no sistema do parceiro. É usado para registros de auditoria e para a vinculação posterior de dados.

• first_name string obrigatório

  Nome da pessoa que está abrindo a porta.

• last_name string obrigatório

  Sobrenome da pessoa que está abrindo a porta.

• full_name string opcional

  Opcional. Se omitido, o Performance Hub combina first_name e last_name.

• check_in_id string opcional

  ID de check-in opcional do seu sistema, para correlação.

• idempotency_key string opcional

  Chave opcional de proteção contra repetição. Reutilizar a mesma chave para o mesmo parceiro, instalação e porta retorna o resultado existente, quando disponível.

Retorno

Retorna 200 somente quando o dispositivo confirma que o relé foi fisicamente destravado. A porta usa o tempo de abertura configurado no Gerenciamento de dispositivos do Performance Hub; os parceiros não podem substituir o tempo do relé por solicitação. A maioria das confirmações deve ser concluída em 3-5 segundos. Trate o tempo limite documentado como uma falha explícita de destravamento e tente novamente somente de acordo com as suas próprias regras de segurança.

Falhas comuns:

• 403 integration_not_enabled - sua integração não está ativada para a instalação.
• 409 maintenance_mode_active - a equipe da instalação ativou o modo de manutenção para a porta.
• 503 device_offline - o Door/Gate Controller está off-line ou desatualizado.
• 504 unlock_confirmation_timeout - o comando foi enviado, mas nenhuma confirmação correspondente foi recebida antes do tempo limite.

Solicitação

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

Resposta

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

Resposta de falha

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