Control de acceso - Documentación para desarrolladores de Rhombus

Nota

Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, escríbenos.

Descripción general

El control de acceso de Rhombus te permite administrar la entrada física en todas tus instalaciones desde una sola API. Las puertas con control de acceso están respaldadas por controladores de puerta y lectores de Rhombus, y cada desbloqueo, credencial y concesión está vinculado a la misma plataforma que registra las imágenes de tus cámaras, de modo que cada evento de entrada tiene contexto visual.

A través de la API, puedes:

Listar puertas con control de acceso e inspeccionar su configuración y estado en vivo
Desbloquear de forma remota una puerta para una entrada momentánea
Emitir credenciales (como tarjetas Wiegand) y asignarlas a usuarios
Crear grupos y concesiones de acceso que vinculan usuarios, puertas y horarios
Activar planes de confinamiento para asegurar una ubicación durante una emergencia

Nota

¿Buscas entrada táctil para visitantes? La guía Control de acceso con código QR (actualmente en beta) cubre la generación de códigos QR de duración limitada que una cámara de Rhombus lee para desbloquear una puerta. Esta guía cubre la superficie de control de acceso más amplia y de disponibilidad general.

Requisitos previos

Nota

Antes de comenzar, asegúrate de tener:

Una clave de API de Rhombus con permisos de control de acceso (generada en la Consola de Rhombus en Configuración → Integraciones y recursos para desarrolladores → Tokens de API)
Al menos una puerta con control de acceso configurada con un controlador de puerta y un lector de Rhombus
Los UUID de los usuarios, puertas y ubicaciones con los que planeas trabajar (puedes descubrir los UUID de las puertas con el endpoint de listado de puertas a continuación)

Todas las solicitudes son POST, apuntan a la URL base https://api2.rhombussystems.com y requieren estos encabezados:

bash

x-auth-scheme: api-token
x-auth-apikey: YOUR_API_KEY
Content-Type: application/json

Listar puertas con control de acceso

Recupera las puertas con control de acceso de tu organización. La respuesta está paginada: envía un cuerpo vacío para la primera página y luego envía el lastEvaluatedKey devuelto en las solicitudes posteriores hasta que vuelva vacío.

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/component/findAccessControlledDoors",
    headers=headers,
    json={
        "maxPageSize": 100
    }
)

data = response.json()
for door in data.get("accessControlledDoors", []):
    print(f"{door['name']} ({door['uuid']}) - estado predeterminado: {door.get('defaultState')}")

# Pagine si quedan más puertas
next_key = data.get("lastEvaluatedKey")

const response = await fetch('https://api2.rhombussystems.com/api/component/findAccessControlledDoors', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    maxPageSize: 100
  })
});

const data = await response.json();
for (const door of data.accessControlledDoors || []) {
  console.log(`${door.name} (${door.uuid}) - estado predeterminado: ${door.defaultState}`);
}

const nextKey = data.lastEvaluatedKey;

curl -X POST https://api2.rhombussystems.com/api/component/findAccessControlledDoors \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{"maxPageSize": 100}'

Parámetros de solicitud

maxPageSizeintegerpath

Número máximo de puertas a devolver en una sola página.

lastEvaluatedKeystringpath

Cursor de paginación devuelto por una llamada anterior. Omítelo en la primera solicitud; proporciónalo para obtener la siguiente página.

Respuesta

accessControlledDoorsarray

La lista de puertas con control de acceso. Campos clave por puerta:

Mostrar campos de la puerta

uuidstring

Identificador único de la puerta. Usa este valor donde se requiera un accessControlledDoorUuid.

namestring

Nombre visible de la puerta (por ejemplo, "Entrada principal").

locationUuidstring

La ubicación a la que pertenece la puerta.

defaultStatestring

Modo de acceso de referencia, uno de ACCESS_CONTROLLED o UNLOCKED.

remoteUnlockEnabledboolean

Si la puerta acepta solicitudes de desbloqueo remoto a través de la API.

unlockTimeSecinteger

Cuánto tiempo permanece desbloqueada la puerta tras un desbloqueo estándar, en segundos.

lastEvaluatedKeystring

Cursor de paginación. Cuando está presente, envíalo de nuevo en la siguiente solicitud para recuperar más puertas.

Consejo

Si solo necesitas el estado ligero de la puerta en lugar de la configuración completa, usa /api/component/findMinimalStateAccessControlledDoors, que devuelve cada puerta más una réplica de estado compacta.

Desbloquear una puerta de forma remota

Activa un desbloqueo momentáneo en una puerta con control de acceso. La puerta se vuelve a bloquear automáticamente después de su tiempo de desbloqueo configurado. El desbloqueo remoto solo funciona cuando remoteUnlockEnabled es true para la puerta de destino.

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/unlockAccessControlledDoor",
    headers=headers,
    json={
        "accessControlledDoorUuid": "YOUR_DOOR_UUID"
    }
)

result = response.json()
print(result.get("type"))  # SUCCESS o ERROR

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/unlockAccessControlledDoor', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    accessControlledDoorUuid: 'YOUR_DOOR_UUID'
  })
});

const result = await response.json();
console.log(result.type); // SUCCESS o ERROR

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/unlockAccessControlledDoor \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{"accessControlledDoorUuid": "YOUR_DOOR_UUID"}'

accessControlledDoorUuidstringpathobligatorio

El UUID de la puerta a desbloquear, del endpoint de listado de puertas.

typestring

Resultado de la solicitud, ya sea SUCCESS o ERROR.

Nota

Cada desbloqueo remoto se registra como un evento de acceso con imágenes de las cámaras asociadas a la puerta, lo que te brinda un registro de auditoría completo.

Emitir y asignar una credencial

Las credenciales son las tarjetas o llaveros físicos que acepta un lector. Este ejemplo crea una credencial Wiegand y la asigna a un usuario. Rhombus admite varios formatos de credenciales: el endpoint createWiegandCredential toma un wiegandFormat y los campos relevantes para ese formato.

Crear una credencial Wiegand

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

now_sec = int(time.time())
one_year_sec = 365 * 24 * 60 * 60

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/createWiegandCredential",
    headers=headers,
    json={
        "wiegandFormat": "H10301",
        "facilityCode": 42,
        "cardNumber": 10537,
        "userUuid": "YOUR_USER_UUID",
        "startDateEpochSecInclusive": now_sec,
        "endDateEpochSecExclusive": now_sec + one_year_sec
    }
)

credential = response.json().get("credential", {})
print(f"Credencial creada {credential.get('uuid')} - estado {credential.get('workflowStatus')}")

const nowSec = Math.floor(Date.now() / 1000);
const oneYearSec = 365 * 24 * 60 * 60;

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/createWiegandCredential', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    wiegandFormat: 'H10301',
    facilityCode: 42,
    cardNumber: 10537,
    userUuid: 'YOUR_USER_UUID',
    startDateEpochSecInclusive: nowSec,
    endDateEpochSecExclusive: nowSec + oneYearSec
  })
});

const { credential } = await response.json();
console.log(`Credencial creada ${credential.uuid} - estado ${credential.workflowStatus}`);

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/createWiegandCredential \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{
    "wiegandFormat": "H10301",
    "facilityCode": 42,
    "cardNumber": 10537,
    "userUuid": "YOUR_USER_UUID",
    "startDateEpochSecInclusive": 1712620800,
    "endDateEpochSecExclusive": 1744156800
  }'

wiegandFormatstringpathobligatorio

El formato de tarjeta Wiegand. Uno de H10301, D10202, H10304, HID_CORP1000_STD_35, HID_CORP1000_STD_48, WIEGAND_64BIT_RAW o CUSTOM. Los campos que completes dependen del formato: para el formato estándar de 26 bits H10301, proporciona facilityCode y cardNumber.

facilityCodeintegerpath

Código de instalación (sitio) codificado en la tarjeta. Usado por formatos como H10301.

cardNumberintegerpath

Número de tarjeta codificado en la tarjeta.

siteCodeintegerpath

Código de sitio, usado por formatos que lo codifican por separado del código de instalación.

companyIdintegerpath

ID de empresa, usado por los formatos HID Corporate 1000.

valuestringpath

Valor de credencial sin procesar. Usado por los formatos WIEGAND_64BIT_RAW y CUSTOM.

userUuidstringpath

El usuario al que pertenece la credencial. Cuando se establece, la credencial se crea ya asignada a ese usuario.

startDateEpochSecInclusiveintegerpath

Inicio de la ventana de validez de la credencial, en segundos epoch (inclusivo).

endDateEpochSecExclusiveintegerpath

Fin de la ventana de validez de la credencial, en segundos epoch (exclusivo).

Advertencia

Las fechas de validez de la credencial se expresan en segundos epoch, no en milisegundos. La mayoría de los demás endpoints de Rhombus usan milisegundos epoch, así que convierte con cuidado.

La respuesta devuelve el objeto credential creado, incluyendo su uuid, lowercaseHexValue y workflowStatus (ACTIVE, UNASSIGNED, SUSPENDED o REVOKED).

Asignar una credencial existente a un usuario

Si una credencial ya existe (por ejemplo, se creó sin asignar), asígnala a un usuario por su valor hexadecimal.

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/assignAccessControlCredential",
    headers=headers,
    json={
        "credentialHexValue": "002a2929",
        "userUuid": "YOUR_USER_UUID"
    }
)
print(response.json())

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/assignAccessControlCredential', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    credentialHexValue: '002a2929',
    userUuid: 'YOUR_USER_UUID'
  })
});
console.log(await response.json());

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/assignAccessControlCredential \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{
    "credentialHexValue": "002a2929",
    "userUuid": "YOUR_USER_UUID"
  }'

credentialHexValuestringpathobligatorio

El valor hexadecimal de la credencial a asignar.

userUuidstringpathobligatorio

El usuario al que asignar la credencial.

Consejo

Administra el ciclo de vida de una credencial con /api/accesscontrol/suspendAccessControlCredential, /api/accesscontrol/unsuspendAccessControlCredential y /api/accesscontrol/revokeAccessControlCredential. Para revisar las credenciales de un usuario, llama a /api/accesscontrol/findAccessControlCredentialByUser con su userUuid.

Otorgar acceso con grupos y horarios

Rhombus modela "quién puede abrir qué puertas y cuándo" como una concesión de acceso. Una concesión vincula un conjunto de usuarios (directamente o a través de grupos de acceso) con un conjunto de puertas, opcionalmente restringido por un horario. El flujo típico es: crear un grupo, agregar usuarios y luego crear una concesión que vincule el grupo con puertas y un horario.

Crear un grupo de acceso y agregar usuarios

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Crear el grupo
create = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/createAccessControlGroup",
    headers=headers,
    json={
        "name": "Personal de almacén",
        "description": "Empleados con acceso permitido al almacén"
    }
)
group_uuid = create.json()["group"]["uuid"]

# Agregar usuarios a él
requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/addUsersToAccessControlGroup",
    headers=headers,
    json={
        "groupUuid": group_uuid,
        "userUuids": ["USER_UUID_1", "USER_UUID_2"]
    }
)

const headers = {
  'Content-Type': 'application/json',
  'x-auth-scheme': 'api-token',
  'x-auth-apikey': 'YOUR_API_KEY'
};

// Crear el grupo
const create = await fetch('https://api2.rhombussystems.com/api/accesscontrol/createAccessControlGroup', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Personal de almacén',
    description: 'Empleados con acceso permitido al almacén'
  })
});
const groupUuid = (await create.json()).group.uuid;

// Agregar usuarios a él
await fetch('https://api2.rhombussystems.com/api/accesscontrol/addUsersToAccessControlGroup', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    groupUuid,
    userUuids: ['USER_UUID_1', 'USER_UUID_2']
  })
});

# 1. Crear el grupo
curl -X POST https://api2.rhombussystems.com/api/accesscontrol/createAccessControlGroup \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{"name": "Personal de almacén", "description": "Empleados con acceso permitido al almacén"}'

# 2. Agregar usuarios (usa el uuid del grupo de la respuesta anterior)
curl -X POST https://api2.rhombussystems.com/api/accesscontrol/addUsersToAccessControlGroup \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{"groupUuid": "GROUP_UUID", "userUuids": ["USER_UUID_1", "USER_UUID_2"]}'

namestringpathobligatorio

Nombre del grupo de acceso.

descriptionstringpath

Descripción opcional del grupo.

userUuidsarraypath

Lista opcional de UUID de usuarios con los que inicializar el grupo al momento de la creación. También puedes agregar miembros más tarde con addUsersToAccessControlGroup.

(Opcional) Crear un horario semanal

Para restringir una concesión a horas específicas, primero crea un horario y haz referencia a su UUID en la concesión. Los horarios semanales usan la estrategia WEEKLY_REPEATING_MINUTES.

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/schedule/createWeeklySchedule",
    headers=headers,
    json={
        "schedule": {
            "name": "Horario laboral",
            "strategy": "WEEKLY_REPEATING_MINUTES"
        }
    }
)
schedule_uuid = response.json().get("scheduleUuid")
print(schedule_uuid)

const response = await fetch('https://api2.rhombussystems.com/api/schedule/createWeeklySchedule', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    schedule: {
      name: 'Horario laboral',
      strategy: 'WEEKLY_REPEATING_MINUTES'
    }
  })
});
const { scheduleUuid } = await response.json();
console.log(scheduleUuid);

curl -X POST https://api2.rhombussystems.com/api/schedule/createWeeklySchedule \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{"schedule": {"name": "Horario laboral", "strategy": "WEEKLY_REPEATING_MINUTES"}}'

La respuesta devuelve un scheduleUuid. Usa /api/schedule/getSchedules y /api/schedule/getScheduleDataV2 para revisar los horarios, y administra los intervalos de tiempo semanales detallados en la Consola de Rhombus.

Crear la concesión de acceso

Vincula el grupo, las puertas y (opcionalmente) un horario. Usa el modo DEFAULT para una concesión de acceso estándar.

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/createAccessGrant",
    headers=headers,
    json={
        "accessGrant": {
            "name": "Personal de almacén - Horario laboral",
            "locationUuid": "YOUR_LOCATION_UUID",
            "mode": "DEFAULT",
            "groupUuids": ["GROUP_UUID"],
            "accessControlledDoorUuids": ["DOOR_UUID_1", "DOOR_UUID_2"],
            "scheduleUuid": "SCHEDULE_UUID"
        }
    }
)

data = response.json()
if data.get("error"):
    print("Error:", data.get("errorMsg"))
else:
    print("Concesión creada:", data["accessGrant"]["uuid"])

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/createAccessGrant', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    accessGrant: {
      name: 'Personal de almacén - Horario laboral',
      locationUuid: 'YOUR_LOCATION_UUID',
      mode: 'DEFAULT',
      groupUuids: ['GROUP_UUID'],
      accessControlledDoorUuids: ['DOOR_UUID_1', 'DOOR_UUID_2'],
      scheduleUuid: 'SCHEDULE_UUID'
    }
  })
});

const data = await response.json();
if (data.error) {
  console.error('Error:', data.errorMsg);
} else {
  console.log('Concesión creada:', data.accessGrant.uuid);
}

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/createAccessGrant \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{
    "accessGrant": {
      "name": "Personal de almacén - Horario laboral",
      "locationUuid": "YOUR_LOCATION_UUID",
      "mode": "DEFAULT",
      "groupUuids": ["GROUP_UUID"],
      "accessControlledDoorUuids": ["DOOR_UUID_1", "DOOR_UUID_2"],
      "scheduleUuid": "SCHEDULE_UUID"
    }
  }'

accessGrant.namestringpath

Nombre legible para la concesión.

accessGrant.locationUuidstringpath

La ubicación a la que se aplica la concesión.

accessGrant.modestringpath

Modo de concesión, uno de DEFAULT o GUEST_PASS_INDIVIDUAL. Usa DEFAULT para el acceso estándar de empleados.

accessGrant.groupUuidsarraypath

Grupos de acceso cuyos miembros reciben acceso. Combínalo con userUuids para otorgar acceso a usuarios individuales directamente.

accessGrant.userUuidsarraypath

Usuarios individuales a los que otorgar acceso, además de cualquier grupo.

accessGrant.accessControlledDoorUuidsarraypath

Las puertas que abre esta concesión. También puedes apuntar a puertas por etiqueta con doorLabelIds.

accessGrant.scheduleUuidstringpath

Horario opcional que restringe cuándo está activa la concesión. Omítelo para acceso 24/7.

accessGrantobject

La concesión creada, incluyendo su uuid generado.

errorboolean

true si la concesión no se pudo crear. Consulta errorMsg para más detalles y warningMsg para notas no fatales.

Activar un plan de confinamiento

Los planes de confinamiento te permiten cambiar instantáneamente el estado de acceso de muchas puertas en una ubicación durante una emergencia. Primero lista los planes configurados para tu organización y luego activa uno o más para una ubicación.

Buscar planes de confinamiento disponibles

import requests

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/findLockdownPlans",
    headers=headers,
    json={}
)
for plan in response.json().get("lockdownPlans", []):
    print(f"{plan.get('name')}: {plan.get('uuid')}")

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/findLockdownPlans', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({})
});
for (const plan of (await response.json()).lockdownPlans || []) {
  console.log(`${plan.name}: ${plan.uuid}`);
}

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/findLockdownPlans \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{}'

Activar el confinamiento para una ubicación

import requests
import time

headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/activateLockdownForLocation",
    headers=headers,
    json={
        "locationUuid": "YOUR_LOCATION_UUID",
        "lockdownPlanUuids": ["LOCKDOWN_PLAN_UUID"],
        "stateUpdatedAtMillis": int(time.time() * 1000)
    }
)

data = response.json()
print("Resultado:", data.get("result"))
print("Estado de la ubicación:", data.get("state", {}).get("state"))

const response = await fetch('https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/activateLockdownForLocation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-auth-scheme': 'api-token',
    'x-auth-apikey': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    locationUuid: 'YOUR_LOCATION_UUID',
    lockdownPlanUuids: ['LOCKDOWN_PLAN_UUID'],
    stateUpdatedAtMillis: Date.now()
  })
});

const data = await response.json();
console.log('Resultado:', data.result);
console.log('Estado de la ubicación:', data.state?.state);

curl -X POST https://api2.rhombussystems.com/api/accesscontrol/lockdownPlan/activateLockdownForLocation \
  -H "Content-Type: application/json" \
  -H "x-auth-scheme: api-token" \
  -H "x-auth-apikey: YOUR_API_KEY" \
  -d '{
    "locationUuid": "YOUR_LOCATION_UUID",
    "lockdownPlanUuids": ["LOCKDOWN_PLAN_UUID"],
    "stateUpdatedAtMillis": 1712707200000
  }'

locationUuidstringpathobligatorio

La ubicación a poner en confinamiento.

lockdownPlanUuidsarraypathobligatorio

Los planes de confinamiento a activar. Usa los UUID de findLockdownPlans.

stateUpdatedAtMillisintegerpathobligatorio

La marca de tiempo actual del estado de confinamiento en milisegundos epoch, usada para concurrencia optimista. Envía la hora actual al iniciar un confinamiento.

resultstring

Resultado de la activación, uno de SUCCESS, INVALID_LOCKDOWN_PLANS u OPTIMISTIC_CONCURRENCY.

stateobject

El estado de confinamiento resultante de la ubicación, incluyendo state (STANDARD_SECURITY o LOCKED_DOWN) y la lista de activeLockdownPlans.

Advertencia

Activar un confinamiento cambia el acceso físico en la ubicación de inmediato. Prueba tu integración con /api/accesscontrol/lockdownPlan/enableLockdownTestModeForLocation antes de usarla en producción, y finaliza un confinamiento con /api/accesscontrol/lockdownPlan/deactivateLockdownForLocation.

Casos de uso

Entrada remota para visitantes

Permite que el software de recepción desbloquee una puerta bajo demanda cuando se verifica a un visitante, con imágenes de cámara adjuntas a cada desbloqueo.

Incorporación automatizada

Aprovisiona la credencial y la membresía de grupo de un nuevo empleado desde tu sistema de RR. HH. para que su acceso esté listo desde el primer día.

Ventanas de tiempo para contratistas

Emite credenciales con fechas explícitas de inicio y fin, y restringe el acceso al horario laboral con un horario.

Confinamiento de emergencia

Conecta un botón de pánico o un sistema de seguridad para activar un plan de confinamiento en toda una ubicación con una sola llamada a la API.

Solución de problemas

El desbloqueo remoto devuelve ERROR

Confirma que la puerta tenga remoteUnlockEnabled establecido en true en la respuesta del listado de puertas, que el accessControlledDoorUuid sea correcto y que tu clave de API tenga permisos de control de acceso. Las puertas que están fuera de línea no se pueden desbloquear de forma remota.

La credencial se crea pero se deniega el acceso

Crear y asignar una credencial no es suficiente por sí solo: el usuario también debe estar cubierto por una concesión de acceso que incluya la puerta de destino. Verifica que una concesión DEFAULT vincule al usuario (directamente o a través de un grupo) con la puerta, y que cualquier horario adjunto esté actualmente activo. Confirma también que el workflowStatus de la credencial sea ACTIVE y que la hora actual esté dentro de su ventana de inicio/fin.

Las fechas de validez de la credencial se comportan de forma inesperada

startDateEpochSecInclusive y endDateEpochSecExclusive usan segundos epoch, no milisegundos. Si una credencial expira de inmediato o nunca se activa, comprueba que no hayas pasado un valor en milisegundos.

La activación del confinamiento devuelve OPTIMISTIC_CONCURRENCY

El estado de confinamiento de la ubicación cambió entre tu lectura y tu escritura. Vuelve a obtener el estado actual (por ejemplo, con getOrCreateLocationLockdownState) y luego reintenta la activación con un stateUpdatedAtMillis actualizado.

La respuesta de la concesión de acceso tiene error establecido en true

Inspecciona errorMsg en la respuesta. Las causas comunes son hacer referencia a una puerta que no tiene una licencia de control de acceso disponible (consulta unassignedACDLicensesDoorUuids y expiredACDLicensesDoorUuids en la respuesta) o un locationUuid no válido.

Próximos pasos

Control de acceso con código QR

Agrega entrada táctil con código QR autenticada por cámara para visitantes y eventos (beta).

Notificaciones por webhook

Recibe eventos de acceso en tiempo real para que tu aplicación pueda reaccionar en el momento en que se usa una puerta.

Referencia de la API

Explora los esquemas completos de solicitud y respuesta para cada endpoint de control de acceso.