Skip to main content

​
Overview

The Catalog Service (jea-catalogo) provides comprehensive inventory and product catalog management for Sistema de Ventas. It maintains real-time stock levels, product information, categories, and pricing across the entire system.

​
Key Features

Product Management

Full CRUD operations with unique product codes and names for catalog management

Category Organization

Hierarchical category management for logical product classification

Inventory Tracking

Real-time stock quantity management with automatic updates

Image Support

Product image storage and retrieval for enhanced product presentation

Pricing Management

Separate tracking for sale price and purchase cost

Automatic Timestamps

Creation and update timestamps for comprehensive audit trails

​
Product Entity Structure

The product entity captures all essential information for inventory management: 
@Entity
public class Producto {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, unique = true)
    private String codigo;           // Unique product code
    
    @Column(nullable = false, unique = true)
    private String nombre;           // Product name
    
    private String descripcion;      // Description
    private Integer cantidad;        // Stock quantity
    private Double precioVenta;      // Sale price
    private Double costoCompra;      // Purchase cost
    private boolean estado = true;   // Active/inactive status
    
    private LocalDateTime fechaCreacion;      // Created timestamp
    private LocalDateTime fechaActualizacion; // Last updated timestamp
    
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "categoria_id")
    private Categoria categoria;     // Product category
    
    private String imagen;           // Image file path
}

​
Inventory Management

​
Real-Time Stock Updates

The Catalog Service maintains accurate inventory levels through automatic integration with sales and purchase services:
  • Sales - Automatically decrease stock when sales are completed
  • Purchases - Automatically increase stock when purchase orders are received
  • Manual Adjustments - Direct quantity updates for inventory corrections

​
Stock Quantity Updates

Update inventory levels programmatically: 
PUT /producto/{id}/cantidad
Content-Type: application/json

150
This endpoint allows direct quantity updates for inventory adjustments, returns, or corrections.
Stock quantity updates should be handled carefully to maintain accurate inventory levels. Always verify quantities before making adjustments.

​
Category Management

Organize products into logical categories for better navigation and reporting: 
@Entity
public class Categoria {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    private String nombre;          // Category name
    private String descripcion;     // Category description
    private boolean estado;         // Active/inactive status
}

​
Category Features

  • Create hierarchical product classifications
  • Filter products by category
  • Generate category-based reports
  • Organize catalog for customer browsing

​
Available Endpoints

The Catalog Service provides comprehensive product and category management:
MethodEndpointDescription
GET/productoList all products
GET/producto/{id}Get product by ID
POST/productoCreate new product
PUT/producto/{id}Update product
DELETE/producto/{id}Delete product
PUT/producto/{id}/cantidadUpdate stock quantity
GET/categoriaList all categories
POST/categoriaCreate new category
GET/imagenes/{filename}Get product image (public)
The /imagenes/** endpoint is publicly accessible without authentication to allow product image display on public-facing pages and catalogs.

​
Product Images

Support for product images enhances the shopping experience:

​
Image Storage

  • Images are stored in the file system
  • File paths are stored in the product entity
  • Images are accessible via public endpoint

​
Image Retrieval

GET /imagenes/{filename}
This endpoint serves product images without authentication, allowing them to be displayed in catalogs, shopping carts, and public product listings.

​
Pricing Management

​
Dual Pricing System

The system maintains separate prices for different purposes:
  • Sale Price (precioVenta) - Customer-facing retail price
  • Purchase Cost (costoCompra) - Internal cost for profit margin calculation
This dual pricing enables:
  • Profit margin analysis
  • Pricing strategy evaluation
  • Cost tracking for financial reporting

​
Automatic Timestamps

Track product lifecycle with automatic timestamp management: 
@PrePersist
protected void onCreate() {
    fechaCreacion = LocalDateTime.now();
    fechaActualizacion = fechaCreacion;
}

@PreUpdate
protected void onUpdate() {
    fechaActualizacion = LocalDateTime.now();
}
These JPA lifecycle hooks ensure every product has accurate creation and modification timestamps for audit purposes.

​
Product Status Management

Control product visibility and availability:
  • Active Products - Available for sale and purchase
  • Inactive Products - Hidden from catalogs but retained in system for historical data
The estado field allows soft deletion, preserving product information for past transactions while removing products from active catalogs.

​
Integration with Other Services

The Catalog Service is the central hub for product information:

​
Sales Service Integration

  • Validates product availability
  • Updates stock quantities after sales
  • Provides product pricing information

​
Purchase Service Integration

  • Updates stock quantities on purchase receipt
  • Validates product codes
  • Updates purchase costs

​
Order Service Integration

  • Checks product availability for orders
  • Reserves stock for pending orders
  • Provides product details for order line items

​
Best Practices

Always assign unique product codes that are meaningful for your business. These codes are used throughout the system for product identification and should follow a consistent naming convention.
Plan your category structure before adding products. A well-organized category hierarchy improves navigation and reporting capabilities.
Regularly monitor stock levels to prevent stockouts. Set up alerts for low inventory levels to ensure timely reordering.
Optimize product images for web delivery to ensure fast loading times. Use consistent image dimensions across all products.
When updating prices, consider the impact on pending orders and quotes. Plan price changes carefully to avoid customer confusion.

​
Low Stock Alerts

Monitor inventory levels to prevent stockouts:
  • Track products with low stock quantities
  • Set minimum stock thresholds per product
  • Generate reorder recommendations
  • Integrate with purchase order system

​
Next Steps

API Reference

Detailed catalog API documentation

Purchase Orders

Manage product procurement

Sales Management

Process sales transactions

Analytics & Reporting

Inventory analytics and reports

Build docs developers (and LLMs) love

Get started for freeTalk to us