API de Grupos

Endpoints para gestionar grupos y sus permisos. Los grupos se usan para implementar control de acceso basado en roles (RBAC).

Listar Grupos

Devuelve todos los grupos de la compañía.

GET/v1/groups

Permiso Requerido: 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_global`	boolean	true	Incluir grupos de sistema/globales

Ejemplo de Solicitud:

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

Respuesta: 200 OK

{
  "total": 4,
  "quantity": 4,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Administrators",
      "slug": "administrators",
      "description": "Full system access",
      "company_id": "507f1f77bcf86cd799439012",
      "is_global": false,
      "roles": [
        {
          "name": "Admin",
          "target": "*",
          "actions": ["*"]
        }
      ],
      "permissionIds": [],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Obtener Grupo

Devuelve un único grupo por ID.

GET/v1/groups/:id

Permiso Requerido: read

Ejemplo de Solicitud:

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

Crear Grupo

Crea un nuevo grupo.

POST/v1/groups

Permiso Requerido: create

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del grupo (mín 2 caracteres)
`slug`	string	Sí	Identificador seguro para URL
`description`	string	Sí	Descripción (mín 10 caracteres)
`roles`	object[]	No	Array de objetos de rol
`permissionIds`	string[]	No	IDs de permisos a asignar

Objeto Rol:

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del rol
`target`	string	Sí	Recurso objetivo (`*` para todos)
`actions`	string[]	Sí	Acciones permitidas (mín 1)

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Content Editors",
    "slug": "content-editors",
    "description": "Can create and edit content, but not delete",
    "roles": [
      {
        "name": "Content Manager",
        "target": "content",
        "actions": ["read", "create", "update"]
      }
    ]
  }'

Respuesta: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "name": "Content Editors",
  "slug": "content-editors",
  "description": "Can create and edit content, but not delete",
  "company_id": "507f1f77bcf86cd799439012",
  "is_global": false,
  "roles": [
    {
      "name": "Content Manager",
      "target": "content",
      "actions": ["read", "create", "update"]
    }
  ],
  "permissionIds": [],
  "created_at": "2024-03-01T10:30:00.000Z"
}

Patrón de Slug:

El slug debe coincidir con: ^[a-z0-9]+(?:-[a-z0-9]+)*$

Válido: editors, content-editors, team-a-editors Inválido: Editors, content_editors, content--editors

Actualizar Grupo

Actualiza un grupo existente.

PUT/v1/groups/:id

Permiso Requerido: update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`name`	string	No	Nuevo nombre del grupo
`slug`	string	No	Nuevo slug
`description`	string	No	Nueva descripción

Ejemplo de Solicitud:

curl -X PUT https://api.console.solucao42.com.br/v1/groups/GROUP_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Editors",
    "description": "Experienced content editors with expanded access"
  }'

Eliminar Grupo

Elimina un grupo.

DELETE/v1/groups/:id

Permiso Requerido: delete

Ejemplo de Solicitud:

curl -X DELETE https://api.console.solucao42.com.br/v1/groups/GROUP_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Respuesta: 204 No Content

Errores:

Estado	Código de Error	Descripción
400	`CANNOT_DELETE_GLOBAL`	No se pueden eliminar grupos de sistema

Agregar Permisos

Agrega permisos a un grupo (se añaden a los existentes).

POST/v1/groups/:id/permissions

Permiso Requerido: update

Cuerpo de Solicitud:

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

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-1", "perm-2"]
  }'

Reemplazar Permisos

Reemplaza todos los permisos de un grupo.

PUT/v1/groups/:id/permissions

Permiso Requerido: update

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`permissionIds`	string[]	Sí	Nuevos IDs de permisos

Ejemplo de Solicitud:

curl -X PUT https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-3", "perm-4"]
  }'

Eliminar Permisos

Elimina permisos específicos de un grupo.

DELETE/v1/groups/:id/permissions

Permiso Requerido: update

Cuerpo de Solicitud:

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

Ejemplo de Solicitud:

curl -X DELETE https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": ["perm-1"]
  }'

Objeto Grupo

Campo	Tipo	Descripción
`_id`	string	Identificador único
`name`	string	Nombre para mostrar
`slug`	string	Identificador seguro para URL
`description`	string	Descripción del grupo
`company_id`	string	ID de compañía padre
`is_global`	boolean	Si es un grupo de sistema
`roles`	object[]	Definiciones de roles
`permissionIds`	string[]	IDs de permisos asignados
`created_at`	string	Timestamp de creación ISO 8601
`updated_at`	string	Timestamp de última actualización ISO 8601

Objeto Rol

Campo	Tipo	Descripción
`name`	string	Nombre del rol
`target`	string	Recurso objetivo (ej. `users`, `content`, `*`)
`actions`	string[]	Acciones permitidas: `read`, `create`, `update`, `delete`, `*`

Patrones Comunes de Grupos

Admin con Acceso Total

{
  "name": "Administrators",
  "slug": "administrators",
  "description": "Full system access for administrators",
  "roles": [
    {
      "name": "Admin",
      "target": "*",
      "actions": ["*"]
    }
  ]
}

Visor Solo Lectura

{
  "name": "Viewers",
  "slug": "viewers",
  "description": "Read-only access to all resources",
  "roles": [
    {
      "name": "Viewer",
      "target": "*",
      "actions": ["read"]
    }
  ]
}

Editor de Recurso Específico

{
  "name": "Content Editors",
  "slug": "content-editors",
  "description": "Can manage content but not other resources",
  "roles": [
    {
      "name": "Content Manager",
      "target": "content",
      "actions": ["read", "create", "update", "delete"]
    },
    {
      "name": "User Viewer",
      "target": "users",
      "actions": ["read"]
    }
  ]
}

Ejemplos de Código

JavaScript
cURL

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

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

// Crear grupo
async function createGroup(token, group) {
  const response = await fetch(`${API_URL}/v1/groups`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(group),
  });
  return response.json();
}

// Agregar permisos a grupo
async function addPermissions(token, groupId, permissionIds) {
  const response = await fetch(`${API_URL}/v1/groups/${groupId}/permissions`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ permissionIds }),
  });
  return response.json();
}

// Uso
const newGroup = await createGroup(token, {
  name: 'Editors',
  slug: 'editors',
  description: 'Content editors with limited access',
  roles: [
    { name: 'Editor', target: 'content', actions: ['read', 'update'] }
  ]
});

await addPermissions(token, newGroup._id, ['perm-1', 'perm-2']);

TOKEN="your-jwt-token"

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

# Crear grupo
curl -s -X POST "https://api.console.solucao42.com.br/v1/groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Editors",
    "slug": "editors",
    "description": "Content editors with limited access",
    "roles": [{"name": "Editor", "target": "content", "actions": ["read", "update"]}]
  }' | jq

# Agregar permisos
curl -s -X POST "https://api.console.solucao42.com.br/v1/groups/GROUP_ID/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissionIds": ["perm-1", "perm-2"]}' | jq

# Eliminar grupo
curl -s -X DELETE "https://api.console.solucao42.com.br/v1/groups/GROUP_ID" \
  -H "Authorization: Bearer $TOKEN"

Listar Grupos​

Obtener Grupo​

Crear Grupo​

Actualizar Grupo​

Eliminar Grupo​

Agregar Permisos​

Reemplazar Permisos​

Eliminar Permisos​

Objeto Grupo​

Objeto Rol​

Patrones Comunes de Grupos​

Admin con Acceso Total​

Visor Solo Lectura​

Editor de Recurso Específico​

Ejemplos de Código​

Listar Grupos

Obtener Grupo

Crear Grupo

Actualizar Grupo

Eliminar Grupo

Agregar Permisos

Reemplazar Permisos

Eliminar Permisos

Objeto Grupo

Objeto Rol

Patrones Comunes de Grupos

Admin con Acceso Total

Visor Solo Lectura

Editor de Recurso Específico

Ejemplos de Código