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 FalsePasso 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 permissoesWorkflow 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 == 200Passo 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 relatorioPasso 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 resultadosBoas 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)