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

> Controle quem pode acessar o quê dentro da sua organização ZappWay. Os Grupos de Acesso permitem definir conjuntos de permissões e atribuí-los a membros da equipe — habilitando controle de acesso baseado em função sem gerenciar permissões individuais.

> **O que você vai aprender:**
> Esta página explica como funcionam os Grupos de Acesso, como criar e configurar grupos, como atribuir membros e como usar o modelo de permissões para controlar o acesso aos recursos do ZappWay.

***

## 🔢 Sumário

1. [Visão Geral](#1-visao-geral)
2. [Como Funcionam os Grupos de Acesso](#2-como-funcionam-os-grupos-de-acesso)
3. [Referência de Endpoints](#3-referencia-de-endpoints)
4. [Gerenciando Grupos](#4-gerenciando-grupos)
5. [Gerenciando Membros](#5-gerenciando-membros)
6. [Grupos do Sistema](#6-grupos-do-sistema)
7. [Auditoria de Permissões](#7-auditoria-de-permissoes)
8. [Formato de Resposta](#8-formato-de-resposta)
9. [Boas Práticas](#9-boas-praticas)
10. [Troubleshooting](#10-troubleshooting)

***

## 1. Visão Geral

### O que são Grupos de Acesso?

Os Grupos de Acesso são **coleções de permissões** que você atribui a membros da equipe. Em vez de gerenciar permissões individuais por pessoa, você:

1. **Cria um grupo** (ex: "Equipe de Vendas", "Gerente de Suporte")
2. **Define suas permissões** (ex: ler conversas, gerenciar contatos)
3. **Atribui membros** ao grupo

Todos os membros de um grupo herdam suas permissões automaticamente.

### Principais Benefícios

* **Gerenciamento simplificado** — Altere permissões para toda uma equipe de uma vez
* **Acesso baseado em função** — Alinhe a estrutura da sua organização ao acesso à plataforma
* **Auditável** — Cada alteração de grupo é registrada no log de auditoria de permissões
* **Escalável** — Funciona para equipes de 2 a 2000+ pessoas

***

## 2. Como Funcionam os Grupos de Acesso

### Modelo de Permissões

O ZappWay usa um **modelo de acesso baseado em permissões** com permissões granulares como:

| Permissão             | O que concede                      |
| --------------------- | ---------------------------------- |
| `conversations.read`  | Visualizar conversas               |
| `conversations.write` | Responder e gerenciar conversas    |
| `agents.read`         | Visualizar Funcionários IA         |
| `agents.write`        | Criar e editar Funcionários IA     |
| `contacts.read`       | Visualizar contatos                |
| `contacts.write`      | Criar e editar contatos            |
| `groups.read`         | Visualizar grupos de acesso        |
| `groups.manage`       | Criar, editar e excluir grupos     |
| `team.invite`         | Convidar novos membros da equipe   |
| `team.change_group`   | Mover membros entre grupos         |
| `billing.read`        | Visualizar informações de cobrança |
| `billing.manage`      | Gerenciar assinatura e pagamentos  |

### Fluxo de Atribuição de Grupo

```
Administrador da Organização
       ↓
Cria Grupo de Acesso (com permissões)
       ↓
Convida membro da equipe OU altera grupo de membro existente
       ↓
Membro herda todas as permissões do grupo
       ↓
Membro acessa recursos correspondentes às suas permissões
```

***

## 3. Referência de Endpoints

| Método   | Endpoint                          | Descrição                                       | Auth                                                  |
| -------- | --------------------------------- | ----------------------------------------------- | ----------------------------------------------------- |
| `GET`    | `/api/access-groups`              | Listar todos os grupos de acesso da organização | `groups.read` OU `team.invite` OU `team.change_group` |
| `POST`   | `/api/access-groups`              | Criar um novo grupo de acesso                   | `groups.manage`                                       |
| `GET`    | `/api/access-groups/[id]`         | Obter um grupo de acesso específico             | `groups.read`                                         |
| `PATCH`  | `/api/access-groups/[id]`         | Atualizar um grupo de acesso                    | `groups.manage`                                       |
| `DELETE` | `/api/access-groups/[id]`         | Excluir um grupo de acesso                      | `groups.manage`                                       |
| `GET`    | `/api/access-groups/[id]/members` | Listar membros de um grupo                      | `groups.manage`                                       |
| `PATCH`  | `/api/access-groups/[id]/members` | Atribuir membros a um grupo                     | `groups.manage`                                       |
| `DELETE` | `/api/access-groups/[id]/members` | Remover membros de um grupo                     | `groups.manage`                                       |

***

## 4. Gerenciando Grupos

### Listar Grupos de Acesso

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

Retorna todos os grupos de acesso da organização atual, incluindo grupos gerenciados pelo sistema.

### Criar um Grupo de Acesso

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

**Corpo da Requisição:**

| Campo         | Tipo       | Obrigatório | Descrição                                                |
| ------------- | ---------- | ----------- | -------------------------------------------------------- |
| `name`        | `string`   | ✅           | Nome de exibição do grupo                                |
| `key`         | `string`   | ❌           | Chave legível por máquina (auto-gerada a partir do nome) |
| `description` | `string`   | ❌           | Descrição do propósito do grupo                          |
| `permissions` | `string[]` | ✅           | Array de strings de permissão a conceder                 |

**Exemplo:**

```json theme={null}
{
  "name": "Equipe de Suporte",
  "description": "Agentes de suporte de linha de frente — podem ler e responder conversas",
  "permissions": [
    "conversations.read",
    "conversations.write",
    "contacts.read",
    "agents.read"
  ]
}
```

**cURL:**

```bash theme={null}
curl -X POST "https://seu-dominio.com/api/access-groups" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=SEU_TOKEN_DE_SESSAO" \
  -d '{
    "name": "Equipe de Suporte",
    "permissions": ["conversations.read", "conversations.write", "contacts.read"]
  }'
```

> Cada `POST` e `DELETE` em grupos de acesso é registrado automaticamente no **log de auditoria de permissões**.

### Atualizar um Grupo de Acesso

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

> Atualizar `permissions` substitui todo o conjunto de permissões. Sempre inclua todas as permissões desejadas na atualização.

### Excluir um Grupo de Acesso

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

> ⚠️ **Grupos do sistema não podem ser excluídos.** Tentar excluir um grupo do sistema (`isSystem: true`) retorna `403 Forbidden`.

***

## 5. Gerenciando Membros

### Listar Membros de um Grupo

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

### Atribuir Membros a um Grupo

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

**Corpo da Requisição:**

| Campo           | Tipo       | Obrigatório | Descrição                                       |
| --------------- | ---------- | ----------- | ----------------------------------------------- |
| `membershipIds` | `string[]` | ✅           | Array de IDs de membership a adicionar ao grupo |

**Exemplo:**

```json theme={null}
{
  "membershipIds": ["mem_abc123", "mem_def456"]
}
```

### Remover Membros de um Grupo

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

**Corpo da Requisição:**

```json theme={null}
{
  "membershipIds": ["mem_abc123"]
}
```

***

## 6. Grupos do Sistema

O ZappWay cria automaticamente **grupos de acesso gerenciados pelo sistema** para cada organização:

| Chave do Grupo | Nome          | Descrição                                  |
| -------------- | ------------- | ------------------------------------------ |
| `admin`        | Administrador | Acesso total a todos os recursos           |
| `member`       | Membro        | Acesso padrão para novos membros da equipe |
| `viewer`       | Visualizador  | Acesso somente leitura                     |

**Regras dos grupos do sistema:**

* Grupos do sistema **não podem ser excluídos**
* Permissões dos grupos do sistema **não podem ser modificadas**
* Todo novo membro é atribuído ao grupo `member` por padrão

***

## 7. Auditoria de Permissões

Cada criação, atualização, exclusão de grupo e atribuição de membros é automaticamente registrada no **log de auditoria de permissões**. O registro de auditoria inclui:

* Quem fez a alteração (usuário)
* O que mudou (ação: `create`, `update`, `delete`)
* Qual recurso foi afetado (ID do grupo, chave)
* Resultado (sucesso/falha)
* Metadados (chave do grupo, se é um grupo do sistema)

***

## 8. Formato de Resposta

### Status Codes

| Status | Significado                                                         |
| ------ | ------------------------------------------------------------------- |
| `200`  | Requisição bem-sucedida                                             |
| `201`  | Grupo criado                                                        |
| `400`  | Corpo inválido da requisição                                        |
| `401`  | Não autenticado                                                     |
| `403`  | Permissões insuficientes ou tentativa de modificar grupo do sistema |
| `404`  | Grupo de acesso não encontrado na organização                       |
| `500`  | Erro interno do servidor                                            |

***

## 9. Boas Práticas

### Planeje a Estrutura de Grupos Primeiro

Antes de criar grupos, mapeie a estrutura da sua organização:

```
Organização
├── Administrador (grupo do sistema — acesso total)
├── Líder de Equipe (personalizado — pode convidar + alterar grupos)
├── Representante de Vendas (personalizado — conversas + contatos)
├── Agente de Suporte (personalizado — leitura/escrita de conversas)
└── Visualizador (grupo do sistema — somente leitura)
```

### Atribuições de Permissão

✅ **Faça:**

* Siga o **princípio do menor privilégio** — conceda apenas as permissões que cada função realmente precisa
* Crie grupos baseados em funções que correspondam a cargos reais
* Revise as permissões trimestralmente e remova as desnecessárias

❌ **Evite:**

* Criar um grupo com todas as permissões para usuários não administradores
* Duplicar o comportamento do grupo do sistema `admin` em grupos personalizados
* Dar `billing.manage` a membros não financeiros da equipe

***

## 10. Troubleshooting

| Problema                                        | Causa Possível                                             | Solução                                                                        |
| ----------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `403 Forbidden` em operações de grupo           | Permissões insuficientes                                   | Você precisa da permissão `groups.manage`                                      |
| Não é possível excluir grupo do sistema         | O grupo tem `isSystem: true`                               | Grupos do sistema não podem ser excluídos                                      |
| Membro não herda permissões do grupo            | Atraso de cache                                            | Aguarde alguns segundos; permissões de sessão são atualizadas no próximo login |
| Permissões incorretas após atualização do grupo | Atualização de `permissions` substitui o conjunto completo | Sempre inclua todas as permissões desejadas no payload de atualização          |
| Membro listado mas sem acesso                   | Membro está em múltiplos grupos                            | Verifique todos os memberships do usuário afetado                              |