⚡ Berserker ERP API

🔗 Base URL: http://localhost:8080 📦 Content-Type: application/json 🔐 Autenticación: Bearer Token JWT

📋 Índice

👤 Usuarios / Auth 🎭 Roles 🔑 Permisos 🔢 Numeración 💰 Impuestos ⚠️ Respuestas de error 🗂️ Tablas BD 📌 Notas generales

👥 Módulo: Gestión de Usuarios (Autenticación)

POST /api/auth/register

🌐 Público 201 Created

Registrar usuario

Request body

{
  "nombreCompleto": "Carlos Ramírez",
  "correo": "carlos.ramirez@empresa.com",
  "contrasena": "MiClave123",
  "rol": "ROLE_USER"
}
        

Campo	Tipo	Requerido	Restricciones
nombreCompleto	string	✅	2–120 caracteres
correo	string	✅	Email válido, máx. 150
contrasena	string	✅	6–100 caracteres
rol	string	✅	"ROLE_USER" o "ROLE_ADMIN"

Response 201 Created

{
  "id": 1,
  "nombreCompleto": "Carlos Ramírez",
  "correo": "carlos.ramirez@empresa.com",
  "role": "ROLE_USER",
  "active": true
}
        

POST /api/auth/login

🌐 Público 200 OK

Iniciar sesión

{
  "correo": "carlos.ramirez@empresa.com",
  "contrasena": "MiClave123"
}
        

Response 200 OK

{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "userId": 1,
  "correo": "carlos.ramirez@empresa.com",
  "nombreCompleto": "Carlos Ramírez",
  "role": "ROLE_USER"
}
        

🔐 Usar el token en requests protegidos: Authorization: Bearer {token}

POST /api/usuarios/{id}/roles

🔐 Requiere Auth 200 OK

Asignar roles a usuario (acumulativo)

[1, 2] // Array de IDs de roles

Response 200 OK

{
  "id": 1,
  "nombreCompleto": "Carlos Ramírez",
  "correo": "carlos.ramirez@empresa.com",
  "roles": [
    { "id": 1, "nombre": "Administrador", "descripcion": "Acceso total al sistema" },
    { "id": 2, "nombre": "Vendedor", "descripcion": "Gestión de facturas y clientes" }
  ]
}
        

GET /api/usuarios/{id}/roles

🔐 Requiere Auth 200 OK

Listar roles de un usuario

{
  "id": 1,
  "nombreCompleto": "Carlos Ramírez",
  "correo": "carlos.ramirez@empresa.com",
  "roles": [ { "id": 1, "nombre": "Administrador", "descripcion": "Acceso total al sistema" } ]
}
        

DELETE /api/usuarios/{id}/roles/{rolId}

🔐 Requiere Auth 200 OK

Remover rol de usuario

{
  "id": 1,
  "nombreCompleto": "Carlos Ramírez",
  "correo": "carlos.ramirez@empresa.com",
  "roles": [ { "id": 1, "nombre": "Administrador" } ]
}
        

🎭 Módulo: Gestión de Roles

POST/api/roles

🔐 Requiere Auth 201 Created

{
  "nombre": "Administrador",
  "descripcion": "Acceso total al sistema"
}
        

Campo	Tipo	Req	Restricciones
nombre	string	✅	2–80, único
descripcion	string	❌	máx 255

{
  "id": 1,
  "nombre": "Administrador",
  "descripcion": "Acceso total al sistema",
  "active": true,
  "permisos": []
}
        

GET/api/roles

🔐 Requiere Auth 200 OK

[
  { "id":1, "nombre":"Administrador", "descripcion":"Acceso total", "active":true, "permisos":[{"id":1,"nombre":"CREAR_FACTURA"}] },
  { "id":2, "nombre":"Vendedor", "descripcion":"Gestión facturas", "active":true, "permisos":[] }
]
        

GET/api/roles/{id}

🔐 Requiere Auth 200 OK

{ "id":1, "nombre":"Administrador", "descripcion":"Acceso total", "active":true, "permisos":[...] }
        

PUT/api/roles/{id}

🔐 Requiere Auth 200 OK

{
  "nombre": "Super Administrador",
  "descripcion": "Acceso total y gestión de usuarios"
}
        

DELETE/api/roles/{id}

🔐 Requiere Auth 204 No Content

(sin cuerpo)

POST/api/roles/{id}/permisos

🔐 Requiere Auth 200 OK

Body: [1, 2, 3] (IDs de permisos)

{
  "id":1, "nombre":"Administrador", "active":true,
  "permisos":[
    {"id":1,"nombre":"CREAR_FACTURA"},
    {"id":2,"nombre":"VER_REPORTES"}
  ]
}
        

DELETE/api/roles/{id}/permisos/{permisoId}

🔐 Requiere Auth 200 OK

{
  "id":1, "nombre":"Administrador", "permisos":[{"id":1,"nombre":"CREAR_FACTURA"}]
}
        

🔑 Módulo: Gestión de Permisos

POST/api/permisos

🔐 Requiere Auth 201 Created

{
  "nombre": "CREAR_FACTURA",
  "descripcion": "Permite crear facturas"
}
        

nombre	string	2‑100, único
descripcion	string	máx 255

GET/api/permisos

🔐 Requiere Auth 200 OK

[ {"id":1,"nombre":"CREAR_FACTURA","descripcion":"...","active":true} ]

GET/api/permisos/{id}

🔐 Requiere Auth 200 OK

PUT/api/permisos/{id}

🔐 Requiere Auth 200 OK

DELETE/api/permisos/{id}

🔐 Requiere Auth 204 No Content

🔢 Módulo: Numeración

POST/api/numeracion

🔐 Requiere Auth 201 Created

{
  "tipoDocumento": "FACTURA",
  "serie": "FAC",
  "numeroActual": 1,
  "longitud": 8
}
        

Campo	Tipo	Req	Restricciones
tipoDocumento	string	✅	2‑60
serie	string	✅	1‑20
numeroActual	integer	✅	≥1
longitud	integer	✅	≥1 (ceros izq.)

{
  "id": 1,
  "tipoDocumento": "FACTURA",
  "serie": "FAC",
  "numeroActual": 1,
  "longitud": 8,
  "active": true
}
        

📌 Ejemplo generado: FAC-00000001

GET/api/numeracion

🔐 Requiere Auth 200 OK

GET/api/numeracion/{id}

🔐 Requiere Auth

PUT/api/numeracion/{id}

🔐 Requiere Auth 200 OK

DELETE/api/numeracion/{id}

🔐 Requiere Auth 204 No Content

💰 Módulo: Impuestos

POST/api/impuestos

🔐 Requiere Auth 201 Created

{
  "nombre": "IVA 12%",
  "codigo": "IVA12",
  "porcentaje": 12.00
}
        

nombre	string	2‑80
codigo	string	1‑20, único, se guarda mayúscula
porcentaje	decimal	0.00 - 999.99

{
  "id":1,"nombre":"IVA 12%","codigo":"IVA12","porcentaje":12.00,"active":true
}
        

GET/api/impuestos

🔐 Requiere Auth 200 OK

GET/api/impuestos/{id}

🔐 Requiere Auth

PUT/api/impuestos/{id}

🔐 Requiere Auth 200 OK

DELETE/api/impuestos/{id}

🔐 Requiere Auth 204 No Content

⚠️ Respuestas de Error

{
  "status": <código HTTP>,
  "message": "<descripción del error>"
}
    

Código	Escenario	Ejemplo mensaje
400	Validación campos	"nombre: size must be between 2 and 80"
400	Regla negocio	"Ya existe un rol con el nombre: Administrador"
401	Credenciales inválidas	"Credenciales inválidas"
401	Token ausente/expirado	"Unauthorized"
404	Recurso no encontrado	"Rol no encontrado con id: 99"
500	Error interno	"Mensaje interno del error"

// Ejemplo 400 duplicado
{ "status": 400, "message": "Ya existe un impuesto con el código: IVA12" }
    

// Ejemplo 404
{ "status": 404, "message": "Permiso no encontrado con id: 5" }
    

🗂️ Tablas de Base de Datos

Tabla	Módulo	Descripción
cg_usuarios	Usuarios	Usuarios del sistema
cg_roles	Roles	Roles de negocio
cg_permisos	Permisos	Permisos granulares
cg_rol_permisos	Roles/Permisos	Relación Rol ↔ Permiso (N:M)
cg_usuario_roles	Usuarios/Roles	Relación Usuario ↔ Rol (N:M)
cg_numeracion	Numeración	Series numéricas de documentos
cg_impuestos	Impuestos	Tasas impositivas

📌 Notas generales

📧 El correo siempre se almacena en minúsculas.
🔠 El código de impuesto siempre se almacena en mayúsculas.
⏳ El JWT tiene validez de 24 horas. Después, el usuario debe volver a hacer login.
🎭 Valores válidos para el campo rol en registro: "ROLE_USER" y "ROLE_ADMIN".
🔐 Todos los endpoints fuera de /api/auth/** requieren el header: Authorization: Bearer {token}.
➕ Las asignaciones (permisos a rol, roles a usuario) son acumulativas: no reemplazan los existentes, los agregan.

⚡ Berserker ERP API — Documentación generada a partir del Markdown original.