API de Permisos

Endpoints para gestionar permisos detallados. Los permisos definen qué acciones se pueden realizar sobre qué recursos.

Listar Permisos

Devuelve todos los permisos.

GET/v1/permissions

Permiso Requerido: read

Ejemplo de Solicitud:

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

Respuesta: 200 OK

{
  "total": 10,
  "quantity": 10,
  "records": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Manage Users",
      "description": "Full access to user management",
      "target": {
        "company_id": "*",
      },
      "actions": ["read", "create", "update", "delete"],
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Obtener Permiso

Devuelve un único permiso por ID.

GET/v1/permissions/:id

Permiso Requerido: read

Ejemplo de Solicitud:

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

Crear Permiso

Crea un nuevo permiso.

POST/v1/permissions

Permiso Requerido: create

Cuerpo de Solicitud:

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del permiso (mín 3 caracteres)
`description`	string	Sí	Descripción (mín 10 caracteres)
`target`	object	Sí	Objeto de alcance objetivo
`actions`	string[]	Sí	Acciones permitidas (mín 1)

Objeto Target:

Campo	Tipo	Requerido	Descripción
`company_id`	string	Sí	ID de compañía o `*`
`service_name`	string	No	Nombre del servicio (ej. `billing`)
`service_id`	string	No	ID de recurso o `*`

Acciones:

Valor	Descripción
`read`	Ver recursos
`create`	Crear recursos
`update`	Modificar recursos
`delete`	Eliminar recursos
`*`	Todas las acciones

Ejemplo de Solicitud:

curl -X POST https://api.console.solucao42.com.br/v1/permissions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Manager",
    "description": "Full access to billing features company-wide",
    "target": {
      "company_id": "507f1f77bcf86cd799439001",
      "service_name": "billing"
    },
    "actions": ["read", "create", "update"]
  }'

Respuesta: 201 Created

{
  "_id": "507f1f77bcf86cd799439015",
  "name": "Billing Manager",
  "description": "Full access to billing features company-wide",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "teamId": "*",
    "service_name": "billing"
  },
  "actions": ["read", "create", "update"],
  "created_at": "2024-03-01T10:30:00.000Z"
}

Actualizar Permiso

Actualiza un permiso existente.

PUT/v1/permissions/:id

Permiso Requerido: update

Cuerpo de Solicitud:

Todos los campos son opcionales. Solo incluye lo que quieras cambiar.

Campo	Tipo	Descripción
`name`	string	Nuevo nombre
`description`	string	Nueva descripción
`target`	object	Nuevo alcance objetivo
`actions`	string[]	Nuevas acciones permitidas

Ejemplo de Solicitud:

curl -X PUT https://api.console.solucao42.com.br/v1/permissions/PERMISSION_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": ["read"]
  }'

Eliminar Permiso

Elimina un permiso.

DELETE/v1/permissions/:id

Permiso Requerido: delete

Ejemplo de Solicitud:

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

Respuesta: 204 No Content

Objeto Permiso

Campo	Tipo	Descripción
`_id`	string	Identificador único
`name`	string	Nombre del permiso
`description`	string	Descripción
`target`	object	Definición de alcance
`actions`	string[]	Acciones permitidas
`created_at`	string	Timestamp de creación ISO 8601
`updated_at`	string	Timestamp de última actualización ISO 8601

Patrones de Target

Acceso a Nivel de Compañía

Acceso específico de compañía:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
  }
}

Acceso Específico de Servicio

Un servicio específico en toda la compañía:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "billing"
  }
}

Acceso Específico de Recurso

Un recurso específico en un servicio:

{
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "projects",
    "service_id": "507f1f77bcf86cd799439003"
  }
}

Acceso Global (Super Admin)

Todas las compañías (usar con extrema precaución):

{
  "target": {
    "company_id": "*",
  }
}

Ejemplos de Permisos

Gestor de Usuarios

{
  "name": "User Manager",
  "description": "Can view and manage all users in the company",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
  },
  "actions": ["read", "create", "update"]
}

Visor de Reportes

{
  "name": "Report Viewer",
  "description": "Read-only access to reports",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "teamId": "*",
    "service_name": "reports"
  },
  "actions": ["read"]
}

Administrador de Departamento

{
  "name": "Sales Admin",
  "description": "Full admin access for Sales department",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "sales"
  },
  "actions": ["*"]
}

Facturación Solo Lectura

{
  "name": "Billing Viewer",
  "description": "Can view billing information but not modify",
  "target": {
    "company_id": "507f1f77bcf86cd799439001",
    "service_name": "billing"
  },
  "actions": ["read"]
}

Validación de Formato de ID

Los IDs en el objeto target deben ser:

Un ObjectId de MongoDB válido: ^[a-f0-9]{24}$
El carácter comodín: *

Ejemplos Válidos:

507f1f77bcf86cd799439001
*

Ejemplos Inválidos:

my-company
123
null

Ejemplos de Código

JavaScript
cURL

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

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

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

// Eliminar permiso
async function deletePermission(token, permissionId) {
  const response = await fetch(`${API_URL}/v1/permissions/${permissionId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` },
  });
  return response.ok;
}

// Uso
const billingPermission = await createPermission(token, {
  name: 'Billing Manager',
  description: 'Manage billing company-wide',
  target: {
    company_id: 'company-id',
    service_name: 'billing'
  },
  actions: ['read', 'create', 'update']
});

console.log(`Created permission: ${billingPermission._id}`);

TOKEN="your-jwt-token"

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

# Crear permiso
curl -s -X POST "https://api.console.solucao42.com.br/v1/permissions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Billing Manager",
    "description": "Manage billing company-wide",
    "target": {
      "company_id": "507f1f77bcf86cd799439001",
      "service_name": "billing"
    },
    "actions": ["read", "create", "update"]
  }' | jq

# Actualizar permiso
curl -s -X PUT "https://api.console.solucao42.com.br/v1/permissions/PERMISSION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"actions": ["read"]}' | jq

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

Mejores Prácticas

Usa nombres descriptivos - Billing Manager es mejor que Permission 1
Sé específico - Los alcances limitados son más seguros que los comodines
Documenta los permisos - Incluye descripciones claras
Audita los cambios - Rastrea quién crea/modifica permisos
Prueba antes de producción - Verifica que los permisos funcionen como se espera

Listar Permisos​

Obtener Permiso​

Crear Permiso​

Actualizar Permiso​

Eliminar Permiso​

Objeto Permiso​

Patrones de Target​

Acceso a Nivel de Compañía​

Acceso Específico de Servicio​

Acceso Específico de Recurso​

Acceso Global (Super Admin)​

Ejemplos de Permisos​

Gestor de Usuarios​

Visor de Reportes​

Administrador de Departamento​

Facturación Solo Lectura​

Validación de Formato de ID​

Ejemplos de Código​

Mejores Prácticas​

Listar Permisos

Obtener Permiso

Crear Permiso

Actualizar Permiso

Eliminar Permiso

Objeto Permiso

Patrones de Target

Acceso a Nivel de Compañía

Acceso Específico de Servicio

Acceso Específico de Recurso

Acceso Global (Super Admin)

Ejemplos de Permisos

Gestor de Usuarios

Visor de Reportes

Administrador de Departamento

Facturación Solo Lectura

Validación de Formato de ID

Ejemplos de Código

Mejores Prácticas