Convide usuários para projetos ou empresas com níveis de acesso específicos e funções personalizadas.
Convidar um Usuário
A inviteUser
mutação permite que você convide usuários para seus projetos ou empresas da Blue. Os usuários podem ser atribuídos a níveis de acesso predefinidos ou funções personalizadas com permissões específicas.
Exemplo Básico
Convide um usuário com um nível de acesso padrão:
mutation InviteUserToProject {
inviteUser(
input: {
email: "newuser@example.com"
projectId: "web-redesign"
accessLevel: MEMBER
}
)
}
Exemplo Avançado
Convide um usuário com uma função personalizada para múltiplos projetos:
mutation InviteUserWithCustomRole {
inviteUser(
input: {
email: "contractor@example.com"
projectIds: ["web-redesign", "mobile-app", "api-v2"]
accessLevel: MEMBER
roleId: "role_contractor_123"
}
)
}
Parâmetros de Entrada
InviteUserInput
Parâmetro | Tipo | Obrigatório | Descrição |
---|---|---|---|
email |
String! | ✅ Sim | Endereço de e-mail do usuário a ser convidado |
accessLevel |
UserAccessLevel! | ✅ Sim | Nível de acesso a conceder (veja a tabela abaixo) |
projectId |
String | Não | ID de um único projeto (mutuamente exclusivo com companyId) |
projectIds |
[String!] | Não | Múltiplos IDs de projeto ao usar companyId |
companyId |
String | Não | ID da empresa para convite em nível de empresa (mutuamente exclusivo com projectId) |
roleId |
String | Não | ID da função personalizada (requer accessLevel: MEMBER) |
Valores de UserAccessLevel
Valor | Descrição |
---|---|
OWNER |
Controle total sobre projeto/empresa |
ADMIN |
Acesso administrativo, pode gerenciar usuários e configurações |
MEMBER |
Acesso padrão de membro com funcionalidade total |
CLIENT |
Acesso limitado para clientes externos |
COMMENT_ONLY |
Pode apenas visualizar e comentar registros |
VIEW_ONLY |
Acesso somente leitura ao projeto |
Campos de Resposta
Campo | Tipo | Descrição |
---|---|---|
success |
Boolean! | Se o convite foi enviado com sucesso |
Permissões Necessárias
Os usuários devem ter permissões suficientes para convidar outros. A hierarquia de permissões é aplicada:
Seu Papel | Pode Convidar |
---|---|
OWNER |
✅ Todos os níveis de acesso |
ADMIN |
✅ ADMIN, MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY (não pode convidar OWNER) |
MEMBER |
✅ MEMBER, CLIENT, COMMENT_ONLY, VIEW_ONLY (não pode convidar OWNER ou ADMIN) |
CLIENT |
✅ CLIENT apenas |
COMMENT_ONLY |
❌ Não pode convidar |
VIEW_ONLY |
❌ Não pode convidar |
Nota: Para convites de empresa (usando companyId
), apenas PROPRIETÁRIOS da empresa podem convidar usuários.
Tipos de Convite
Convite de Projeto
Convide um usuário para um único projeto:
- Use o parâmetro
projectId
- Não pode usar
companyId
simultaneamente - O convidador deve ter acesso ao projeto
- Restrições de nível de acesso se aplicam
Convite de Empresa
Convide um usuário para uma empresa (e opcionalmente projetos específicos):
- Use o parâmetro
companyId
- Não pode usar
projectId
simultaneamente - Apenas PROPRIETÁRIOS da empresa podem usar este método
- Use o array
projectIds
para especificar quais projetos incluir - Se
projectIds
for omitido, o usuário recebe apenas acesso à empresa
Funções Personalizadas
Ao usar funções personalizadas:
- Defina
accessLevel
paraMEMBER
- Forneça o
roleId
da sua função personalizada - O usuário herdará todas as permissões definidas na função personalizada
- Funções personalizadas são específicas para o projeto
Para recuperar funções personalizadas disponíveis, use a projectUserRoles
consulta.
Respostas de Erro
Usuário Já no Projeto
{
"errors": [{
"message": "User is already in the project.",
"extensions": {
"code": "USER_ALREADY_IN_THE_PROJECT"
}
}]
}
Permissões Insuficientes
{
"errors": [{
"message": "You don't have permission to invite users with this access level",
"extensions": {
"code": "UNAUTHORIZED"
}
}]
}
Projeto Inválido
{
"errors": [{
"message": "Project not found",
"extensions": {
"code": "PROJECT_NOT_FOUND"
}
}]
}
Limite de Convite Excedido
{
"errors": [{
"message": "Unable to invite more people.",
"extensions": {
"code": "INVITATION_LIMIT"
}
}]
}
Não é Possível Convidar a Si Mesmo
{
"errors": [{
"message": "You are not allowed to add yourself.",
"extensions": {
"code": "ADD_SELF"
}
}]
}
Função Personalizada Inválida
{
"errors": [{
"message": "Project user role was not found.",
"extensions": {
"code": "PROJECT_USER_ROLE_NOT_FOUND"
}
}]
}
Empresa Banida
{
"errors": [{
"message": "Company is banned",
"extensions": {
"code": "COMPANY_BANNED"
}
}]
}
Notas Importantes
- Validação de E-mail: Endereços de e-mail são normalizados e validados antes do envio de convites
- Expiração do Convite: Convites expiram após 7 dias e devem ser reenviados se não forem aceitos
- Notificações Automáticas: A Blue envia automaticamente e-mails de convite para novos usuários
- Proprietários da Empresa: Proprietários da empresa recebem automaticamente acesso ADMIN em todos os projetos
- Impacto na Cobrança: Adicionar usuários pode afetar sua assinatura se você tiver preços por usuário
- Registro de Atividades: Todos os convites de usuários são registrados para fins de auditoria
- Exclusividade de Parâmetros: Você deve fornecer
projectId
OUcompanyId
, não ambos - Restrições da Empresa: Apenas proprietários da empresa podem usar o parâmetro
companyId
- Auto-Convidar: Usuários não podem se convidar (gerará erro
ADD_SELF
)
Operações Relacionadas
- Listar Usuários - Veja todos os usuários em um projeto ou empresa
- Remover Usuário - Remover usuários de projetos
- Funções Personalizadas - Gerenciar funções de usuário personalizadas