Usuarios - Sistema de Facturación Electrónica SUNAT

Información General

Los endpoints de usuarios permiten gestionar cuentas de usuario, asignar roles y configurar permisos para controlar el acceso a diferentes funcionalidades del sistema. Todos los usuarios están asociados a una empresa y tienen un rol que define sus permisos.

Listar Usuarios

Obtiene la lista de todos los usuarios del sistema con sus relaciones de rol y empresa.

Respuesta

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Juan Pérez",
      "email": "[email protected]",
      "rol_id": 1,
      "id_empresa": 1,
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-03-01T14:20:00.000000Z",
      "rol": {
        "rol_id": 1,
        "nombre": "Administrador"
      },
      "empresa": {
        "id_empresa": 1,
        "comercial": "J.V.C. SAC",
        "ruc": "20612706702"
      }
    },
    {
      "id": 2,
      "name": "María García",
      "email": "[email protected]",
      "rol_id": 2,
      "id_empresa": 1,
      "created_at": "2024-02-10T08:15:00.000000Z",
      "updated_at": "2024-02-10T08:15:00.000000Z",
      "rol": {
        "rol_id": 2,
        "nombre": "Vendedor"
      },
      "empresa": {
        "id_empresa": 1,
        "comercial": "J.V.C. SAC",
        "ruc": "20612706702"
      }
    }
  ]
}

Crear Usuario

Crea un nuevo usuario en el sistema con un rol y empresa asignados.

Parámetros del Body

Ejemplo de Solicitud

{
  "name": "Carlos Rodríguez",
  "email": "[email protected]",
  "password": "segura123",
  "password_confirmation": "segura123",
  "rol_id": 3,
  "id_empresa": 1
}

Respuesta Exitosa

{
  "success": true,
  "message": "Usuario creado exitosamente",
  "data": {
    "id": 3,
    "name": "Carlos Rodríguez",
    "email": "[email protected]",
    "rol_id": 3,
    "id_empresa": 1,
    "created_at": "2024-03-04T10:30:00.000000Z",
    "updated_at": "2024-03-04T10:30:00.000000Z"
  }
}

Errores de Validación

{
  "success": false,
  "message": "Error de validación",
  "errors": {
    "email": [
      "El campo email ya ha sido tomado."
    ],
    "password": [
      "El campo password debe tener al menos 6 caracteres."
    ]
  }
}

Obtener Usuario

Obtiene los detalles de un usuario específico con sus relaciones.

Parámetros de Ruta

Respuesta

{
  "success": true,
  "data": {
    "id": 2,
    "name": "María García",
    "email": "[email protected]",
    "rol_id": 2,
    "id_empresa": 1,
    "created_at": "2024-02-10T08:15:00.000000Z",
    "updated_at": "2024-02-10T08:15:00.000000Z",
    "rol": {
      "rol_id": 2,
      "nombre": "Vendedor"
    },
    "empresa": {
      "id_empresa": 1,
      "comercial": "J.V.C. SAC",
      "ruc": "20612706702"
    }
  }
}

Actualizar Usuario

Actualiza los datos de un usuario existente. Todos los campos son opcionales.

Parámetros de Ruta

Parámetros del Body

Ejemplo de Solicitud

{
  "name": "María García Sánchez",
  "rol_id": 3
}

Respuesta Exitosa

{
  "success": true,
  "message": "Usuario actualizado exitosamente",
  "data": {
    "id": 2,
    "name": "María García Sánchez",
    "email": "[email protected]",
    "rol_id": 3,
    "id_empresa": 1,
    "updated_at": "2024-03-04T11:45:00.000000Z"
  }
}

Eliminar Usuario

Elimina un usuario del sistema.

Parámetros de Ruta

Respuesta Exitosa

{
  "success": true,
  "message": "Usuario eliminado exitosamente"
}

Errores

Obtener Roles

Obtiene la lista de roles disponibles en el sistema para asignar a usuarios.

Respuesta

{
  "success": true,
  "data": [
    {
      "rol_id": 1,
      "nombre": "Administrador"
    },
    {
      "rol_id": 2,
      "nombre": "Vendedor"
    },
    {
      "rol_id": 3,
      "nombre": "Almacenero"
    },
    {
      "rol_id": 4,
      "nombre": "Contador"
    }
  ]
}

Sistema de Permisos

Listar Todos los Permisos

Obtiene todos los permisos del sistema agrupados por módulo.

Respuesta

{
  "success": true,
  "data": [
    {
      "module": "ventas",
      "module_name": "Ventas",
      "permissions": [
        {
          "id": 1,
          "name": "ventas.view",
          "display_name": "Ver ventas",
          "action": "view"
        },
        {
          "id": 2,
          "name": "ventas.create",
          "display_name": "Crear ventas",
          "action": "create"
        },
        {
          "id": 3,
          "name": "ventas.edit",
          "display_name": "Editar ventas",
          "action": "edit"
        },
        {
          "id": 4,
          "name": "ventas.delete",
          "display_name": "Eliminar ventas",
          "action": "delete"
        }
      ]
    },
    {
      "module": "productos",
      "module_name": "Productos",
      "permissions": [
        {
          "id": 5,
          "name": "productos.view",
          "display_name": "Ver productos",
          "action": "view"
        },
        {
          "id": 6,
          "name": "productos.create",
          "display_name": "Crear productos",
          "action": "create"
        }
      ]
    }
  ]
}

Obtener Permisos del Usuario Actual

Obtiene la lista de permisos del usuario autenticado.

Respuesta

{
  "success": true,
  "permissions": [
    "ventas.view",
    "ventas.create",
    "ventas.edit",
    "productos.view",
    "clientes.view",
    "clientes.create"
  ]
}

Obtener Permisos de un Rol

Obtiene los permisos asignados a un rol específico.

Parámetros de Ruta

Respuesta

{
  "success": true,
  "data": {
    "rol_id": 2,
    "rol_name": "Vendedor",
    "permissions": [1, 2, 3, 5, 9, 10, 11]
  }
}

Actualizar Permisos de un Rol

Actualiza los permisos asignados a un rol específico.

Parámetros de Ruta

Parámetros del Body

Ejemplo de Solicitud

{
  "permissions": [1, 2, 3, 5, 6, 9, 10]
}

Respuesta Exitosa

{
  "success": true,
  "message": "Permisos actualizados correctamente",
  "should_reload": true
}

Middleware de Permisos

Los endpoints protegidos usan el middleware permission con el formato recurso.accion:

// Ejemplo en routes/api.php
Route::get('productos', [ProductoController::class, 'index'])
    ->middleware('permission:productos.view');

Route::post('ventas', [VentasController::class, 'store'])
    ->middleware('permission:ventas.create');

Formato de Permisos

ventas.view - Ver ventas
ventas.create - Crear ventas
ventas.edit - Editar ventas
ventas.delete - Eliminar ventas
productos.view - Ver productos
clientes.create - Crear clientes
cotizaciones.view - Ver cotizaciones

Bypass para Administradores

Modelo de Datos

Tabla: users

Campo	Tipo	Descripción
id	BIGINT	Primary key
name	VARCHAR(255)	Nombre del usuario
email	VARCHAR(255)	Email único
password	VARCHAR(255)	Hash bcrypt de la contraseña
rol_id	INT	FK a tabla roles
id_empresa	INT	FK a tabla empresas
num_doc	VARCHAR(20)	Número de documento
nombres	VARCHAR(100)	Nombres
apellidos	VARCHAR(100)	Apellidos
telefono	VARCHAR(30)	Teléfono
estado	CHAR(1)	1=Activo, 0=Inactivo
foto_perfil	VARCHAR(255)	Ruta de foto
created_at	TIMESTAMP	Fecha de creación
updated_at	TIMESTAMP	Fecha de actualización

Tabla: roles

Campo	Tipo	Descripción
rol_id	INT	Primary key
nombre	VARCHAR(100)	Nombre del rol
descripcion	TEXT	Descripción del rol

Tabla: permissions

Campo	Tipo	Descripción
permission_id	INT	Primary key
name	VARCHAR(100)	Nombre técnico (ej: ventas.view)
display_name	VARCHAR(255)	Nombre para mostrar
module	VARCHAR(50)	Módulo al que pertenece
action	VARCHAR(50)	Acción (view, create, edit, delete)

Relación: permission_rol (Pivot)

Campo	Tipo	Descripción
id	BIGINT	Primary key
rol_id	INT	FK a roles
permission_id	INT	FK a permissions

Autenticación

Endpoints

Recursos

​Información General

​Listar Usuarios

​Respuesta

​Crear Usuario

​Parámetros del Body

​Ejemplo de Solicitud

​Respuesta Exitosa

​Errores de Validación

​Obtener Usuario

​Parámetros de Ruta

​Respuesta

​Actualizar Usuario

​Parámetros de Ruta

​Parámetros del Body

​Ejemplo de Solicitud

​Respuesta Exitosa

​Eliminar Usuario

​Parámetros de Ruta

​Respuesta Exitosa

​Errores

​Obtener Roles

​Respuesta

​Sistema de Permisos

​Listar Todos los Permisos

​Respuesta

​Obtener Permisos del Usuario Actual

​Respuesta

​Obtener Permisos de un Rol

​Parámetros de Ruta

​Respuesta

​Actualizar Permisos de un Rol

​Parámetros de Ruta

​Parámetros del Body

​Ejemplo de Solicitud

​Respuesta Exitosa

​Middleware de Permisos

​Formato de Permisos

​Bypass para Administradores

​Modelo de Datos

​Tabla: users

​Tabla: roles

​Tabla: permissions

​Relación: permission_rol (Pivot)

Build docs developers (and LLMs) love

Información General

Listar Usuarios

Respuesta

Crear Usuario

Parámetros del Body

Ejemplo de Solicitud

Respuesta Exitosa

Errores de Validación

Obtener Usuario

Parámetros de Ruta

Respuesta

Actualizar Usuario

Parámetros de Ruta

Parámetros del Body

Ejemplo de Solicitud

Respuesta Exitosa

Eliminar Usuario

Parámetros de Ruta

Respuesta Exitosa

Errores

Obtener Roles

Respuesta

Sistema de Permisos

Listar Todos los Permisos

Respuesta

Obtener Permisos del Usuario Actual

Respuesta

Obtener Permisos de un Rol

Parámetros de Ruta

Respuesta

Actualizar Permisos de un Rol

Parámetros de Ruta

Parámetros del Body

Ejemplo de Solicitud

Respuesta Exitosa

Middleware de Permisos

Formato de Permisos

Bypass para Administradores

Modelo de Datos

Tabla: users

Tabla: roles

Tabla: permissions

Relación: permission_rol (Pivot)