> ## Índice de la documentación
> Consulta el índice completo de la documentación en: https://developer.rhombus.com/llms.txt
> Úsalo para descubrir todas las páginas disponibles antes de seguir explorando.

# Control de acceso con QR Code

> Implementa desbloqueo de puertas con QR Code y control de acceso de Rhombus: genera credenciales de visitante y activa entradas sin contacto vía API.

> **Note**: Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, [escríbenos](mailto:support@rhombus.com).

> **Warning**: Esta funcionalidad se encuentra actualmente en **beta** y no está disponible para todos los clientes. Las funcionalidades y características pueden cambiar. Para solicitar acceso, contacta a tu representante de Rhombus o escribe a <support@rhombus.com>.

## Descripción general

El desbloqueo con QR Code permite que los usuarios autorizados ingresen presentando un QR Code a una cámara de seguridad de Rhombus o a un controlador de puerta DR40. La cámara reconoce el código, lo valida contra el backend de Rhombus y desbloquea la puerta de inmediato cuando está autorizado.

Esta implementación ofrece un método rápido, seguro y autenticado por cámara para controlar el acceso sin requerir tarjetas físicas, gafetes ni aplicaciones móviles.

## Cómo funciona

1. **Genera un QR Code mediante la API**

   Un administrador o un sistema integrado genera un QR Code seguro y con vigencia limitada usando la API de Rhombus. El código se devuelve como una cadena base64 que puede convertirse en imagen.

2. **El usuario presenta el QR Code**

   El usuario muestra el QR Code en su dispositivo móvil o en material impreso y lo presenta ante una cámara de Rhombus asignada a la puerta.

3. **La cámara autentica y desbloquea**

   La cámara lee y valida el QR Code contra el backend de Rhombus. Si está autorizado y dentro de la ventana de tiempo válida, la puerta se desbloquea automáticamente.

4. **Registro de eventos**

   Cada evento de desbloqueo se registra con evidencia visual de la cámara, lo que proporciona una pista de auditoría completa de los intentos de acceso.

## Casos de uso

El desbloqueo con QR Code es ideal para diversos escenarios de control de acceso:

- **Visitantes en oficinas**: Otorga acceso por un día o por tiempo limitado a visitantes sin necesidad de emitir gafetes físicos.
- **Operaciones de campo**: Envía QR Codes a técnicos o contratistas para acceso temporal a áreas específicas.
- **Edificios multi-tenant**: Emite códigos específicos por tenant con duraciones personalizadas para distintos niveles de acceso.
- **Entregas y ventanas de acceso**: Programa accesos durante horarios de entrega específicos con QR Codes con tiempo limitado.

## Requisitos previos

Antes de implementar el control de acceso con QR Code, asegúrate de tener:

- Una cuenta activa de Rhombus con acceso a la API
- Una clave de API válida desde la [Consola de Rhombus](https://console.rhombussystems.com/settings/integrations/api-tokens/)
- Al menos una cámara de Rhombus o un controlador de puerta DR40 configurado para control de acceso
- El UUID de la puerta con control de acceso que quieres administrar

> **Tip**: Puedes encontrar los UUIDs de puertas listando todas las puertas con control de acceso de tu organización con el endpoint [`POST /api/component/findAccessControlledDoors`](https://developer.rhombus.com/api-reference/component-webservice/find-access-controlled-doors-within-the-org) en la Referencia de la API.

## Genera un QR Access Code

Usa el endpoint `generateQRAccessCode` para crear un QR Code con tiempo limitado para acceder a una puerta.

### Solicitud a la API

```bash cURL
curl --location 'https://api2.rhombussystems.com/api/accesscontrol/qr/generateQRAccessCode' \
--header 'Accept: application/json' \
--header 'x-auth-scheme: api-token' \
--header 'x-auth-apikey: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "accessControlledDoorUuid": "door-uuid-here",
  "validDurationSec": 86400
}'
```

```python Python
import requests
import json

url = "https://api2.rhombussystems.com/api/accesscontrol/qr/generateQRAccessCode"

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

payload = {
    "accessControlledDoorUuid": "door-uuid-here",
    "validDurationSec": 86400  # 24 hours
}

response = requests.post(url, headers=headers, json=payload)
qr_code_data = response.json()
print(qr_code_data)
```

```javascript JavaScript
const axios = require('axios');

const url = 'https://api2.rhombussystems.com/api/accesscontrol/qr/generateQRAccessCode';

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

const payload = {
  accessControlledDoorUuid: 'door-uuid-here',
  validDurationSec: 86400  // 24 hours
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });
```

### Parámetros de la solicitud

- **`accessControlledDoorUuid` (path, string, required)**: El identificador único de la puerta para la cual quieres autorizar el acceso. Este UUID se obtiene del endpoint `findAccessControlledDoors`.
- **`validDurationSec` (path, integer, required)**: Tiempo en segundos durante el cual el QR Code permanecerá válido. Valores comunes:
  - `3600` - 1 hora
  - `28800` - 8 horas (jornada laboral)
  - `86400` - 24 horas
  - `604800` - 7 días
- **`auditPrincipal` (path, string)**: Etiqueta opcional que identifica a quién se emitió el QR Code (por ejemplo, el nombre del visitante). Rhombus registra este valor en los eventos de auditoría de acceso resultantes para que los desbloqueos puedan atribuirse a la persona correcta.

### Respuesta

La API devuelve una carga útil JSON que contiene los datos del QR Code como una cadena codificada en base64:

```json
{
  "qrCode": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA...",
  "accessTokenUuid": "59OcXLkFShWyHK3O2Fh2Ag"
}
```

- **`qrCode` (string)**: El QR Code como una imagen PNG, devuelta como un arreglo de bytes codificado en base64. Decodifícala para mostrar o distribuir el QR Code.
- **`accessTokenUuid` (string)**: El UUID del token de acceso generado que respalda este QR Code. Úsalo para rastrear o hacer referencia a la credencial emitida.

## Ejemplos de implementación

### Convertir QR Code a imagen

Después de recibir el QR Code en base64 desde la API, debes convertirlo a un formato de imagen visualizable.

```python Python
import base64
from PIL import Image
from io import BytesIO

# Assuming you have the qr_code_data from the API response
qr_code_base64 = qr_code_data['qrCode']

# Decode base64 to image
image_data = base64.b64decode(qr_code_base64)
image = Image.open(BytesIO(image_data))

# Save to file
image.save('access_qr_code.png')

# Or display directly
image.show()
```

```javascript Node.js
const fs = require('fs');

// Assuming you have the response from the API
const qrCodeBase64 = response.data.qrCode;

// Convert base64 to buffer and save
const imageBuffer = Buffer.from(qrCodeBase64, 'base64');
fs.writeFileSync('access_qr_code.png', imageBuffer);

console.log('QR code saved to access_qr_code.png');
```

### Enviar QR Code por correo a un visitante

Aquí tienes un ejemplo completo para generar un QR Code y enviarlo por correo electrónico a un visitante:

```python Python
import requests
import base64
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from email.mime.image import MIMEImage
import smtplib

# Generate QR code
url = "https://api2.rhombussystems.com/api/accesscontrol/qr/generateQRAccessCode"
headers = {
    "x-auth-scheme": "api-token",
    "x-auth-apikey": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "accessControlledDoorUuid": "door-uuid-here",
    "validDurationSec": 28800  # 8 hours
}

response = requests.post(url, headers=headers, json=payload)
qr_data = response.json()

# La respuesta no devuelve una marca de tiempo de expiración: derívala de validDurationSec
from datetime import datetime, timedelta, timezone
valid_until = (datetime.now(timezone.utc) + timedelta(seconds=payload['validDurationSec'])).strftime('%Y-%m-%d %H:%M UTC')

# Decode QR code image
qr_image = base64.b64decode(qr_data['qrCode'])

# Create email
msg = MIMEMultipart('related')
msg['Subject'] = 'Your Temporary Access QR Code'
msg['From'] = 'access@yourcompany.com'
msg['To'] = 'visitor@example.com'

# Email body
html = f"""
<html>
  <body>
    <h2>Welcome to Our Office</h2>
    <p>Please use the QR code below to access the building.</p>
    <p>This code is valid until {valid_until}</p>
    <p>Simply hold your phone up to the camera at the entrance.</p>
    <img src="cid:qrcode">
  </body>
</html>
"""

msg_html = MIMEText(html, 'html')
msg.attach(msg_html)

# Attach QR code image
img = MIMEImage(qr_image)
img.add_header('Content-ID', '<qrcode>')
msg.attach(img)

# Send email
smtp = smtplib.SMTP('smtp.gmail.com', 587)
smtp.starttls()
smtp.login('your-email@gmail.com', 'your-password')
smtp.send_message(msg)
smtp.quit()

print("QR code email sent successfully")
```

### Integración con un sistema de gestión de eventos

Genera QR Codes para los asistentes a un evento:

```python Python
import requests
import pandas as pd

def generate_event_access_codes(attendees_csv, door_uuid, event_duration_hours):
    """
    Generate QR codes for all event attendees

    Args:
        attendees_csv: Path to CSV with attendee information
        door_uuid: UUID of the door for event access
        event_duration_hours: How long access should be valid
    """
    # Read attendee list
    attendees = pd.read_csv(attendees_csv)

    # API configuration
    url = "https://api2.rhombussystems.com/api/accesscontrol/qr/generateQRAccessCode"
    headers = {
        "x-auth-scheme": "api-token",
        "x-auth-apikey": "YOUR_API_KEY",
        "Content-Type": "application/json"
    }

    results = []

    for _, attendee in attendees.iterrows():
        # Generate QR code for each attendee
        payload = {
            "accessControlledDoorUuid": door_uuid,
            "validDurationSec": event_duration_hours * 3600
        }

        response = requests.post(url, headers=headers, json=payload)
        qr_data = response.json()

        results.append({
            "name": attendee['name'],
            "email": attendee['email'],
            "qr_code": qr_data['qrCode'],
            "access_token_uuid": qr_data['accessTokenUuid']
        })

        print(f"Generated QR code for {attendee['name']}")

    # Save results
    results_df = pd.DataFrame(results)
    results_df.to_csv('event_qr_codes.csv', index=False)

    return results_df

# Usage
attendees = generate_event_access_codes(
    'attendees.csv',
    'door-uuid-here',
    event_duration_hours=12
)
```

## Consideraciones de seguridad

> **Warning**: Protege siempre tus QR Codes e implementa medidas de seguridad apropiadas:

### Acceso con tiempo limitado

- Establece valores apropiados de `validDurationSec` según tu caso de uso
- Duraciones más cortas (1-8 horas) para acceso de visitantes
- Duraciones más largas (1-7 días) para acceso de contratistas o empleados temporales
- Nunca configures códigos con duración ilimitada

### Distribución de QR Codes

**Distribución por correo electrónico**

Usa sistemas de correo seguros y verifica las direcciones del destinatario antes de enviar QR Codes. Considera usar correo cifrado para accesos sensibles.

**Distribución por SMS**

Verifica los números de teléfono y usa servicios SMS seguros. Ten en cuenta que el SMS puede no estar cifrado de extremo a extremo.

**Aplicaciones móviles**

Integra la generación de QR Codes en tu aplicación móvil con autenticación adecuada y verificación de usuario.

**QR Codes impresos**

Para los códigos impresos, asegura su seguridad física y deshazte de ellos correctamente tras su expiración. Considera agregar marcas de agua u otras medidas anti-copia.

### Monitoreo de accesos

- Revisa los registros de acceso regularmente usando la Consola de Rhombus
- Configura alertas para patrones de acceso inusuales
- Monitorea intentos de acceso fallidos
- Mantén pistas de auditoría sobre la generación y el uso de QR Codes

## Mejores prácticas

> **Tip**: Sigue estas mejores prácticas para un sistema de acceso con QR Code seguro y eficiente:

1. **Valida los UUIDs de puertas**: Verifica siempre los UUIDs antes de generar QR Codes para asegurarte de que otorgan acceso a las puertas correctas.

2. **Implementa límites de tasa**: Si expones la generación de QR Codes a través de tu propia aplicación, implementa rate limiting para evitar abusos.

3. **Registra eventos de generación**: Mantén registros de quién generó QR Codes, para qué puertas y con qué períodos de validez.

4. **Tiempos de expiración amigables**: Al mostrar QR Codes, presenta el tiempo de expiración en la zona horaria local del usuario.

5. **Prueba antes de distribuir**: Genera y prueba los QR Codes antes de enviarlos a los usuarios para asegurarte de que funcionan correctamente.

6. **Provee instrucciones**: Incluye instrucciones claras junto con los QR Codes sobre dónde presentarlos y qué esperar.

7. **Manejo de errores**: Implementa un manejo adecuado de errores para fallos de la API y respuestas inválidas.

## Beneficios

El acceso con QR Code permite la entrada sin contacto, funciona en cualquier smartphone y se integra con el hardware de control de acceso de Rhombus existente.

## Solución de problemas

**El QR Code no funciona**

**Causas comunes:**

- El QR Code expiró (es válido durante `validDurationSec` a partir del momento en que se generó)
- Se usó un UUID de puerta incorrecto al generar el código
- La cámara no está configurada correctamente para control de acceso
- La imagen del QR Code está dañada o poco clara

**Soluciones:**

- Genera un nuevo QR Code con una duración válida
- Verifica el UUID de la puerta usando el endpoint `findAccessControlledDoors`
- Revisa la configuración de la cámara en la Consola de Rhombus
- Asegúrate de que el QR Code se muestre claramente y a un tamaño adecuado

**La API devuelve error**

**Causas comunes:**

- Clave de API inválida o encabezados de autenticación incorrectos
- UUID de puerta incorrecto
- Puerta no configurada para acceso con QR Code
- Permisos insuficientes

**Soluciones:**

- Verifica tu clave de API en la Consola de Rhombus
- Revisa que el encabezado `x-auth-scheme` esté configurado como `api-token`
- Confirma que el UUID de la puerta exista y esté configurado para control de acceso
- Contacta al soporte de Rhombus si la funcionalidad no está habilitada para tu cuenta

**La cámara no lee el QR Code**

**Causas comunes:**

- Condiciones de iluminación deficientes
- QR Code demasiado pequeño o demasiado grande
- Ángulo de cámara incorrecto
- QR Code mostrado en una superficie reflectante

**Soluciones:**

- Asegura una iluminación adecuada en el punto de entrada
- Muestra el QR Code de 3 a 5 pulgadas de ancho
- Coloca el QR Code perpendicular a la cámara
- Evita mostrarlo en pantallas brillosas — usa protectores mate o imprime en papel

## Próximos pasos

- **[Integración con webhooks](https://developer.rhombus.com/es/implementations/webhook-listener)**: Configura webhooks para recibir eventos de control de acceso en tiempo real
- **[Soporte de Rhombus](mailto:support@rhombus.com)**: Contacta al Soporte de Rhombus para obtener ayuda con tu integración.
- **[Consola de Rhombus](https://console.rhombussystems.com)**: Administra tus dispositivos y ajustes de control de acceso

> **Note**: Esta funcionalidad se encuentra en desarrollo activo. Contacta a tu representante de Rhombus para obtener novedades sobre nuevas funcionalidades y mejoras.