Registrar uma tentativa ou negação de acesso

Registra uma tentativa ou negação de acesso que o seu sistema já decidiu. O Door/Gate Controller não é contatado e a porta não é destravada.

Use isto quando o seu sistema recusar a entrada ou quando uma tentativa precisar aparecer nos Registros de acesso do Door & Gate Access sem um destravamento. O Performance Hub não avalia o status da associação, os horários de acesso nem outras regras de acesso.

Um evento negado aparece nos Registros de acesso do Door & Gate Access com o resultado Denied, o nome do seu parceiro, a porta, o identificador do membro (quando você o envia) e o código do motivo em formato legível. Por exemplo, membership_expired é exibido como "Membership Expired". reason_display_text e user_email são armazenados com o evento.

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.

• outcome string obrigatório

  denied ou attempted.

• reason string opcional

  Código do motivo em snake_case minúsculo, com até 64 caracteres. Obrigatório quando outcome é denied. Exemplo: membership_expired.

• reason_display_text string opcional

  Motivo legível, com até 256 caracteres. Exemplo: Membership expired on 2026-04-01.

• member_id string opcional

  ID do membro no sistema do parceiro. Omita-o quando a credencial não corresponder a um membro, como no caso de um cartão desconhecido.

• user_email string opcional

  E-mail da pessoa que tentou o acesso.

• timestamp string opcional

  Quando a tentativa ocorreu, em ISO 8601 com fuso horário. Exemplo: 2026-05-18T10:15:30Z. O padrão é o horário em que a solicitação é recebida. Não pode estar mais de 5 minutos no futuro nem ser anterior a 30 dias.

• idempotency_key string opcional

  Chave de proteção contra repetição, com até 128 caracteres. Reutilizar a mesma chave para o mesmo parceiro, instalação e porta retorna o resultado original.

Retorno

Retorna 201 quando o evento é registrado. Repetir o mesmo idempotency_key retorna 200 com idempotent definido como true e não cria outro evento.

Uma chave dry-run retorna 200 com dry_run definido como true. Nada é registrado.

Falhas comuns:

• 400 - o corpo é inválido, uma negação não tem reason, o carimbo de data/hora está fora do intervalo ou facility_id / linking_identifier não corresponde a uma instalação vinculada.
• 403 - a chave é somente leitura.
• 403 integration_not_enabled - sua integração não está ativada para a instalação. message informa o motivo.
• 404 - o Door/Gate Controller não foi encontrado para a instalação vinculada.

Solicitação

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

Resposta

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

Repetição 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
}