API de Usuarios

Endpoints para gestionar usuarios, invitaciones y asignaciones de grupos.

Listar Usuarios

Devuelve todos los usuarios de la compañía.

GET/v1/users

Permiso Requerido: user:read

Parámetros de Consulta:

Parámetro	Tipo	Por defecto	Descripción
`page`	integer	1	Número de página
`per_page`	integer	20	Elementos por página (máx: 100)
`include`	string	-	Establecer como `groups` para datos expandidos de grupos

Ejemplo de Solicitud:

curl "https://api.console.solucao42.com.br/v1/users?include=groups" \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 200 OK

{
  "total": 25,
  "quantity": 20,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "email": "[email protected]",
      "name": "John Doe",
      "company_id": "507f1f77bcf86cd799439012",
      "status": "active",
      "group_ids": ["admin-group"],
      "groups": [
        {
          "_id": "admin-group",
          "name": "Administrators",
          "slug": "administrators"
        }
      ],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Obtener Usuario

Devuelve un único usuario por ID.

GET/v1/users/:id

Permiso Requerido: user:read

Ejemplo de Solicitud:

curl https://api.console.solucao42.com.br/v1/users/507f1f77bcf86cd799439011 \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "name": "John Doe",
  "company_id": "507f1f77bcf86cd799439012",
  "status": "active",
  "teams": ["default-team"],
  "group_ids": ["admin-group"],
  "created_at": "2024-01-15T10:30:00.000Z"
}

Invitar Usuario

Invita a un nuevo usuario a la compañía. Recibirán un email para establecer su contraseña.

POST/v1/users/invite

Permiso Requerido: user:update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de email del usuario
`team_ids`	string[]	No	Equipos a asignar
`group_ids`	string[]	No	Grupos a asignar

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "group_ids": ["editors"]
  }'

Respuesta: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "email": "[email protected]",
  "company_id": "507f1f77bcf86cd799439012",
  "status": "invited",
  "teams": ["default-team"],
  "group_ids": ["editors"],
  "invitation_expires_at": "2024-03-08T10:30:00.000Z",
  "created_at": "2024-03-01T10:30:00.000Z"
}

Errores:

Estado	Código de Error	Descripción
400	`USER_EMAIL_DUPLICATE`	El email ya existe
422	`VALIDATION_ERROR`	Formato de email inválido

Aceptar Invitación

Acepta una invitación y establece la contraseña del usuario. No requiere autenticación.

POST/v1/users/accept-invitation

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`token`	string	Sí	Token de invitación del email
`password`	string	Sí	Nueva contraseña (mín 12 caracteres)

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/accept-invitation \
  -H "Content-Type: application/json" \
  -d '{
    "token": "invitation-token-from-email",
    "password": "SecurePassword123!"
  }'

Respuesta: 200 OK

{
  "success": true,
  "user": {
    "_id": "507f1f77bcf86cd799439015",
    "email": "[email protected]",
    "status": "active"
  }
}

Errores:

Estado	Código de Error	Descripción
400	`INVALID_INVITATION_TOKEN`	Token expirado o inválido
422	`VALIDATION_ERROR`	La contraseña no cumple los requisitos

Solicitar Restablecimiento de Contraseña

Envía un email de restablecimiento de contraseña. No requiere autenticación.

POST/v1/users/reset-password/request

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de email del usuario

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/reset-password/request \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Respuesta: 200 OK

{
  "success": true,
  "message": "If the email exists, a reset link has been sent"
}

Nota de Seguridad

La respuesta es siempre la misma independientemente de si el email existe. Esto previene ataques de enumeración de emails.

Activar Usuario

Activa un usuario desactivado.

POST/v1/users/:id/activate

Permiso Requerido: user:update

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/activate \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "status": "active"
}

Desactivar Usuario

Desactiva un usuario. No podrá iniciar sesión.

POST/v1/users/:id/deactivate

Permiso Requerido: user:update

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/deactivate \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 200 OK

{
  "_id": "507f1f77bcf86cd799439011",
  "email": "[email protected]",
  "status": "inactive"
}

Errores:

Estado	Código de Error	Descripción
400	`CANNOT_DEACTIVATE_SELF`	No puedes desactivarte a ti mismo

Agregar Grupos a Usuario

Agrega grupos a un usuario (se añaden a los existentes).

POST/v1/users/:id/groups

Permiso Requerido: user:update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`group_ids`	string[]	Sí	IDs de grupos a agregar (mín 1)

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["editors", "viewers"]
  }'

Respuesta: 200 OK

Devuelve el objeto de usuario actualizado.

Reemplazar Grupos de Usuario

Reemplaza todos los grupos de un usuario.

PUT/v1/users/:id/groups

Permiso Requerido: user:update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`group_ids`	string[]	Sí	Nuevos IDs de grupos (reemplaza todos)

Ejemplo de Solicitud:

curl -X PUT https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["managers"]
  }'

Eliminar Grupos de Usuario

Elimina grupos específicos de un usuario.

DELETE/v1/users/:id/groups

Permiso Requerido: user:update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`group_ids`	string[]	Sí	IDs de grupos a eliminar

Ejemplo de Solicitud:

curl -X DELETE https://api.console.solucao42.com.br/v1/users/USER_ID/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "group_ids": ["viewers"]
  }'

Objeto Usuario

Campo	Tipo	Descripción
`_id`	string	Identificador único
`email`	string	Dirección de email (único por compañía)
`name`	string	Nombre para mostrar
`company_id`	string	ID de compañía padre
`status`	string	`invited`, `active`, o `inactive`
`group_ids`	string[]	IDs de grupos asignados al usuario
`groups`	object[]	Objetos de grupo expandidos (cuando `include=groups`)
`created_at`	string	Timestamp de creación ISO 8601

Estado de Usuario

Estado	Descripción
`invited`	El usuario recibió invitación, no la ha aceptado
`active`	El usuario está activo y puede iniciar sesión
`inactive`	El usuario está desactivado, no puede iniciar sesión

Ejemplos de Código

JavaScript
cURL

const API_URL = 'https://api.console.solucao42.com.br';

// Listar usuarios con grupos
async function listUsers(token) {
  const response = await fetch(`${API_URL}/v1/users?include=groups`, {
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.json();
}

// Invitar usuario
async function inviteUser(token, email, group_ids = []) {
  const response = await fetch(`${API_URL}/v1/users/invite`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ email, group_ids }),
  });
  return response.json();
}

// Gestionar grupos de usuario
async function setUserGroups(token, userId, group_ids) {
  const response = await fetch(`${API_URL}/v1/users/${userId}/groups`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ group_ids }),
  });
  return response.json();
}

// Desactivar usuario
async function deactivateUser(token, userId) {
  const response = await fetch(`${API_URL}/v1/users/${userId}/deactivate`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.json();
}

TOKEN="your-jwt-token"

# Listar usuarios
curl -s "https://api.console.solucao42.com.br/v1/users?include=groups" \
  -H "Authorization: Bearer $TOKEN" | jq

# Invitar usuario
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/invite" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","group_ids":["editors"]}' | jq

# Agregar grupos
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/USER_ID/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"group_ids":["managers"]}' | jq

# Desactivar usuario
curl -s -X POST "https://api.console.solucao42.com.br/v1/users/USER_ID/deactivate" \
  -H "Authorization: Bearer $TOKEN" | jq

Listar Usuarios​

Obtener Usuario​

Invitar Usuario​

Aceptar Invitación​

Solicitar Restablecimiento de Contraseña​

Activar Usuario​

Desactivar Usuario​

Agregar Grupos a Usuario​

Reemplazar Grupos de Usuario​

Eliminar Grupos de Usuario​

Objeto Usuario​

Estado de Usuario​

Ejemplos de Código​

Listar Usuarios

Obtener Usuario

Invitar Usuario

Aceptar Invitación

Solicitar Restablecimiento de Contraseña

Activar Usuario

Desactivar Usuario

Agregar Grupos a Usuario

Reemplazar Grupos de Usuario

Eliminar Grupos de Usuario

Objeto Usuario

Estado de Usuario

Ejemplos de Código