Registrar un intento de acceso o una denegación

Registra un intento de acceso o una denegación que tu sistema ya decidió. No se contacta con el controlador de puertas y portones y la puerta no se desbloquea.

Usa este endpoint cuando tu sistema rechace la entrada o cuando un intento deba aparecer en los registros de acceso de Door & Gate Access sin un desbloqueo. El Performance Hub no evalúa el estado de la membresía, los horarios de acceso ni otras reglas de acceso.

Un evento denegado aparece en los registros de acceso de Door & Gate Access con el resultado Denied, el nombre de tu empresa asociada, la puerta, el identificador del miembro si lo envías y el código de motivo en formato legible. Por ejemplo, membership_expired se muestra como "Membership Expired". reason_display_text y user_email se guardan con el evento.

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.

• outcome string obligatorio

  denied o attempted.

• reason string opcional

  Código de motivo en snake_case y minúsculas, de hasta 64 caracteres. Obligatorio cuando outcome es denied. Ejemplo: membership_expired.

• reason_display_text string opcional

  Motivo legible, de hasta 256 caracteres. Ejemplo: Membership expired on 2026-04-01.

• member_id string opcional

  ID del miembro en el sistema del socio. Omítelo cuando la credencial no coincidió con ningún miembro, por ejemplo, una tarjeta desconocida.

• user_email string opcional

  Correo electrónico de la persona que intentó acceder.

• timestamp string opcional

  Momento en que ocurrió el intento, en formato ISO 8601 con zona horaria. Ejemplo: 2026-05-18T10:15:30Z. Si se omite, se usa la hora en que se recibe la solicitud. No puede estar más de 5 minutos en el futuro ni tener más de 30 días de antigüedad.

• idempotency_key string opcional

  Clave de protección contra repeticiones, de hasta 128 caracteres. Si reutilizas la misma clave para el mismo socio, la misma instalación y la misma puerta, se devuelve el resultado original.

Valor devuelto

Devuelve 201 cuando se registra el evento. Si repites la misma idempotency_key, se devuelve 200 con idempotent establecido en true y no se crea otro evento.

Una clave de prueba (dry-run) devuelve 200 con dry_run establecido en true. No se registra nada.

Errores comunes:

• 400: el cuerpo no es válido, una denegación no tiene reason, la marca de tiempo está fuera del rango o facility_id / linking_identifier no coincide con una instalación vinculada.
• 403: la clave es de solo lectura.
• 403 integration_not_enabled: tu integración no está habilitada para la instalación. message indica el motivo.
• 404: no se encontró el controlador de puertas y portones en la instalación vinculada.

Solicitud

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

Respuesta

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

Repetición 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
}