Logo

Gestão de Usuários

Guia completo para gerenciar usuários, perfis e permissões no Sinapse

Este guia mostra como gerenciar usuários no Sinapse, incluindo criação de contas, atualização de perfis, gestão de grupos e permissões.

Objetivos

Ao final deste guia, você será capaz de:

  • Criar e gerenciar contas de usuário
  • Atualizar perfis e informações pessoais
  • Gerenciar grupos e permissões
  • Implementar fluxos de onboarding
  • Automatizar gestão de acessos

Pré-requisitos

Token de autenticação válido Permissões adequadas para gestão (se aplicável) Entendimento do sistema RBAC do Sinapse

Workflow 1: Auto-cadastro e Gestão de Perfil

Passo 1: Criar sua Conta

// Formulário de cadastro
const formCadastro = {
  email: "[email protected]",
  senha: "SenhaForte123!",
  confirmarSenha: "SenhaForte123!",
  nome: "Maria Silva",
  cpf: "123.456.789-00",
  telefone: "(11) 98765-4321",
  cargo: "Analista de Dados",
  departamento: "Vigilância Epidemiológica"
};

// Validar senha
function validarSenha(senha) {
  const regras = {
    minLength: senha.length >= 8,
    hasUpper: /[A-Z]/.test(senha),
    hasLower: /[a-z]/.test(senha),
    hasNumber: /[0-9]/.test(senha),
    hasSpecial: /[^A-Za-z0-9]/.test(senha)
  };
  
  return Object.values(regras).every(v => v);
}
# Criar conta
curl -X POST https://api.sinapse.org.br/v1/usuarios/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "senha": "SenhaForte123!",
    "nome": "Maria Silva",
    "cpf": "123.456.789-00",
    "telefone": "(11) 98765-4321"
  }'

# Resposta
{
  "id": 456,
  "email": "[email protected]",
  "nome": "Maria Silva",
  "token_ativacao": "abc123",
  "mensagem": "Conta criada! Verifique seu email."
}
from sinapse_sdk import SinapseClient

# Criar conta
client = SinapseClient()

novo_usuario = client.usuarios.criar({
    "email": "[email protected]",
    "senha": "SenhaForte123!",
    "nome": "Maria Silva",
    "cpf": "123.456.789-00",
    "telefone": "(11) 98765-4321"
})

print(f"Conta criada! ID: {novo_usuario.id}")
print(f"Verifique o email: {novo_usuario.email}")

Passo 2: Verificar Email

Após criar a conta, o usuário recebe um email com link de verificação:

# Verificar email
def verificar_email(token):
    response = requests.post(
        f"{base_url}/auth/verify-email",
        json={"token": token}
    )
    
    if response.status_code == 200:
        print("Email verificado com sucesso!")
        return True
    else:
        print("Token inválido ou expirado")
        return False

Passo 3: Completar Perfil

Após verificação, complete seu perfil:

async function completarPerfil(userId, dadosAdicionais) {
  const response = await fetch(`/api/v1/usuarios/${userId}`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cargo: "Analista de Dados",
      departamento: "Vigilância Epidemiológica",
      cidade: "São Paulo",
      estado: "SP",
      bio: "Especialista em análise de dados epidemiológicos",
      avatar_url: "https://exemplo.com/avatar.jpg"
    })
  });
  
  return response.json();
}

Workflow 2: Gestão de Equipe (Admin)

Passo 1: Listar Usuários da Organização

Permissão necessária: usuarios.listar

def listar_equipe(filtros={}):
    """Lista usuários com filtros avançados"""
    
    params = {
        "page": 1,
        "size": 50,
        "ativo": True,
        **filtros
    }
    
    response = requests.get(
        f"{base_url}/usuarios",
        headers=headers,
        params=params
    )
    
    usuarios = response.json()
    
    # Análise rápida
    print(f"Total de usuários: {usuarios['total']}")
    print(f"Ativos: {usuarios['agregacoes']['ativos']}")
    print(f"Por grupo:")
    for grupo, count in usuarios['agregacoes']['por_grupo'].items():
        print(f"  {grupo}: {count}")
    
    return usuarios['items']

Passo 2: Criar Usuários em Lote

Para onboarding de equipes:

async function criarUsuariosLote(usuarios) {
  const resultados = {
    sucesso: [],
    erros: []
  };
  
  for (const usuario of usuarios) {
    try {
      const response = await fetch('/api/v1/usuarios', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${adminToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          ...usuario,
          senha_temporaria: gerarSenhaTemporaria(),
          forcar_troca_senha: true
        })
      });
      
      if (response.ok) {
        const novoUsuario = await response.json();
        resultados.sucesso.push(novoUsuario);
        
        // Enviar email de boas-vindas
        await enviarEmailBoasVindas(novoUsuario);
      } else {
        const erro = await response.json();
        resultados.erros.push({usuario: usuario.email, erro});
      }
    } catch (error) {
      resultados.erros.push({usuario: usuario.email, erro: error.message});
    }
  }
  
  return resultados;
}

function gerarSenhaTemporaria() {
  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%';
  let senha = '';
  for (let i = 0; i < 12; i++) {
    senha += chars.charAt(Math.floor(Math.random() * chars.length));
  }
  return senha;
}

Passo 3: Atribuir Grupos e Permissões

def configurar_acesso_usuario(user_id, grupo_padrao="usuario"):
    """Configura acesso inicial do usuário"""
    
    # 1. Adicionar ao grupo padrão
    response = requests.post(
        f"{base_url}/usuarios/{user_id}/grupos/{grupo_padrao}",
        headers=headers
    )
    
    if response.status_code == 200:
        print(f"Usuário adicionado ao grupo {grupo_padrao}")
    
    # 2. Adicionar permissões específicas se necessário
    permissoes_extras = []
    
    # Exemplo: dar permissão de exportação para analistas
    if grupo_padrao == "analista":
        permissoes_extras = ["relatorios.exportar", "agravos.exportar"]
    
    for permissao in permissoes_extras:
        requests.post(
            f"{base_url}/usuarios/{user_id}/permissoes/{permissao}",
            headers=headers
        )
    
    # 3. Verificar permissões efetivas
    response = requests.get(
        f"{base_url}/usuarios/{user_id}/permissoes",
        headers=headers
    )
    
    permissoes = response.json()
    print(f"Permissões totais: {len(permissoes['permissoes_efetivas'])}")
    
    return permissoes

Workflow 3: Gestão de Senhas e Segurança

Passo 1: Alterar Própria Senha

async function alterarSenha(senhaAtual, novaSenha) {
  // Validar nova senha localmente primeiro
  if (!validarRequisitos(novaSenha)) {
    throw new Error('Nova senha não atende aos requisitos');
  }
  
  const response = await fetch('/api/v1/auth/change-password', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      senha_atual: senhaAtual,
      nova_senha: novaSenha
    })
  });
  
  if (response.ok) {
    // Fazer logout em todos os dispositivos
    await fetch('/api/v1/auth/logout-all', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${token}` }
    });
    
    alert('Senha alterada! Faça login novamente.');
    window.location.href = '/login';
  }
}

Passo 2: Recuperar Senha

# Solicitar recuperação
def solicitar_recuperacao_senha(email):
    response = requests.post(
        f"{base_url}/auth/forgot-password",
        json={"email": email}
    )
    
    if response.status_code == 200:
        return {
            "sucesso": True,
            "mensagem": "Email de recuperação enviado"
        }
    else:
        return {
            "sucesso": False,
            "mensagem": "Email não encontrado"
        }

# Resetar senha com token
def resetar_senha(token, nova_senha):
    response = requests.post(
        f"{base_url}/auth/reset-password",
        json={
            "token": token,
            "nova_senha": nova_senha
        }
    )
    
    return response.status_code == 200

Passo 3: Habilitar MFA (Multi-Factor Authentication)

// Habilitar MFA
async function habilitarMFA() {
  // 1. Gerar QR Code
  const setupResponse = await fetch('/api/v1/auth/mfa/setup', {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` }
  });
  
  const { qr_code, secret, backup_codes } = await setupResponse.json();
  
  // 2. Mostrar QR Code para usuário
  document.getElementById('qrcode').src = qr_code;
  
  // 3. Validar código do autenticador
  const codigo = prompt('Digite o código do seu autenticador:');
  
  const enableResponse = await fetch('/api/v1/auth/mfa/enable', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      secret: secret,
      codigo: codigo
    })
  });
  
  if (enableResponse.ok) {
    // Salvar backup codes
    console.log('MFA habilitado! Guarde estes códigos de backup:');
    backup_codes.forEach(code => console.log(code));
  }
}

Workflow 4: Auditoria e Compliance

Passo 1: Monitorar Atividades

def auditar_acesso_usuario(user_id, dias=30):
    """Audita atividades de um usuário"""
    
    # Buscar logs de acesso
    params = {
        "user_id": user_id,
        "dias": dias,
        "incluir": "login,api_calls,permissoes"
    }
    
    response = requests.get(
        f"{base_url}/auditoria/usuarios/{user_id}",
        headers=headers,
        params=params
    )
    
    atividades = response.json()
    
    # Análise de segurança
    relatorio = {
        "total_logins": len(atividades['logins']),
        "ips_unicos": len(set(l['ip'] for l in atividades['logins'])),
        "tentativas_falhas": sum(1 for l in atividades['logins'] if not l['sucesso']),
        "endpoints_acessados": {},
        "horarios_atipicos": []
    }
    
    # Identificar padrões suspeitos
    for atividade in atividades['api_calls']:
        endpoint = atividade['endpoint']
        relatorio['endpoints_acessados'][endpoint] = \
            relatorio['endpoints_acessados'].get(endpoint, 0) + 1
        
        # Verificar horários
        hora = datetime.fromisoformat(atividade['timestamp']).hour
        if hora < 6 or hora > 22:  # Fora do horário comercial
            relatorio['horarios_atipicos'].append(atividade)
    
    return relatorio

Passo 2: Desativar Usuários Inativos

async function desativarUsuariosInativos(diasInatividade = 90) {
  // Buscar usuários inativos
  const response = await fetch(
    `/api/v1/usuarios?ultimo_acesso_antes=${diasInatividade}&ativo=true`,
    { headers: { 'Authorization': `Bearer ${adminToken}` } }
  );
  
  const usuarios = await response.json();
  const desativados = [];
  
  for (const usuario of usuarios.items) {
    // Verificar se tem dados importantes
    const temDados = await verificarDadosUsuario(usuario.id);
    
    if (!temDados) {
      // Desativar usuário
      await fetch(`/api/v1/usuarios/${usuario.id}`, {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${adminToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          ativo: false,
          motivo_desativacao: 'Inatividade por mais de 90 dias'
        })
      });
      
      desativados.push(usuario);
      
      // Notificar usuário
      await enviarEmailDesativacao(usuario);
    }
  }
  
  return {
    total_inativos: usuarios.total,
    desativados: desativados.length,
    usuarios: desativados
  };
}

Workflow 5: Integração com RH

Importar Usuários do Sistema RH

def sincronizar_com_rh():
    """Sincroniza usuários com sistema RH"""
    
    # 1. Buscar dados do RH
    usuarios_rh = buscar_usuarios_rh()  # Sistema externo
    
    # 2. Mapear para formato Sinapse
    usuarios_sinapse = []
    for u in usuarios_rh:
        usuario_mapeado = {
            "email": u['email_corporativo'],
            "nome": u['nome_completo'],
            "cpf": u['cpf'],
            "telefone": u['telefone_comercial'],
            "cargo": u['cargo'],
            "departamento": mapear_departamento(u['departamento_id']),
            "matricula": u['matricula'],  # Campo customizado
            "data_admissao": u['data_admissao']
        }
        usuarios_sinapse.append(usuario_mapeado)
    
    # 3. Processar em lote
    resultados = {
        "criados": 0,
        "atualizados": 0,
        "erros": []
    }
    
    for usuario in usuarios_sinapse:
        try:
            # Verificar se existe
            existing = buscar_por_cpf(usuario['cpf'])
            
            if existing:
                # Atualizar
                response = requests.put(
                    f"{base_url}/usuarios/{existing['id']}",
                    headers=headers,
                    json=usuario
                )
                if response.status_code == 200:
                    resultados['atualizados'] += 1
            else:
                # Criar
                usuario['senha'] = gerar_senha_inicial(usuario['cpf'])
                response = requests.post(
                    f"{base_url}/usuarios",
                    headers=headers,
                    json=usuario
                )
                if response.status_code == 201:
                    resultados['criados'] += 1
                    enviar_credenciais_iniciais(usuario)
                    
        except Exception as e:
            resultados['erros'].append({
                "usuario": usuario['email'],
                "erro": str(e)
            })
    
    return resultados

Boas Práticas

1. Onboarding Eficiente

class OnboardingManager {
  async processarNovoUsuario(dadosUsuario) {
    const passos = [
      this.criarConta,
      this.enviarEmailBoasVindas,
      this.atribuirGrupoPadrao,
      this.criarTutorial,
      this.notificarGestor
    ];
    
    const resultados = [];
    
    for (const passo of passos) {
      try {
        const resultado = await passo(dadosUsuario);
        resultados.push({ sucesso: true, ...resultado });
      } catch (erro) {
        resultados.push({ sucesso: false, erro: erro.message });
        // Continuar com próximos passos mesmo com erro
      }
    }
    
    return resultados;
  }
  
  async criarTutorial(usuario) {
    // Criar tarefas iniciais personalizadas
    const tarefas = [
      "Complete seu perfil",
      "Configure autenticação de dois fatores",
      "Explore o dashboard de agravos",
      "Faça sua primeira análise"
    ];
    
    return await this.criarTarefasUsuario(usuario.id, tarefas);
  }
}

2. Gestão de Permissões Escalável

class GestorPermissoes:
    def __init__(self, api_client):
        self.api = api_client
        
    def criar_perfil_acesso(self, nome, descricao, permissoes):
        """Cria um perfil de acesso reutilizável"""
        
        # Criar grupo
        grupo = self.api.grupos.criar({
            "nome": nome,
            "descricao": descricao
        })
        
        # Adicionar permissões
        for permissao in permissoes:
            self.api.grupos.adicionar_permissao(grupo.id, permissao)
        
        return grupo
    
    def aplicar_perfil_departamento(self, departamento, perfil_id):
        """Aplica perfil a todos usuários de um departamento"""
        
        usuarios = self.api.usuarios.listar(
            filtros={"departamento": departamento}
        )
        
        for usuario in usuarios:
            self.api.usuarios.adicionar_grupo(usuario.id, perfil_id)
        
        return len(usuarios)

Perguntas Frequentes

Próximos Passos

On this page