⛽ EPSDC API

API REST para el Sistema de Distribución de Gas / REST API for the Gas Distribution System

🇪🇸 Español | 🇬🇧 English below

🇪🇸 Versión en Español

📌 Descripción General

EPSDC API es una API REST desarrollada en PHP puro como evolución del sistema web EPSDC Noel Rodríguez. Expone la lógica de negocio del sistema de distribución de gas a través de endpoints HTTP bien definidos, permitiendo desacoplar el backend del frontend y sentar las bases para integraciones con aplicaciones móviles u otros clientes.

La API comparte los modelos de datos del sistema original (gestión de solicitudes, inventario, entregas, usuarios) pero añade una capa de seguridad robusta con autenticación JWT, cifrado RSA de payloads, CSRF, Rate Limiting y soporte completo a CORS.

🏗️ Arquitectura del Proyecto

La API sigue un patrón de enrutamiento centralizado desde un único index.php (Front Controller), que despacha cada petición a una clase *Src según el módulo en la URL. Cada *Src hereda de una clase base abstracta Src que centraliza la autenticación JWT, la verificación de permisos por módulo y el registro de bitácora.

EPSDC-API/
│
├── index.php                    # Front Controller — parsea la URL y despacha al módulo correcto
│
├── 📁 src/                      # Controladores de la API (uno por módulo/recurso)
│   ├── loginSrc.php             # Autenticación: login y creación de cuenta
│   ├── solicitudSrc.php         # Solicitudes de gas (~22KB, endpoint más complejo)
│   ├── entregaSrc.php           # Gestión de entregas a comunidades (~27KB)
│   ├── recepcionSrc.php         # Recepciones de gas en almacén
│   ├── usuarioSrc.php           # Gestión de usuarios del sistema
│   ├── estadisticasSrc.php      # Métricas y estadísticas operativas
│   ├── asistenciaSrc.php        # Control de asistencia de choferes (~12KB)
│   ├── periodoSrc.php           # Gestión de períodos de distribución
│   ├── recuperarSrc.php         # Recuperación de contraseña por email
│   └── ...                      # +9 módulos adicionales (almacén, comunidades, etc.)
│
├── 📁 class/                    # Modelos de datos y lógica de negocio
│   ├── Src.php                  # Clase base abstracta: JWT, permisos y bitácora
│   ├── solicitud.php            # Modelo más robusto (~53KB de lógica SQL/negocio)
│   ├── entrega.php              # Entregas, asignaciones y PDF
│   ├── usuario.php              # Gestión completa de usuarios (~15KB)
│   ├── correo.php               # Servicio de correos con PHPMailer (~12KB)
│   ├── recepcion.php            # Recepciones y stock de almacén
│   ├── conexion/                # Gestión de conexiones PDO (multi-base de datos)
│   └── ...                      # +20 modelos adicionales
│
├── 📁 helpers/                  # Utilidades transversales
│   ├── JWTHelper.php            # Generación y validación de tokens JWT (HS256)
│   ├── csrf.php                 # Protección CSRF para endpoints mutantes
│   ├── RateLimiter.php          # Limitador de tasa de peticiones (Symfony Cache)
│   ├── LoginAttemptLimiter.php  # Protección anti-fuerza bruta en login
│   ├── WsHelper.php             # Helper para enviar notificaciones por WebSocket
│   └── config.php               # Constantes globales (timezone, rutas, claves JWT)
│
└── .htaccess                    # Rewrite rules: enruta todo al Front Controller

🔐 Modelo de Seguridad

La API implementa múltiples capas de seguridad de forma independiente y complementaria:

🔑 Autenticación JWT de doble token

Access Token (corta duración): requerido en el header Authorization: Bearer <token> en cada petición autenticada.
Refresh Token (larga duración): permite renovar el access token sin re-autenticarse.
CSRF Token (via JWT separado): protege los endpoints de mutación (POST, PUT, PATCH, DELETE).

🔒 Cifrado RSA de Payloads (OAEP)

Los payloads de las peticiones mutantes (POST, PUT, PATCH, DELETE) deben enviarse cifrados con la clave pública RSA del servidor. El servidor descifra el cuerpo con openssl_private_decrypt antes de procesarlo. Esto protege los datos sensibles incluso en redes no seguras.

// Cuerpo de una petición cifrada
{
  "encrypted": "<base64 del payload cifrado con RSA-OAEP>"
}

🛡️ Otras medidas

CSRF tokens en todas las operaciones que modifican datos
Rate Limiting por IP usando Symfony Cache
LoginAttemptLimiter: bloqueo temporal tras múltiples intentos fallidos de login
CORS configurable con detección dinámica de origen
Permisos granulares por módulo, verificados en la clase base Src en cada petición

✨ Endpoints Disponibles

Todos los endpoints (excepto login y recuperar) requieren un Access Token JWT válido en el header Authorization.

Módulo	Ruta base	Métodos	Descripción
Login	`/login`	POST	Autenticación y creación de cuenta
Recuperar	`/recuperar`	POST	Recuperación de contraseña por email
Solicitud	`/solicitud`	GET, POST	Gestión de solicitudes de gas
Entrega	`/entrega`	GET, POST, PUT, PATCH	Control de entregas a comunidades
Recepción	`/recepcion`	GET, POST	Recepciones de gas en almacén
Almacén	`/almacen`	GET	Stock e inventario
Usuario	`/usuario`	GET, POST, PUT	Gestión de usuarios
Vocero	`/vocero`	GET, POST, PUT	Voceros comunales
Estadísticas	`/estadisticas`	GET	Métricas y dashboards
Asistencia	`/asistencia`	GET, POST	Control de asistencia de choferes
Período	`/periodo`	GET, POST, PUT	Períodos de distribución
Comunidad	`/comunidad`	GET	Comunidades registradas
Empleado	`/empleado`	GET	Empleados del sistema
Cilindro	`/cilindro`	GET	Tipos de cilindros
Estado	`/estado`	GET	Estados de las solicitudes
Municipio	`/municipio`	GET	Municipios
Parroquia	`/parroquia`	GET	Parroquias
Asignación	`/asignacion`	GET, POST, PUT	Asignaciones de equipos

🛠️ Stack Tecnológico

Capa	Tecnología
Backend	PHP 8.x
Base de Datos	MySQL + PDO (multi-base: `epsdc_principal` + `epsdc_control`)
Autenticación	JWT (`firebase/php-jwt` 6.10) con HS256
Cifrado de Payloads	OpenSSL RSA-OAEP (clave pública/privada)
Correo Electrónico	PHPMailer 6.9
Generación de PDF	FPDF 1.86
Caché / Rate Limiting	Symfony Cache 7.3
WebSocket (cliente)	textalk/websocket 1.6
Variables de Entorno	vlucas/phpdotenv 5.6
Autoloading	Composer PSR-4
Enrutamiento	Front Controller manual + Apache `.htaccess`

🗄️ Multi-Base de Datos

El sistema opera con dos bases de datos MySQL independientes:

Base de Datos	Variable	Propósito
`epsdc_principal`	`DB_MAIN_*`	Datos operativos: solicitudes, entregas, inventario, usuarios
`epsdc_control`	`DB_CONTROL_*`	Datos de control: caché, rate limiting, intentos de login

🚀 Instalación y Configuración

Prerrequisitos

PHP 8.0 o superior con extensiones: openssl, pdo_mysql, json
MySQL 5.7+ o MariaDB
Composer
Servidor web con soporte de mod_rewrite (Apache) o configuración equivalente (Nginx)

Pasos

# 1. Clonar el repositorio
git clone https://github.com/Gusthere/EPSDC-API.git
cd EPSDC-API

# 2. Instalar dependencias PHP
composer install

# 3. Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales

Contenido de `.env`

# Base de datos principal
DB_MAIN_NAME="epsdc_principal"
DB_MAIN_HOST="localhost"
DB_MAIN_USER="root"
DB_MAIN_PASSWORD=""

# Base de datos de control (rate limiting, caché)
DB_CONTROL_NAME="epsdc_control"
DB_CONTROL_HOST="localhost"
DB_CONTROL_USER="root"
DB_CONTROL_PASSWORD=""

# Correo electrónico (PHPMailer)
MAIL_HOST="smtp.gmail.com"
MAIL_USERNAME="tu@gmail.com"
MAIL_PASSWORD="app_password"
MAIL_SMTP_SECURE="STARTTLS"

# Zona horaria
TIMEZONE="America/Caracas"

# Ruta base de la API (ej: "/" si está en la raíz)
BASE_PATH="/"

# Claves JWT (usar strings largos y aleatorios en producción)
JWT_KEY="clave_csrf_secreta"
JWT_ACCESS="clave_access_token_secreta"
JWT_REFRESH="clave_refresh_token_secreta"

# 4. Importar las bases de datos
# Importar los archivos SQL desde /database/ a tu servidor MySQL

# 5. Generar par de claves RSA para cifrado de payloads
mkdir key
openssl genrsa -out key/private.pem 2048
openssl rsa -in key/private.pem -pubout -out key/public.pem

# 6. Acceder a la API
# http://localhost/EPSDC-API/login

📡 Ejemplo de Uso

Login

POST /login
Content-Type: application/json

{
  "encrypted": "<payload RSA-OAEP cifrado con clave pública>"
}

Respuesta exitosa:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Petición autenticada

GET /solicitud
Authorization: Bearer <access_token>

🔗 Proyecto Relacionado

Esta API es una extensión del sistema web original:

EPSDC Noel Rodríguez — Sistema web MVC en PHP para la gestión integral de distribución de gas.

👨‍💻 Autores

Gustavo Heredia

GitHub: @Gusthere

Wilker Alburjas

GitHub: @Wilker2504

Jhon Arrieche

GitHub: @Kaygrem

🇬🇧 English Version

📌 Overview

EPSDC API is a REST API built in pure PHP as an evolution of the EPSDC Noel Rodríguez web system. It exposes the gas distribution business logic through well-defined HTTP endpoints, decoupling the backend from the frontend and laying the groundwork for mobile app integrations and other clients.

The API shares the data models from the original system (request management, inventory, deliveries, users) while adding a robust security layer with JWT authentication, RSA payload encryption, CSRF protection, Rate Limiting, and full CORS support.

🏗️ Project Architecture

The API follows a centralized routing pattern from a single index.php (Front Controller), which dispatches each request to a *Src class based on the URL module. Each *Src inherits from an abstract base class Src that centralizes JWT authentication, per-module permission checks, and audit log registration.

EPSDC-API/
│
├── index.php                    # Front Controller — parses URL and dispatches to the correct module
│
├── 📁 src/                      # API controllers (one per module/resource)
│   ├── loginSrc.php             # Authentication: login and account creation
│   ├── solicitudSrc.php         # Gas supply requests (~22KB, most complex endpoint)
│   ├── entregaSrc.php           # Delivery management (~27KB)
│   ├── recepcionSrc.php         # Gas warehouse receptions
│   ├── usuarioSrc.php           # System user management
│   ├── estadisticasSrc.php      # Operational metrics and statistics
│   ├── asistenciaSrc.php        # Driver attendance tracking (~12KB)
│   └── ...                      # +10 additional modules
│
├── 📁 class/                    # Data models and business logic
│   ├── Src.php                  # Abstract base class: JWT auth, permissions, audit log
│   ├── solicitud.php            # Heaviest model (~53KB of SQL/business logic)
│   ├── entrega.php              # Deliveries, assignments, and PDF generation
│   ├── usuario.php              # Full user management (~15KB)
│   ├── correo.php               # Email service via PHPMailer (~12KB)
│   ├── conexion/                # Multi-database PDO connection management
│   └── ...                      # +20 additional models
│
├── 📁 helpers/                  # Cross-cutting utilities
│   ├── JWTHelper.php            # JWT token generation and validation (HS256)
│   ├── csrf.php                 # CSRF protection for mutating endpoints
│   ├── RateLimiter.php          # Rate limiting per IP (Symfony Cache)
│   ├── LoginAttemptLimiter.php  # Anti-brute-force login protection
│   ├── WsHelper.php             # WebSocket notification broadcast helper
│   └── config.php               # Global constants (timezone, paths, JWT keys)
│
└── .htaccess                    # Rewrite rules: routes everything to the Front Controller

🔐 Security Model

The API implements multiple security layers independently and complementarily:

🔑 Dual-Token JWT Authentication

Access Token (short-lived): required in the Authorization: Bearer <token> header for every authenticated request.
Refresh Token (long-lived): allows renewing the access token without re-authenticating.
CSRF Token (separate JWT): protects mutating endpoints (POST, PUT, PATCH, DELETE).

🔒 RSA Payload Encryption (OAEP)

Payloads for mutating requests (POST, PUT, PATCH, DELETE) must be encrypted with the server's RSA public key. The server decrypts the body using openssl_private_decrypt before processing. This protects sensitive data even on insecure networks.

// Body of an encrypted request
{
  "encrypted": "<base64 of RSA-OAEP encrypted payload>"
}

🛡️ Additional Measures

CSRF tokens on all data-modifying operations
Rate Limiting per IP using Symfony Cache
LoginAttemptLimiter: temporary lockout after multiple failed login attempts
CORS with dynamic origin detection
Granular per-module permissions verified in the base Src class on every request

✨ Available Endpoints

All endpoints (except login and recuperar) require a valid JWT Access Token in the Authorization header.

Module	Base Route	Methods	Description
Login	`/login`	POST	Authentication and account creation
Recover	`/recuperar`	POST	Password recovery via email
Request	`/solicitud`	GET, POST	Gas supply request management
Delivery	`/entrega`	GET, POST, PUT, PATCH	Delivery management
Reception	`/recepcion`	GET, POST	Gas warehouse receptions
Warehouse	`/almacen`	GET	Stock and inventory
User	`/usuario`	GET, POST, PUT	User management
Representative	`/vocero`	GET, POST, PUT	Community representatives
Statistics	`/estadisticas`	GET	Metrics and dashboards
Attendance	`/asistencia`	GET, POST	Driver attendance tracking
Period	`/periodo`	GET, POST, PUT	Distribution periods
Community	`/comunidad`	GET	Registered communities
Employee	`/empleado`	GET	System employees
Cylinder	`/cilindro`	GET	Cylinder types
Status	`/estado`	GET	Request statuses
Municipality	`/municipio`	GET	Municipalities
Parish	`/parroquia`	GET	Parishes
Assignment	`/asignacion`	GET, POST, PUT	Teams assignments

🛠️ Tech Stack

Layer	Technology
Backend	PHP 8.x
Database	MySQL + PDO (multi-DB: `epsdc_principal` + `epsdc_control`)
Authentication	JWT (`firebase/php-jwt` 6.10) with HS256
Payload Encryption	OpenSSL RSA-OAEP (public/private key pair)
Email Service	PHPMailer 6.9
PDF Generation	FPDF 1.86
Cache / Rate Limiting	Symfony Cache 7.3
WebSocket (client)	textalk/websocket 1.6
Environment Variables	vlucas/phpdotenv 5.6
Autoloading	Composer PSR-4
Routing	Manual Front Controller + Apache `.htaccess`

🗄️ Multi-Database

The system operates with two independent MySQL databases:

Database	Variable	Purpose
`epsdc_principal`	`DB_MAIN_*`	Operational data: requests, deliveries, inventory, users
`epsdc_control`	`DB_CONTROL_*`	Control data: cache, rate limiting, login attempts

🚀 Setup & Installation

Prerequisites

PHP 8.0 or higher with extensions: openssl, pdo_mysql, json
MySQL 5.7+ or MariaDB
Composer
Web server with mod_rewrite support (Apache) or equivalent (Nginx)

Steps

# 1. Clone the repository
git clone https://github.com/Gusthere/EPSDC-API.git
cd EPSDC-API

# 2. Install PHP dependencies
composer install

# 3. Configure environment variables
cp .env.example .env
# Edit .env with your credentials

# 4. Import the databases
# Import the SQL files from /database/ into your MySQL server

# 5. Generate RSA key pair for payload encryption
mkdir key
openssl genrsa -out key/private.pem 2048
openssl rsa -in key/private.pem -pubout -out key/public.pem

# 6. Access the API
# http://localhost/EPSDC-API/login

📡 Usage Example

Login

POST /login
Content-Type: application/json

{
  "encrypted": "<RSA-OAEP encrypted payload with public key>"
}

Successful response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
}

Authenticated request

GET /solicitud
Authorization: Bearer <access_token>

🔗 Related Project

This API is an extension of the original web system:

EPSDC Noel Rodríguez — MVC web system in PHP for comprehensive gas distribution management.

👨‍💻 Authors

Gustavo Heredia

GitHub: @Gusthere

Wilker Alburjas

GitHub: @Wilker2504

Jhon Arrieche

GitHub: @Kaygrem

Proyecto de Ingeniería de Software para la obtención del título de Ingeniero en Sistemas en Venezuela 🇻🇪

Software Engineering project for the obtention of the title of Systems Engineer in Venezuela 🇻🇪

Name		Name	Last commit message	Last commit date
Latest commit History 96 Commits
.expo		.expo
.vscode		.vscode
class		class
helpers		helpers
public/img		public/img
src		src
.env.example		.env.example
.gitignore		.gitignore
.htaccess		.htaccess
README.md		README.md
composer.json		composer.json
composer.lock		composer.lock
index.php		index.php
package-lock.json		package-lock.json

Folders and files

Latest commit

History

Repository files navigation

⛽ EPSDC API

API REST para el Sistema de Distribución de Gas / REST API for the Gas Distribution System

🇪🇸 Versión en Español

📌 Descripción General

🏗️ Arquitectura del Proyecto

🔐 Modelo de Seguridad

🔑 Autenticación JWT de doble token

🔒 Cifrado RSA de Payloads (OAEP)

🛡️ Otras medidas

✨ Endpoints Disponibles

🛠️ Stack Tecnológico

🗄️ Multi-Base de Datos

🚀 Instalación y Configuración

Prerrequisitos

Pasos

Contenido de .env

📡 Ejemplo de Uso

Login

Petición autenticada

🔗 Proyecto Relacionado

👨‍💻 Autores

🇬🇧 English Version

📌 Overview

🏗️ Project Architecture

🔐 Security Model

🔑 Dual-Token JWT Authentication

🔒 RSA Payload Encryption (OAEP)

🛡️ Additional Measures

✨ Available Endpoints

🛠️ Tech Stack

🗄️ Multi-Database

🚀 Setup & Installation

Prerequisites

Steps

📡 Usage Example

Login

Authenticated request

🔗 Related Project

👨‍💻 Authors

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Contenido de `.env`