> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
</Note>

<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 publica en la [Comunidad de Desarrolladores de Rhombus](https://rhombus.community).
</Warning>

## 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

<Steps>
  ### 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.

  ### 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.

  ### 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.

  ### 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.
</Steps>

## Casos de uso

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

<CardGroup cols={2}>
  <Card title="Visitantes en oficinas" icon="building">
    Otorga acceso por un día o por tiempo limitado a visitantes sin necesidad de emitir gafetes físicos.
  </Card>

  <Card title="Operaciones de campo" icon="wrench">
    Envía QR Codes a técnicos o contratistas para acceso temporal a áreas específicas.
  </Card>

  <Card title="Edificios multi-tenant" icon="users">
    Emite códigos específicos por tenant con duraciones personalizadas para distintos niveles de acceso.
  </Card>

  <Card title="Entregas y ventanas de acceso" icon="truck">
    Programa accesos durante horarios de entrega específicos con QR Codes con tiempo limitado.
  </Card>
</CardGroup>

## 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 API key válida desde la [Consola de Rhombus](https://console.rhombussystems.com)
* 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` en la Referencia de la API.
</Tip>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  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 theme={null}
  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 theme={null}
  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);
    });
  ```
</CodeGroup>

### Parámetros de la solicitud

<ParamField path="accessControlledDoorUuid" type="string" required>
  El identificador único de la puerta para la cual quieres autorizar el acceso. Este UUID se obtiene del endpoint `findAccessControlledDoors`.
</ParamField>

<ParamField path="validDurationSec" type="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
</ParamField>

<ParamField path="auditPrincipal" type="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.
</ParamField>

### Respuesta

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

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

<ResponseField name="qrCode" type="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.
</ResponseField>

<ResponseField name="accessTokenUuid" type="string">
  El UUID del token de acceso generado que respalda este QR Code. Úsalo para rastrear o hacer referencia a la credencial emitida.
</ResponseField>

## 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.

<CodeGroup>
  ```python Python theme={null}
  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 theme={null}
  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');
  ```
</CodeGroup>

### 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 theme={null}
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 theme={null}
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:
</Warning>

### 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

### 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:
</Tip>

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="La API devuelve error">
    **Causas comunes:**

    * API key inválida o headers de autenticación incorrectos
    * UUID de puerta incorrecto
    * Puerta no configurada para acceso con QR Code
    * Permisos insuficientes

    **Soluciones:**

    * Verifica tu API key en la Consola de Rhombus
    * Revisa que el header `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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Integración con webhooks" icon="webhook" href="/es/implementations/webhook-listener">
    Configura webhooks para recibir eventos de control de acceso en tiempo real
  </Card>

  <Card title="Comunidad de desarrolladores" icon="comments" href="https://rhombus.community">
    Únete a la Comunidad de Desarrolladores de Rhombus para soporte y novedades
  </Card>

  <Card title="Consola de Rhombus" icon="gear" href="https://console.rhombussystems.com">
    Administra tus dispositivos y ajustes de control de acceso
  </Card>
</CardGroup>

<Note>
  Esta funcionalidad se encuentra en desarrollo activo. Mantente atento a la [Comunidad de Desarrolladores de Rhombus](https://rhombus.community) para obtener actualizaciones sobre nuevas funcionalidades y mejoras.
</Note>