Grupos de Acesso

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
2. Como Funcionam os Grupos de Acesso
3. Referência de Endpoints
4. Gerenciando Grupos
5. Gerenciando Membros
6. Grupos do Sistema
7. Auditoria de Permissões
8. Formato de Resposta
9. Boas Práticas
10. Troubleshooting

​

1. Visão Geral

​

O que são Grupos de Acesso?

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

​

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

​

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

​

4. Gerenciando Grupos

​

Listar Grupos de Acesso

GET /api/access-groups

​

Criar um Grupo de Acesso

POST /api/access-groups
Content-Type: application/json

{
  "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 -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

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

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

GET /api/access-groups/{groupId}/members

​

Atribuir Membros a um Grupo

PATCH /api/access-groups/{groupId}/members
Content-Type: application/json

{
  "membershipIds": ["mem_abc123", "mem_def456"]
}

​

Remover Membros de um Grupo

DELETE /api/access-groups/{groupId}/members
Content-Type: application/json

{
  "membershipIds": ["mem_abc123"]
}

​

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

• 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

​

9. Boas Práticas

​

Planeje a Estrutura de Grupos Primeiro

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

• 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

• 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