Paint Store API

Full-featured REST API for a retail ERP system built for a paint and coatings store. Manages products, inventory across multiple branches, sales (including POS), purchasing, cash register, color formulas, and more.

Tech Stack

• Runtime: Node.js 18+
• Framework: Express 5
• ORM: Sequelize 6
• Database: MySQL 8+
• Auth: JWT + bcrypt
• Security: Helmet, CORS, express-rate-limit
• Validation: express-validator
• PDF Generation: pdfkit
• Data Import: xlsx, pdf-parse, papaparse
• Testing: Jest + Supertest

Features

• JWT Authentication with role-based access control (admin / vendedor)
• Multi-branch architecture — inventory, sales, and cash registers are scoped per branch; admins can operate across all branches, regular users are restricted to their assigned branch
• Product catalog with categories, measurement units (gallon-based scaling), multiple price lists, combos with recipes
• POS & Sales — direct POS sales and quote-to-sale conversion with stock validation and automatic cash register entries
• Cash register management — open/close, operational expenses, movements tied to sales and donations
• Purchasing — purchase orders with PDF export, receiving with quantity adjustments, automatic inventory entries
• Inter-branch transfers — transfer stock between branches with confirmation workflow
• Color formula system — formula definitions with colorants and amounts by presentation size, imported from Excel/PDF
• Automotive color registry — per-vehicle plate records with formula scaling between presentation sizes
• Data import pipelines — bulk product import from JSON with category/unit auto-creation
• PDF export — purchase order documents generated server-side with pdfkit
• Standardized API responses — consistent { tipo, datos, msj } response shape across all endpoints

Architecture

src/
├── config/          # Database, CORS, email, multer configuration
├── middleware/       # JWT auth & admin authorization
├── helpers/          # Response formatting, validation, branch-by-role logic
├── models/           # Sequelize models organized by domain
│   ├── catalogos/    # Categories, units, price lists
│   ├── productos/    # Products, prices, combos, recipes
│   ├── inventario/   # Stock per branch
│   ├── ventas/       # Sales, quotes, line items
│   ├── caja/         # Cash register, movements, expenses
│   ├── compras/      # Purchase orders, receiving, entries
│   ├── formulas/     # Color formula systems and colorants
│   ├── transferencias/
│   ├── clientes/
│   ├── proveedores/
│   ├── registroColores/
│   ├── sucursales/
│   └── usuarios/
├── controller/       # Business logic per domain (mirrors models)
├── routes/           # Express route definitions per domain
└── api/              # Internal API helpers

Getting Started

Prerequisites

• Node.js 18+
• MySQL 8+

Setup

# Install dependencies
npm install

# Copy environment config
cp .env.example .env
# Edit .env with your MySQL credentials

# Create the database
mysql -u root -e "CREATE DATABASE paint_store_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Run migrations (Sequelize sync)
npm run migrate

# Seed initial data (admin user, categories, units, branches)
npm run seed

Run

# Development (with hot reload)
npm run dev

# Production
npm start

The API starts on http://localhost:4001 by default.

Demo Credentials

• Email: admin@demo.com
• Password: admin123

API Endpoints

All endpoints return { tipo, datos, msj }. Protected routes require header x-auth-token with a valid JWT.

Module	Endpoints
Auth	POST /api/auth/login
Users	GET /api/usuarios/perfil, PUT /api/usuarios/perfil
Categories	GET/POST /api/categorias, GET/PUT/DELETE/PATCH /:id
Units	GET/POST /api/unidades-medida, GET/PUT/DELETE/PATCH /:id
Price Lists	GET/POST /api/listas-precios, GET/PUT/DELETE /:id
Branches	GET/PUT /api/sucursales
Employees	GET /api/empleados
Client Groups	GET /api/grupos-cliente
Products	GET/POST /api/productos, GET/PATCH /:id, prices CRUD
Inventory	GET /api/inventario/:branchId, adjustments, low-stock alerts
Formulas	GET/POST /api/formulas, GET /:id
Suppliers	GET/POST /api/proveedores, GET/PUT/PATCH /:id
Clients	GET/POST /api/clientes, GET/PUT/PATCH /:id
Quotes	GET/POST /api/cotizaciones, GET /:id, POST /:id/convertir
Sales	GET /api/ventas, GET /:id, POST /pos
Cash Register	GET /api/caja/estado/:branchId, open/close, expenses
Donations	GET/POST /api/donaciones, file upload
Purchase Orders	GET/POST /api/pedidos-compra, receive, PDF export
Transfers	GET/POST /api/transferencias, confirm
Auto Colors	GET/POST /api/registro-colores-automotriz, scale formula
Health	GET /api/health

See docs/API_DEMO1.md for detailed endpoint documentation with request/response examples.

Environment Variables

Variable	Description	Default
PORT	Server port	4001
MYSQL_DB	Database name	paint_store_db
MYSQL_USER	Database user	root
MYSQL_PASSWORD	Database password	(empty)
MYSQL_HOST	Database host	localhost
MYSQL_PORT	Database port	3306
JWT_SECRET	Secret for JWT signing	(required)

License

UNLICENSED — This is a portfolio project.