API RESTful moderna y escalable para sistema de Punto de Venta (POS), construida con NestJS, TypeORM y MySQL.
Sistema backend completo para la gestión de un punto de venta que incluye administración de productos, categorías, ventas, usuarios y reportes. La API cuenta con autenticación JWT, validación de datos, documentación automática con Swagger y control de acceso basado en roles.
- 🔐 Autenticación y Autorización: Sistema JWT con roles de usuario
- 📦 Gestión de Productos: CRUD completo con control de stock y SKU
- 🏷️ Categorías: Organización jerárquica de productos
- 💰 Ventas: Registro de ventas con detalle de productos
- 👥 Usuarios: Administración de usuarios con roles
- 📊 Reportes: Generación de reportes de ventas
- 📚 Documentación: API documentada con Swagger/OpenAPI
- ✅ Validación: Validación automática de datos con class-validator
- 🔄 CORS: Configuración de CORS habilitada
- Framework: NestJS v11
- Lenguaje: TypeScript
- ORM: TypeORM v0.3
- Base de Datos: MySQL
- Autenticación: JWT (Passport)
- Validación: class-validator & class-transformer
- Documentación: Swagger/OpenAPI
- Encriptación: bcrypt
- Testing: Jest
- Node.js >= 18.x
- npm >= 9.x
- MySQL >= 8.x
- Clonar el repositorio
git clone <repository-url>
cd pos-api- Instalar dependencias
npm install- Configurar variables de entorno
Crear un archivo .env en la raíz del proyecto:
# Puerto de la aplicación
PORT=3000
# Base de datos
DB_HOST=localhost
DB_PORT=3308
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=pos_db
# JWT
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=1d
# Entorno
NODE_ENV=development- Crear la base de datos
mysql -u root -p
CREATE DATABASE pos_db;npm run start:dev# Compilar
npm run build
# Ejecutar
npm run start:prodnpm run start:debugLa API estará disponible en http://localhost:3000/api/v1
La documentación interactiva de Swagger está disponible en:
http://localhost:3000/api/docs
POST /auth/register- Registrar nuevo usuarioPOST /auth/login- Iniciar sesiónGET /auth/profile- Obtener perfil del usuario autenticado
GET /users- Listar todos los usuariosGET /users/:id- Obtener usuario específicoPATCH /users/:id- Actualizar usuarioDELETE /users/:id- Eliminar usuario
POST /categories- Crear categoríaGET /categories- Listar todas las categoríasGET /categories/active- Listar categorías activasGET /categories/:id- Obtener categoría con sus productosPATCH /categories/:id- Actualizar categoríaDELETE /categories/:id- Eliminar categoría
POST /products- Crear productoGET /products- Listar todos los productosGET /products/active- Listar productos activosGET /products/low-stock- Listar productos con stock bajoGET /products/:id- Obtener producto específicoGET /products/sku/:sku- Buscar producto por SKUPATCH /products/:id- Actualizar productoPATCH /products/:id/stock- Actualizar stock del productoDELETE /products/:id- Eliminar producto
POST /sales- Registrar nueva ventaGET /sales- Listar todas las ventasGET /sales/:id- Obtener detalle de venta
- Endpoints para generación de reportes
src/
├── auth/ # Módulo de autenticación
│ ├── decorators/ # Decoradores personalizados
│ ├── dto/ # DTOs de autenticación
│ ├── guards/ # Guards de autenticación y roles
│ └── strategies/ # Estrategias de Passport
├── categories/ # Módulo de categorías
│ ├── dto/ # DTOs de categorías
│ └── entities/ # Entidad de categoría
├── config/ # Configuraciones
│ └── database.config.ts # Configuración de base de datos
├── products/ # Módulo de productos
│ ├── dto/ # DTOs de productos
│ └── entities/ # Entidad de producto
├── reports/ # Módulo de reportes
├── sales/ # Módulo de ventas
│ ├── dto/ # DTOs de ventas
│ └── entities/ # Entidades de venta
├── users/ # Módulo de usuarios
│ ├── dto/ # DTOs de usuarios
│ └── entities/ # Entidad de usuario
├── app.module.ts # Módulo raíz
└── main.ts # Punto de entrada de la aplicación
npm run testnpm run test:watchnpm run test:e2enpm run test:cov- Autenticación JWT: Tokens seguros con expiración configurable
- Hashing de Contraseñas: bcrypt para encriptación de contraseñas
- Validación de Datos: Validación automática de DTOs
- Guards: Protección de rutas con autenticación y roles
- CORS: Configuración de CORS para control de acceso
# Desarrollo
npm run start:dev # Iniciar en modo desarrollo (watch mode)
npm run start:debug # Iniciar en modo debug
# Producción
npm run build # Compilar el proyecto
npm run start:prod # Ejecutar versión de producción
# Calidad de Código
npm run lint # Ejecutar ESLint
npm run format # Formatear código con Prettier
# Testing
npm run test # Tests unitarios
npm run test:watch # Tests en modo watch
npm run test:cov # Tests con cobertura
npm run test:e2e # Tests end-to-endAsegúrate de configurar las siguientes variables de entorno en tu servidor de producción:
NODE_ENV=production
PORT=3000
DB_HOST=your-production-host
DB_PORT=3306
DB_USERNAME=your-db-user
DB_PASSWORD=your-secure-password
DB_DATABASE=pos_db
JWT_SECRET=your-very-secure-secret-key
JWT_EXPIRES_IN=1d# Compilar
npm run build
# La carpeta dist/ contendrá el código compilado
# Ejecutar con Node.js
node dist/main.jsSi deseas usar Docker, puedes crear un Dockerfile:
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/main"]- ✅ Usar DTOs para validación de datos
- ✅ Implementar guards para protección de rutas
- ✅ Validar entrada de usuarios con class-validator
- ✅ Usar decoradores personalizados para lógica reutilizable
- ✅ Separar lógica de negocio en servicios
- ✅ Documentar endpoints con Swagger
- ✅ Manejar errores con exception filters
- ✅ Usar variables de entorno para configuración
- Fork el proyecto
- Crea tu Feature Branch (
git checkout -b feature/AmazingFeature) - Commit tus cambios (
git commit -m 'Add some AmazingFeature') - Push al Branch (
git push origin feature/AmazingFeature) - Abre un Pull Request
Este proyecto es para uso libre.
Desarrollado con ❤️ para todos. By Diego Minaya y Cloude Code <3
Nota: Este proyecto está en desarrollo activo. Para reportar bugs o solicitar nuevas características, por favor crea un issue en el repositorio.