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

# Grupos de acceso

> Controle quién puede acceder a qué dentro de su organización ZappWay. Los grupos de acceso le permiten definir conjuntos de permisos y asignarlos a los miembros del equipo, lo que permite un control de acceso basado en roles sin administrar permisos individuales.

> **Lo que aprenderás:**
> Esta página explica cómo funcionan los grupos de acceso, cómo crear y configurar grupos, cómo asignar miembros y cómo usar el modelo de permisos para controlar el acceso a las funciones de ZappWay.

***

## 🔢 Tabla de contenidos

1. [Overview](#1-overview)
2. [How Access Groups Work](#2-how-access-groups-work)
3. [Endpoint Reference](#3-endpoint-reference)
4. [Managing Groups](#4-managing-groups)
5. [Managing Members](#5-managing-members)
6. [System Groups](#6-system-groups)
7. [Permission Audit](#7-permission-audit)
8. [Response Format](#8-response-format)
9. [Best Practices](#9-best-practices)
10. [Troubleshooting](#10-troubleshooting)

***

## 1. Descripción general

### ¿Qué son los grupos de acceso?

Los grupos de acceso son **colecciones de permisos** que asignas a los miembros del equipo. En lugar de gestionar permisos individuales por persona, usted:

1. **Create a group** (e.g., "Sales Team", "Support Manager")
2. **Define its permissions** (e.g., read conversations, manage contacts)
3. **Assign members** to the group

Todos los miembros de un grupo heredan sus permisos automáticamente.

### Beneficios clave

* **Administración simplificada**: cambie los permisos para todo un equipo a la vez
* **Acceso basado en roles**: haga coincidir la estructura de su organización con el acceso a la plataforma
* **Auditable**: cada cambio de grupo se registra en el registro de auditoría de permisos.
* **Escalable**: funciona para equipos de 2 a 2000+

***

## 2. Cómo funcionan los grupos de acceso

### Modelo de permiso

ZappWay utiliza un **modelo de acceso basado en permisos** con permisos granulares como:

| Permiso               | Qué otorga                           |
| --------------------- | ------------------------------------ |
| `conversations.read`  | Ver conversaciones                   |
| `conversations.write` | Responder y gestionar conversaciones |
| `agents.read`         | Ver empleados de IA                  |
| `agents.write`        | Crear y editar empleados de IA       |
| `contacts.read`       | Ver contactos                        |
| `contacts.write`      | Crear y editar contactos             |
| `groups.read`         | Ver grupos de acceso                 |
| `groups.manage`       | Crear, editar y eliminar grupos      |
| `team.invite`         | Invitar a nuevos miembros del equipo |
| `team.change_group`   | Mover miembros entre grupos          |
| `billing.read`        | Ver información de facturación       |
| `billing.manage`      | Gestionar suscripción y pagos        |

### Flujo de asignación de grupo

```
Organization Admin
       ↓
Creates Access Group (with permissions)
       ↓
Invites team member OR changes existing member's group
       ↓
Team member inherits all group permissions
       ↓
Member can access features matching their permissions
```

***

## 3. Referencia de punto final

| Método   | Punto final                       | Descripción                                          | Autenticación                                       |
| -------- | --------------------------------- | ---------------------------------------------------- | --------------------------------------------------- |
| `GET`    | `/api/access-groups`              | Listar todos los grupos de acceso de la organización | `groups.read` O `team.invite` O `team.change_group` |
| `POST`   | `/api/access-groups`              | Crear un nuevo grupo de acceso                       | `groups.manage`                                     |
| `GET`    | `/api/access-groups/[id]`         | Obtener un grupo de acceso específico                | `groups.read`                                       |
| `PATCH`  | `/api/access-groups/[id]`         | Actualizar un grupo de acceso                        | `groups.manage`                                     |
| `DELETE` | `/api/access-groups/[id]`         | Eliminar un grupo de acceso                          | `groups.manage`                                     |
| `GET`    | `/api/access-groups/[id]/members` | Listar miembros de un grupo                          | `groups.manage`                                     |
| `PATCH`  | `/api/access-groups/[id]/members` | Asignar miembros a un grupo                          | `groups.manage`                                     |
| `DELETE` | `/api/access-groups/[id]/members` | Restablecer (eliminar) miembros de un grupo          | `groups.manage`                                     |

***

## 4. Gestión de grupos

### Listar grupos de acceso

```bash theme={null}
GET /api/access-groups
```

Devuelve todos los grupos de acceso de la organización actual, incluidos los grupos administrados por el sistema.

**Respuesta:**
***CÓDIGO\_BLOQUE\_2***

### Crear un grupo de acceso

```bash theme={null}
POST /api/access-groups
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo         | Tipo       | Requerido | Descripción                                                              |
| ------------- | ---------- | --------- | ------------------------------------------------------------------------ |
| `name`        | `string`   | ✅         | Nombre para mostrar del grupo                                            |
| `key`         | `string`   | ❌         | Clave legible por máquina (generada automáticamente a partir del nombre) |
| `description` | `string`   | ❌         | Descripción del objeto del grupo                                         |
| `permissions` | `string[]` | ✅         | Matriz de cadenas de permisos para otorgar                               |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_4***

**rizo:**
***CÓDIGO\_BLOQUE\_5***

**Mecanografiado:**
***CÓDIGO\_BLOQUE\_6***

> Cada `POST` y ​​`DELETE` en grupos de acceso se registra en el **registro de auditoría de permisos** automáticamente.

### Actualizar un grupo de acceso

```bash theme={null}
PATCH /api/access-groups/{groupId}
Content-Type: application/json
```

Todos los campos son opcionales. Sólo se actualizan los campos proporcionados.

**Ejemplo: agregue un permiso:**
***CÓDIGO\_BLOQUE\_8***

> La actualización `permissions` reemplaza todo el conjunto de permisos. Incluya siempre todos los permisos deseados en la actualización, no solo los agregados.

### Eliminar un grupo de acceso

```bash theme={null}
DELETE /api/access-groups/{groupId}
```

> ⚠️ **Los grupos del sistema no se pueden eliminar.** Al intentar eliminar un grupo del sistema (`isSystem: true`) se devuelve `403 Forbidden`.

***

## 5. Gestión de miembros

### Listar miembros de un grupo

```bash theme={null}
GET /api/access-groups/{groupId}/members
```

**Respuesta:**
***CÓDIGO\_BLOQUE\_11***

### Asignar miembros a un grupo

```bash theme={null}
PATCH /api/access-groups/{groupId}/members
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo           | Tipo       | Requerido | Descripción                                       |
| --------------- | ---------- | --------- | ------------------------------------------------- |
| `membershipIds` | `string[]` | ✅         | Conjunto de ID de membresía para agregar al grupo |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_13***

### Eliminar miembros de un grupo

```bash theme={null}
DELETE /api/access-groups/{groupId}/members
Content-Type: application/json
```

**Cuerpo de la solicitud:**
***CÓDIGO\_BLOQUE\_15***

***

## 6. Grupos de sistemas

ZappWay crea automáticamente **grupos de acceso administrados por el sistema** para cada organización:

| Clave de grupo | Nombre        | Descripción                                           |
| -------------- | ------------- | ----------------------------------------------------- |
| `admin`        | Administrador | Acceso completo a todas las funciones                 |
| `member`       | Miembro       | Acceso predeterminado para nuevos miembros del equipo |
| `viewer`       | Visor         | Acceso de sólo lectura                                |

**Reglas del grupo del sistema:**

* Los grupos del sistema **no se pueden eliminar**
* Permisos de grupo del sistema **no se pueden modificar** (administrados por ZappWay)
* Cada nuevo miembro del equipo se asigna a `member` de forma predeterminada, a menos que especifique lo contrario durante la invitación.

***

## 7. Auditoría de permisos

Cada creación, actualización, eliminación y asignación de miembros de un grupo se registra automáticamente en el **registro de auditoría de permisos**. El registro de auditoría incluye:

* Quién realizó el cambio (usuario)
* Qué cambió (acción: `create`, `update`, `delete`)
* Qué recurso se vio afectado (ID de grupo de acceso, clave)
* Resultado (éxito/fracaso)
* Metadatos (clave de grupo, ya sea un grupo de sistema)

Puede exportar registros de auditoría a través de la configuración de la organización.

***

## 8. Formato de respuesta

### Códigos de estado

| Estado | Significado                                                        |
| ------ | ------------------------------------------------------------------ |
| `200`  | Solicitud exitosa                                                  |
| `201`  | Grupo creado                                                       |
| `400`  | Cuerpo de solicitud no válido                                      |
| `401`  | No autenticado                                                     |
| `403`  | Permisos insuficientes o intento de modificar un grupo de sistemas |
| `404`  | Grupo de acceso no encontrado en la organización                   |
| `500`  | Error interno del servidor                                         |

***

## 9. Mejores prácticas

### Primero diseñe la estructura de su grupo

Antes de crear grupos, mapee la estructura de su organización:

```
Organization
├── Administrator (system group — full access)
├── Team Lead (custom — can invite + change groups)
├── Sales Representative (custom — conversations + contacts)
├── Support Agent (custom — conversations read/write)
└── Viewer (system group — read only)
```

### Asignaciones de permisos

✅ **Hacer:**

* Siga el **principio de privilegio mínimo**: otorgue solo los permisos que cada rol realmente necesita
* Crear grupos basados en roles que coincidan con funciones laborales reales
* Revisar los permisos trimestralmente y eliminar los innecesarios.

❌ **Evitar:**

* Crear un grupo con todos los permisos para usuarios que no sean administradores
* Duplicar el comportamiento del grupo del sistema `admin` en grupos personalizados
* Dar `billing.manage` a miembros del equipo no financieros

### Gestión de miembros a escala

* Asignar miembros a grupos **durante la invitación** en lugar de después (flujo de trabajo más limpio)
* Utilice `PATCH /members` para realizar reasignaciones masivas al reorganizar equipos
* Revisar la membresía del grupo después de que los miembros del equipo cambien de roles.

***

## 10. Solución de problemas

| Problema                                                   | Posible causa                                                           | Solución                                                                                             |
| ---------------------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `403 Forbidden` sobre operaciones grupales                 | No hay suficientes permisos                                             | Necesitas permiso `groups.manage`                                                                    |
| No se puede eliminar el grupo del sistema                  | El grupo tiene `isSystem: true`                                         | Los grupos del sistema no se pueden eliminar; póngase en contacto con soporte si necesita cambios    |
| Miembro que no hereda los permisos del grupo               | Retraso de caché                                                        | Espere unos segundos y actualice; actualización de permisos de sesión en el próximo inicio de sesión |
| Permisos incorrectos después de la actualización del grupo | La actualización `permissions` reemplaza el conjunto completo           | Incluya siempre todos los permisos deseados en la carga útil de actualización                        |
| Miembro listado pero sin acceso                            | El miembro está en varios grupos; otro grupo puede restringir el acceso | Verifique todas las membresías de grupos del usuario afectado                                        |