Um convite de usuário parece ser apenas um e-mail com um link, mas, em um SaaS B2B, representa um fluxo de identidade e de associação a uma organização. Se não ficar definido o que acontece quando o link expira, é reenviado ou chega a uma conta existente, a equipe acaba resolvendo exceções manualmente e os usuários recebem resultados difíceis de entender.
A decisão de produto consiste em modelar o ciclo completo, não apenas o envio. É recomendável separar o convite — uma solicitação pendente para um e-mail e uma organização — da conta do usuário e das permissões que ele terá ao ingressar. Essa distinção ajuda a criar um processo previsível, auditável e seguro.
Modele o convite com estados e transições explícitos
Comece definindo os estados necessários para o produto. Um modelo comum inclui pendente, aceito, expirado e revogado. Se for possível observar uma falha no envio do e-mail, registre esse resultado separadamente ou adicione um estado operacional, como “falha no envio”. Não transforme cada problema de entrega em um estado de negócio se o usuário ainda puder aceitar o convite.
Especifique quais ações permitem as transições. Um convite pendente pode ser aceito, revogado ou expirar; um convite expirado pode ser substituído por um novo; um convite aceito não deve poder ser aceito novamente. A revogação precisa impedir o uso do link, mesmo que a mensagem original continue na caixa de entrada.
- Identifique o objeto: armazene a organização, o endereço convidado, quem criou o convite e quando isso ocorreu.
- Defina o resultado: registre a aceitação e a identidade que concluiu o processo.
- Evite estados ambíguos: “e-mail enviado” não significa necessariamente “convite aceito” e não garante que a mensagem tenha sido lida.
Essa separação também facilita a explicação da tela de administração: quem está pendente, desde quando e o que o administrador pode fazer em seguida.
Defina a expiração considerando o risco e a experiência
A expiração limita por quanto tempo um link pode ser usado. Um convite válido por tempo demais amplia a janela em que um link encaminhado ou exposto continua funcionando; um prazo curto demais cria atrito, especialmente se a pessoa convidada só consultar o e-mail dias depois. Não existe uma duração universal: ela depende do risco, do tipo de organização e do nível de controle necessário para o administrador.
Defina de forma consistente o que acontece quando o prazo termina. Em geral, a opção mais clara é informar que o convite não é mais válido e oferecer uma maneira de solicitar outro. Se o usuário estiver conectado, você pode encaminhá-lo ao administrador da organização. Não apresente um convite expirado como se a conta estivesse bloqueada: são situações diferentes.
Na interface de quem envia o convite, mostre a data de expiração ou o estado expirado e permita gerar um novo convite se a pessoa tiver autorização. Defina também se o novo convite mantém o destinatário e a função previstos ou se o responsável precisa revisá-los. A expiração deve ser uma regra aplicada no servidor, não apenas um temporizador visual: o sistema precisa verificá-la no momento da aceitação.
Planeje reenvios e alterações de e-mail sem reativar links antigos
Um reenvio pode significar duas coisas diferentes: enviar novamente o mesmo link ou emitir um link novo. Se o link for mantido, a data de expiração e o token continuam iguais. Se outro link for gerado, defina explicitamente se o anterior será invalidado. Para evitar várias rotas ativas para o mesmo convite, costuma ser mais simples revogar o token anterior ao emitir o novo.
Quem envia o convite precisa receber uma confirmação de que a ação foi concluída e um aviso claro se o envio falhar. Evite que o botão de reenvio crie convites independentes a cada clique: aplique uma regra de idempotência ou verifique se já existe um convite pendente equivalente. Também é recomendável evitar envios repetidos por acidente sem impedir uma nova tentativa legítima.
Se o endereço mudar, trate a alteração como uma mudança sensível. Em geral, a solução mais clara é revogar o convite destinado ao endereço anterior e criar outro para o novo. Não altere o destinatário silenciosamente e mantenha o link que já foi enviado: quem controlar a caixa de entrada antiga poderá continuar com acesso ao processo. Registre a alteração para que a organização possa entender o que aconteceu.
Resolva duplicidades e contas que já existem
Antes de criar um convite, defina o que significa haver duplicidade. Uma regra prática é considerar a combinação entre organização e endereço normalizado, usando as mesmas convenções de normalização em todo o sistema. Não aplique transformações agressivas aos endereços de e-mail: algumas equivalências que parecem óbvias não são universais. Preserve o endereço informado pelo usuário para exibi-lo e usá-lo no envio.
Se já houver um convite pendente para aquela organização e aquele e-mail, ofereça uma ação útil: mostrar o estado, reenviar ou revogar e substituir, de acordo com as permissões de quem está agindo. Não crie uma segunda entrada que deixe os administradores sem saber qual convite é válido.
Se o e-mail pertencer a uma conta existente, o convite poderá adicionar essa identidade a outra organização, desde que a pessoa se autentique com a conta correta e aceite ingressar. Ter uma conta não significa pertencer a todas as organizações. Se houver várias contas que possam ser associadas ao mesmo e-mail, não as vincule automaticamente sem um mecanismo de verificação e uma regra de identidade definida.
Proteja o link e verifique quem o aceita
O link deve funcionar como uma credencial temporária. Use um token difícil de adivinhar, associado a um convite específico e com expiração verificada no servidor. Não inclua informações sensíveis na URL e evite expor o token em registros, ferramentas de análise ou páginas de terceiros. As recomendações da OWASP sobre gestão segura de credenciais e sessões podem servir como referência para revisar o projeto.
Ao abrir o link, mostre contexto suficiente para que a pessoa entenda a qual organização está ingressando e para qual endereço foi convidada. Antes de concluir a aceitação, verifique se ela controla esse e-mail. Se já estiver conectada com outra identidade, explique o conflito e peça que troque de conta ou conclua a verificação, em vez de vincular as duas identidades por conveniência.
A aceitação deve ser uma operação atômica: verificar se o convite continua pendente e válido, confirmar a identidade, criar a associação e marcar o convite como aceito. Se duas solicitações tentarem usar o mesmo link ao mesmo tempo, apenas uma deverá concluir a alteração. Uma segunda visita pode informar que o convite já foi utilizado, sem conceder acesso novamente.
Defina o que acontece quando as permissões mudam ou o convite é revogado
O convite pode incluir uma função inicial ou uma referência às permissões que serão aplicadas no momento da aceitação. Decida se essas permissões serão definidas no envio ou consultadas quando o convite for aceito. Defini-las no envio deixa explícita a oferta original; consultá-las no final permite refletir mudanças recentes, mas pode surpreender quem enviou o convite. Em ambos os casos, informe mudanças relevantes e evite ampliar permissões sem uma decisão deliberada.
Se o convite for revogado antes da aceitação, o link deverá deixar de funcionar e a pessoa convidada deverá receber uma mensagem neutra explicando que não pode mais concluir o processo. Não revele informações desnecessárias sobre a organização. Se a função ou o e-mail forem alterados, registre quem fez a mudança e quando, especialmente quando várias pessoas administrarem a organização.
Teste os casos extremos e monitore o fluxo
Os testes devem cobrir tanto o fluxo esperado quanto as transições que costumam gerar chamados de suporte. Inclua, no mínimo, a aceitação antes e depois da expiração, o reenvio com um link anterior, a revogação, o clique duplo, um convite repetido, uma conta existente, uma sessão com outro e-mail e a alteração da função enquanto o convite está pendente.
- Verifique se um token usado, expirado ou revogado não concede acesso.
- Confirme que uma falha no e-mail não altera por engano o estado de aceitação.
- Verifique se as novas tentativas não criam associações ou convites duplicados.
- Confira se as mensagens explicam o próximo passo sem revelar dados de terceiros.
Em produção, monitore a quantidade de convites pendentes, expirados, revogados e aceitos, além das falhas de envio e do tempo até a aceitação. Analise esses sinais em conjunto: muitos convites expirados podem indicar prazos inadequados ou e-mails que não chegam; muitos reenvios podem sugerir que a mensagem não está clara ou que o fluxo está travando. Uma métrica, por si só, não comprova a causa; por isso, combine o monitoramento com o suporte e testes de experiência.
A regra de projeto que conecta todo o fluxo é simples: cada convite deve ter um destinatário, um estado, um prazo e uma consequência inequívoca. Quando essas decisões estão documentadas, a equipe consegue resolver exceções sem confundir convites com contas, associações ou permissões gerais.