Products Management

Author: NextGate Development Team, Backend Developer Last Updated: 2025-01-23 Version: v1.0

Short Description: The Product Management API provides comprehensive functionality for creating, managing, and browsing products within shops. It supports advanced features like group buying, installment payments, color variations, specifications, and complex filtering capabilities for both shop owners and public users.

Hints:

• All product operations require valid authentication except for public browsing endpoints

• Products support advanced features like group buying and installment payments with detailed calculations

• Color variations can have individual pricing adjustments and image galleries

• Search and filter operations support different access levels based on user permissions

• Draft products can be hard deleted while published products are soft deleted for data integrity

• Product slugs are unique within each shop but can be repeated across different shops

---

Endpoints

1. Create Product

Purpose: Creates a new product in a shop with support for advanced features like group buying, installments, and color variations

Endpoint: POST /api/v1/shops/{shopId}/products

Access Level: 🔒 Protected (Requires shop owner or admin permissions)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be "application/json"

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Unique identifier of the shop	Must be valid UUID format

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
action	enum	Yes	Product creation action	SAVE_DRAFT or SAVE_PUBLISH	None

Request JSON Sample:

{
  "productName": "Dell Precision 5570 Laptop",
  "productDescription": "High-performance mobile workstation with Intel Core i7 processor, 32GB RAM, and NVIDIA RTX graphics card. Perfect for professional design work and development.",
  "shortDescription": "Professional mobile workstation with powerful specs",
  "price": 2599.99,
  "comparePrice": 2999.99,
  "stockQuantity": 15,
  "lowStockThreshold": 3,
  "categoryId": "550e8400-e29b-41d4-a716-446655440000",
  "productImages": [
    "https://example.com/images/dell-precision-front.jpg",
    "https://example.com/images/dell-precision-side.jpg"
  ],
  "brand": "Dell",
  "condition": "NEW",
  "tags": ["laptop", "workstation", "professional", "dell"],
  "specifications": {
    "Processor": "Intel Core i7-12800H",
    "RAM": "32GB DDR5",
    "Storage": "1TB SSD",
    "Graphics": "NVIDIA RTX A2000",
    "Screen Size": "15.6 inches",
    "Operating System": "Windows 11 Pro"
  },
  "colors": [
    {
      "name": "Space Gray",
      "hex": "#8C8C8C",
      "images": ["https://example.com/images/dell-gray-1.jpg"],
      "priceAdjustment": 0.00
    },
    {
      "name": "Platinum Silver",
      "hex": "#C0C0C0",
      "images": ["https://example.com/images/dell-silver-1.jpg"],
      "priceAdjustment": 50.00
    }
  ],
  "groupBuyingEnabled": true,
  "groupMinSize": 5,
  "groupMaxSize": 20,
  "groupPrice": 2399.99,
  "groupTimeLimitHours": 72,
  "installmentEnabled": true,
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free payment"
    },
    {
      "duration": 12,
      "interval": "MONTHS",
      "interestRate": 3.99,
      "description": "12 months low interest payment"
    }
  ],
  "minDownPaymentPercentage": 20.00,
  "trackInventory": true,
  "isFeatured": false,
  "metaTitle": "Dell Precision 5570 - Professional Laptop",
  "metaDescription": "Buy Dell Precision 5570 mobile workstation with Intel i7, 32GB RAM, RTX graphics. Perfect for professionals."
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productName	string	Yes	Product display name	Min: 2, Max: 100 characters
productDescription	string	Yes	Detailed product description	Min: 10, Max: 1000 characters
shortDescription	string	No	Brief product summary	Max: 200 characters
price	decimal	Yes	Product base price	Min: 0.01, Max precision: 8 digits, 2 decimals
comparePrice	decimal	No	Original price for discount display	Must be greater than price
stockQuantity	integer	Yes	Available inventory count	Min: 0
lowStockThreshold	integer	No	Alert threshold for low stock	Min: 1, Max: 1000, Default: 5
categoryId	UUID	Yes	Product category identifier	Must reference existing active category
productImages	array	Yes	Product image URLs	Each URL must be valid, array cannot be empty
brand	string	No	Product brand name	Max: 100 characters
condition	enum	No	Product condition	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS
tags	array	No	Product search tags	Each tag max: 50 characters
specifications	object	No	Technical specifications	Key max: 100 chars, Value max: 500 chars
colors	array	No	Available color variations	See ColorRequest schema
groupBuyingEnabled	boolean	No	Enable group purchasing	Default: false
groupMinSize	integer	No	Minimum group size	Required if group buying enabled, Min: 2
groupMaxSize	integer	No	Maximum group size	Required if group buying enabled, Min: 2
groupPrice	decimal	No	Group purchase price	Required if group buying enabled, Must be less than regular price
groupTimeLimitHours	integer	No	Group formation time limit	Required if group buying enabled, Min: 1, Max: 8760
installmentEnabled	boolean	No	Enable installment payments	Default: false
installmentPlans	array	No	Available installment options	Required if installments enabled
minDownPaymentPercentage	decimal	No	Minimum down payment percentage	Min: 0.0, Max: 100.0, Default: 0.0

Response JSON Sample:

{
  "status": "success",
  "message": "Product created successfully",
  "data": null,
  "timestamp": "2025-01-23T14:30:00Z"
}

Error Responses:

• 400 Bad Request: Invalid request data or validation errors

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Shop not found

• 409 Conflict: Product with same attributes already exists

---

2. Get Product Details

Purpose: Retrieves comprehensive product information including all advanced features and calculations

Endpoint: GET /api/v1/shops/{shopId}/products/{productId}/detailed

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Product details retrieved successfully",
  "data": {
    "productId": "550e8400-e29b-41d4-a716-446655440001",
    "productName": "Dell Precision 5570 Laptop",
    "productSlug": "dell-precision-5570-laptop",
    "productDescription": "High-performance mobile workstation...",
    "shortDescription": "Professional mobile workstation",
    "productImages": ["https://example.com/images/dell-precision-front.jpg"],
    "price": 2599.99,
    "comparePrice": 2999.99,
    "discountAmount": 400.00,
    "discountPercentage": 13.33,
    "isOnSale": true,
    "stockQuantity": 15,
    "isInStock": true,
    "isLowStock": false,
    "brand": "Dell",
    "sku": "SHP12345678-LAP-DEL-I7-0001",
    "condition": "NEW",
    "status": "ACTIVE",
    "shopId": "550e8400-e29b-41d4-a716-446655440000",
    "shopName": "Tech Solutions Store",
    "categoryId": "550e8400-e29b-41d4-a716-446655440002",
    "categoryName": "Laptops",
    "specifications": {
      "Processor": "Intel Core i7-12800H",
      "RAM": "32GB DDR5",
      "Storage": "1TB SSD"
    },
    "hasSpecifications": true,
    "colors": [
      {
        "name": "Space Gray",
        "hex": "#8C8C8C",
        "priceAdjustment": 0.00,
        "finalPrice": 2599.99,
        "hasExtraFee": false
      },
      {
        "name": "Platinum Silver",
        "hex": "#C0C0C0",
        "priceAdjustment": 50.00,
        "finalPrice": 2649.99,
        "hasExtraFee": true
      }
    ],
    "hasMultipleColors": true,
    "priceRange": {
      "minPrice": 2599.99,
      "maxPrice": 2649.99,
      "hasPriceVariations": true
    },
    "groupBuying": {
      "isEnabled": true,
      "isAvailable": true,
      "minGroupSize": 5,
      "maxGroupSize": 20,
      "currentGroupSize": 7,
      "groupPrice": 2399.99,
      "groupDiscount": 200.00,
      "groupDiscountPercentage": 7.69,
      "timeLimitHours": 72,
      "status": "ACTIVE",
      "canJoinGroup": true
    },
    "installmentOptions": {
      "isEnabled": true,
      "isAvailable": true,
      "downPaymentRequired": false,
      "plans": [
        {
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "calculations": {
            "downPayment": 519.99,
            "paymentAmount": 346.67,
            "totalAmount": 2599.99
          }
        }
      ]
    },
    "createdAt": "2025-01-23T10:00:00Z",
    "updatedAt": "2025-01-23T12:00:00Z"
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response Fields:

Field	Description
productId	Unique product identifier
productName	Product display name
productSlug	URL-friendly product identifier
price	Current product price
discountAmount	Amount saved if on sale
stockQuantity	Available inventory count
specifications	Technical product details
colors	Available color variations with pricing
groupBuying	Group purchase information and status
installmentOptions	Available payment plans with calculations
priceRange	Minimum and maximum prices across variations

Error Responses:

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Product or shop not found

---

3. Get Shop Products (Owner View)

Purpose: Retrieves all products for shop management with summary statistics

Endpoint: GET /api/v1/shops/{shopId}/products/all

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Retrieved 25 products from shop: Tech Solutions Store",
  "data": {
    "contents": {
      "shop": {
        "shopId": "550e8400-e29b-41d4-a716-446655440000",
        "shopName": "Tech Solutions Store",
        "shopSlug": "tech-solutions-store",
        "isVerified": true,
        "isApproved": true
      },
      "summary": {
        "totalProducts": 25,
        "activeProducts": 18,
        "draftProducts": 4,
        "outOfStockProducts": 2,
        "featuredProducts": 5,
        "lowStockProducts": 3,
        "averagePrice": 1250.50,
        "totalInventoryValue": 65000.00,
        "productsWithGroupBuying": 8,
        "productsWithInstallments": 12,
        "productsWithMultipleColors": 6
      },
      "products": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440001",
          "productName": "Dell Precision 5570 Laptop",
          "productSlug": "dell-precision-5570-laptop",
          "primaryImage": "https://example.com/images/dell-precision-front.jpg",
          "price": 2599.99,
          "comparePrice": 2999.99,
          "isOnSale": true,
          "stockQuantity": 15,
          "isInStock": true,
          "brand": "Dell",
          "status": "ACTIVE",
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 2399.99,
          "createdAt": "2025-01-23T10:00:00Z"
        }
      ],
      "totalProducts": 25
    }
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response Fields:

Field	Description
shop	Basic shop information
summary	Product statistics and metrics
products	Array of product summaries
totalProducts	Count of products returned

Error Responses:

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Shop not found

---

4. Get Shop Products (Paginated)

Purpose: Retrieves shop products with pagination for management interface

Endpoint: GET /api/v1/shops/{shopId}/products/all-paged

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 100	10

Response JSON Sample:

{
  "status": "success",
  "message": "Retrieved 10 products from shop: Tech Solutions Store (Page 1 of 3)",
  "data": {
    "contents": {
      "shop": {
        "shopId": "550e8400-e29b-41d4-a716-446655440000",
        "shopName": "Tech Solutions Store"
      },
      "products": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440001",
          "productName": "Dell Precision 5570 Laptop",
          "price": 2599.99,
          "stockQuantity": 15,
          "status": "ACTIVE"
        }
      ]
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response Fields:

Field	Description
contents	Paginated product data
currentPage	Current page number
totalElements	Total number of products
totalPages	Total number of pages
hasNext	Whether there are more pages
hasPrevious	Whether there are previous pages

Error Responses:

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Shop not found

---

5. Update Product

Purpose: Updates existing product with support for all advanced features

Endpoint: PUT /api/v1/shops/{shopId}/products/{productId}

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	Must be "application/json"

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
action	enum	No	Update action	SAVE_DRAFT or SAVE_PUBLISH	Keep current status

Request JSON Sample:

{
  "productName": "Dell Precision 5570 Laptop - Updated",
  "price": 2499.99,
  "stockQuantity": 12,
  "shortDescription": "Updated professional mobile workstation",
  "specifications": {
    "Processor": "Intel Core i7-12800H",
    "RAM": "32GB DDR5",
    "Storage": "2TB SSD",
    "Graphics": "NVIDIA RTX A2000",
    "Warranty": "3 years"
  },
  "groupPrice": 2299.99,
  "installmentPlans": [
    {
      "duration": 6,
      "interval": "MONTHS",
      "interestRate": 0.00,
      "description": "6 months interest-free payment"
    },
    {
      "duration": 12,
      "interval": "MONTHS",
      "interestRate": 2.99,
      "description": "12 months low interest payment - Updated rate"
    }
  ]
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
productName	string	No	Updated product name	Min: 2, Max: 100 characters
price	decimal	No	Updated price	Min: 0.01
stockQuantity	integer	No	Updated stock count	Min: 0
specifications	object	No	Updated specifications	Key max: 100 chars, Value max: 500 chars
groupPrice	decimal	No	Updated group price	Must be less than regular price if group buying enabled
installmentPlans	array	No	Updated installment options	Valid plan objects

Response JSON Sample:

{
  "status": "success",
  "message": "Product updated successfully and published",
  "data": {
    "productId": "550e8400-e29b-41d4-a716-446655440001",
    "productName": "Dell Precision 5570 Laptop - Updated",
    "price": 2499.99,
    "stockQuantity": 12,
    "status": "ACTIVE",
    "updatedAt": "2025-01-23T15:30:00Z"
  },
  "timestamp": "2025-01-23T15:30:00Z"
}

Error Responses:

• 400 Bad Request: Invalid request data

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Product or shop not found

• 409 Conflict: Product name already exists

---

6. Publish Product

Purpose: Changes product status from draft to active, making it publicly visible

Endpoint: PATCH /api/v1/shops/{shopId}/products/{productId}/publish

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Product 'Dell Precision 5570 Laptop' published successfully",
  "data": {
    "productId": "550e8400-e29b-41d4-a716-446655440001",
    "productName": "Dell Precision 5570 Laptop",
    "status": "ACTIVE",
    "publishedAt": "2025-01-23T16:00:00Z"
  },
  "timestamp": "2025-01-23T16:00:00Z"
}

Error Responses:

• 400 Bad Request: Product already published or missing required fields

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Product or shop not found

---

7. Delete Product

Purpose: Deletes product (hard delete for drafts, soft delete for published products)

Endpoint: DELETE /api/v1/shops/{shopId}/products/{productId}

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Product 'Dell Precision 5570 Laptop' has been deleted and will be permanently removed after 30 days",
  "data": {
    "message": "Product 'Dell Precision 5570 Laptop' has been deleted and will be permanently removed after 30 days",
    "productName": "Dell Precision 5570 Laptop",
    "previousStatus": "ACTIVE",
    "deletedAt": "2025-01-23T16:30:00Z",
    "deletionType": "SOFT_DELETE",
    "note": "Product will be permanently deleted after 30 days"
  },
  "timestamp": "2025-01-23T16:30:00Z"
}

Response Fields:

Field	Description
productName	Name of deleted product
previousStatus	Status before deletion
deletedAt	Deletion timestamp
deletionType	HARD_DELETE for drafts, SOFT_DELETE for published
note	Additional deletion information

Error Responses:

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Product or shop not found

---

8. Restore Product

Purpose: Restores a soft-deleted product back to draft status

Endpoint: PATCH /api/v1/shops/{shopId}/products/{productId}/restore

Access Level: 🔒 Protected (Shop owner or admin only)

Authentication: Bearer Token required

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Product 'Dell Precision 5570 Laptop' has been restored successfully",
  "data": {
    "productId": "550e8400-e29b-41d4-a716-446655440001",
    "productName": "Dell Precision 5570 Laptop",
    "status": "DRAFT",
    "restoredAt": "2025-01-23T17:00:00Z"
  },
  "timestamp": "2025-01-23T17:00:00Z"
}

Error Responses:

• 400 Bad Request: Product is not deleted

• 401 Unauthorized: Authentication required

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Product or shop not found

---

9. Get Product by ID (Public)

Purpose: Retrieves single product details for public viewing

Endpoint: GET /api/v1/shops/{shopId}/products/{productId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID
productId	UUID	Yes	Product identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Product retrieved successfully",
  "data": {
    "productId": "550e8400-e29b-41d4-a716-446655440001",
    "productName": "Dell Precision 5570 Laptop",
    "productSlug": "dell-precision-5570-laptop",
    "price": 2599.99,
    "comparePrice": 2999.99,
    "isOnSale": true,
    "isInStock": true,
    "brand": "Dell",
    "condition": "NEW",
    "shopId": "550e8400-e29b-41d4-a716-446655440000",
    "shopName": "Tech Solutions Store",
    "specifications": {
      "Processor": "Intel Core i7-12800H",
      "RAM": "32GB DDR5"
    },
    "colors": [
      {
        "name": "Space Gray",
        "hex": "#8C8C8C",
        "finalPrice": 2599.99
      }
    ],
    "groupBuying": {
      "isAvailable": true,
      "groupPrice": 2399.99,
      "groupDiscount": 200.00,
      "minGroupSize": 5
    },
    "installmentOptions": {
      "isAvailable": true,
      "plans": [
        {
          "duration": 6,
          "interval": "MONTHS",
          "interestRate": 0.00,
          "description": "6 months interest-free"
        }
      ]
    }
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Error Responses:

• 404 Not Found: Product not found or not available

---

10. Get Public Products by Shop

Purpose: Lists all active products from a shop for public browsing

Endpoint: GET /api/v1/shops/{shopId}/products/public-view/all

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Response JSON Sample:

{
  "status": "success",
  "message": "Retrieved 15 products from Tech Solutions Store",
  "data": {
    "shop": {
      "shopId": "550e8400-e29b-41d4-a716-446655440000",
      "shopName": "Tech Solutions Store",
      "shopSlug": "tech-solutions-store",
      "isVerified": true
    },
    "products": [
      {
        "productId": "550e8400-e29b-41d4-a716-446655440001",
        "productName": "Dell Precision 5570 Laptop",
        "primaryImage": "https://example.com/images/dell-precision-front.jpg",
        "price": 2599.99,
        "isOnSale": true,
        "isInStock": true,
        "hasGroupBuying": true,
        "hasInstallments": true
      }
    ],
    "totalProducts": 15
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Error Responses:

• 404 Not Found: Shop not found or not available

---

11. Get Public Products by Shop (Paginated)

Purpose: Lists active products from a shop with pagination for public browsing

Endpoint: GET /api/v1/shops/{shopId}/products/public-view/all-paged

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Items per page	Min: 1, Max: 50	10

Response JSON Sample:

{
  "status": "success",
  "message": "Retrieved 10 products from Tech Solutions Store (Page 1 of 2)",
  "data": {
    "contents": {
      "shop": {
        "shopId": "550e8400-e29b-41d4-a716-446655440000",
        "shopName": "Tech Solutions Store",
        "isVerified": true
      },
      "products": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440001",
          "productName": "Dell Precision 5570 Laptop",
          "price": 2599.99,
          "isInStock": true,
          "hasGroupBuying": true
        }
      ],
      "totalProducts": 10
    },
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 15,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Error Responses:

• 404 Not Found: Shop not found or not available

---

12. Search Products

Purpose: Performs intelligent text search across products within a shop, searching product names, descriptions, brands, tags, and specifications with relevance ranking

Endpoint: GET /api/v1/shops/{shopId}/products/search

Access Level: 🌐 Public (Authentication optional for enhanced results)

Authentication: Bearer Token optional

Request Headers:

Header	Type	Required	Description
Authorization	string	No	Bearer token for enhanced search (shop owners can search draft products)

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
q	string	Yes	Search query (searches across name, description, brand, tags, specifications)	Min: 2, Max: 100 characters, Special characters filtered	None
status	array	No	Product statuses to search (authenticated users only)	ACTIVE, DRAFT, INACTIVE, OUT_OF_STOCK, ARCHIVED	[ACTIVE]
page	integer	No	Page number (1-based)	Min: 1, Max: 1000	1
size	integer	No	Items per page	Min: 1, Max: 50	10
sortBy	string	No	Sort field	relevance, createdAt, updatedAt, price, productName, brand, stockQuantity	relevance
sortDir	string	No	Sort direction	asc, desc	desc

Search Features:

• Multi-field Search: Searches across product name, description, short description, brand, tags, and specification values

• Intelligent Matching: Supports partial word matching and multi-word queries

• Relevance Ranking: Results sorted by relevance when sortBy="relevance"

• Case Insensitive: All searches are case-insensitive

• Permission-based: Public users see only ACTIVE products, owners/admins can search all statuses

Search Examples:

• q=dell laptop - Finds products containing both "dell" and "laptop"

• q=precision - Finds products with "precision" in any searchable field

• q=i7 32gb - Finds products with both "i7" and "32gb" in specifications or description

• q=workstation - Searches across all fields for "workstation"

Request JSON Sample:

GET /api/v1/shops/550e8400-e29b-41d4-a716-446655440000/products/search?q=dell%20precision&page=1&size=20&sortBy=relevance&sortDir=desc

Response JSON Sample:

{
  "status": "success",
  "message": "Found 8 products matching 'dell precision'",
  "data": {
    "contents": {
      "shop": {
        "shopId": "550e8400-e29b-41d4-a716-446655440000",
        "shopName": "Tech Solutions Store",
        "shopSlug": "tech-solutions-store",
        "isVerified": true,
        "isApproved": true
      },
      "products": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440001",
          "productName": "Dell Precision 5570 Laptop",
          "productSlug": "dell-precision-5570-laptop",
          "shortDescription": "Professional mobile workstation with powerful specs",
          "primaryImage": "https://example.com/images/dell-precision-front.jpg",
          "price": 2599.99,
          "comparePrice": 2999.99,
          "finalPrice": 2599.99,
          "isOnSale": true,
          "discountPercentage": 13.33,
          "stockQuantity": 15,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Dell",
          "sku": "SHP12345678-LAP-DEL-I7-0001",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 2399.99,
          "startingFromPrice": 2599.99,
          "createdAt": "2025-01-23T10:00:00Z"
        },
        {
          "productId": "550e8400-e29b-41d4-a716-446655440002",
          "productName": "Dell Precision 7770 Mobile Workstation",
          "productSlug": "dell-precision-7770-mobile-workstation",
          "shortDescription": "Ultimate performance for demanding professionals",
          "primaryImage": "https://example.com/images/dell-precision-7770.jpg",
          "price": 3499.99,
          "comparePrice": 3899.99,
          "finalPrice": 3499.99,
          "isOnSale": true,
          "discountPercentage": 10.26,
          "stockQuantity": 8,
          "isInStock": true,
          "isLowStock": true,
          "brand": "Dell",
          "condition": "NEW",
          "status": "ACTIVE",
          "hasGroupBuying": false,
          "hasInstallments": true,
          "hasMultipleColors": false,
          "createdAt": "2025-01-22T15:30:00Z"
        }
      ],
      "totalProducts": 8,
      "searchMetadata": {
        "searchQuery": "dell precision",
        "searchedStatuses": null,
        "userType": "PUBLIC",
        "canSearchAllStatuses": false
      }
    },
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 8,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response Fields:

Field	Description
products	Array of matching products with relevance-based ordering
searchMetadata.searchQuery	The processed search query that was executed
searchMetadata.userType	User permission level (PUBLIC, SHOP_OWNER, ADMIN, AUTHENTICATED)
searchMetadata.canSearchAllStatuses	Whether user can search non-active products
searchMetadata.searchedStatuses	Product statuses included in search (null for public users)
totalElements	Total number of products matching the search query
currentPage	Current page number (1-based)
hasNext	Whether more pages are available

Error Responses:

• 400 Bad Request: Search query too short, too long, or contains only special characters

• 404 Not Found: Shop not found or not accessible

• 422 Unprocessable Entity: Invalid sort parameters or pagination values

---

13. Advanced Filter Products

Purpose: Filters products using comprehensive criteria including price ranges, brands, features, availability, and business model options with powerful combination logic

Endpoint: GET /api/v1/shops/{shopId}/products/advanced-filter

Access Level: 🌐 Public (Authentication optional for enhanced filtering)

Authentication: Bearer Token optional

Request Headers:

Header	Type	Required	Description
Authorization	string	No	Bearer token for enhanced filtering (access to draft products and internal metrics)

Path Parameters:

Parameter	Type	Required	Description	Validation
shopId	UUID	Yes	Shop identifier	Must be valid UUID

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
minPrice	decimal	No	Minimum price filter (inclusive)	Min: 0.01, Max precision: 8 digits, 2 decimals	None
maxPrice	decimal	No	Maximum price filter (inclusive)	Min: 0.01, Max precision: 8 digits, 2 decimals	None
brand	array	No	Brand names to filter (case insensitive, multiple values supported)	Each brand max 100 chars, comma-separated	None
condition	enum	No	Product condition filter	NEW, USED_LIKE_NEW, USED_GOOD, USED_FAIR, REFURBISHED, FOR_PARTS	None
categoryId	UUID	No	Category filter	Must be valid UUID of existing category	None
tags	array	No	Product tags to match (case insensitive, OR logic)	Each tag max 50 chars, comma-separated	None
inStock	boolean	No	Filter by stock availability	true (only in-stock), false (only out-of-stock)	None
onSale	boolean	No	Filter by sale status (has comparePrice > price)	true (only on sale), false (not on sale)	None
hasGroupBuying	boolean	No	Filter products with group buying enabled	true/false	None
hasInstallments	boolean	No	Filter products with installment payments	true/false	None
hasMultipleColors	boolean	No	Filter products with color variations	true/false	None
isFeatured	boolean	No	Filter featured products	true/false	None
status	array	No	Product statuses (authenticated shop owners/admins only)	ACTIVE, DRAFT, INACTIVE, OUT_OF_STOCK, ARCHIVED	[ACTIVE]
page	integer	No	Page number (1-based)	Min: 1, Max: 1000	1
size	integer	No	Items per page	Min: 1, Max: 50	10
sortBy	string	No	Sort field	createdAt, updatedAt, price, productName, brand, stockQuantity	createdAt
sortDir	string	No	Sort direction	asc, desc	desc

Filter Logic:

• Price Range: Products with price between minPrice and maxPrice (inclusive)

• Brand Filter: Case-insensitive exact match, supports multiple brands (OR logic)

• Tag Filter: Case-insensitive partial match, supports multiple tags (OR logic)

• Boolean Filters: Exact boolean matching for feature flags

• Category Filter: Exact UUID match for product category

• Stock Filter: Based on stockQuantity > 0 for inStock=true

• Sale Filter: Based on comparePrice > price for onSale=true

• Combination Logic: All filters use AND logic between different filter types, OR logic within same filter type arrays

Complex Filter Examples:

# Laptops under $3000 with group buying, in stock, from Dell or HP
GET /api/v1/shops/{shopId}/products/advanced-filter?maxPrice=3000&hasGroupBuying=true&inStock=true&brand=Dell,HP&tags=laptop

# Featured products on sale with installments, sorted by price ascending
GET /api/v1/shops/{shopId}/products/advanced-filter?isFeatured=true&onSale=true&hasInstallments=true&sortBy=price&sortDir=asc

# Multi-color products in specific category with price range
GET /api/v1/shops/{shopId}/products/advanced-filter?categoryId=550e8400-e29b-41d4-a716-446655440002&hasMultipleColors=true&minPrice=500&maxPrice=2000

Request JSON Sample:

GET /api/v1/shops/550e8400-e29b-41d4-a716-446655440000/products/advanced-filter?minPrice=1000&maxPrice=5000&brand=Dell,HP&hasGroupBuying=true&inStock=true&onSale=true&sortBy=price&sortDir=asc&page=1&size=20

Response JSON Sample:

{
  "status": "success",
  "message": "Found 12 products matching your filters",
  "data": {
    "contents": {
      "shop": {
        "shopId": "550e8400-e29b-41d4-a716-446655440000",
        "shopName": "Tech Solutions Store",
        "shopSlug": "tech-solutions-store",
        "logoUrl": "https://example.com/logos/tech-solutions.jpg",
        "isVerified": true,
        "isApproved": true
      },
      "products": [
        {
          "productId": "550e8400-e29b-41d4-a716-446655440001",
          "productName": "Dell Precision 5570 Laptop",
          "productSlug": "dell-precision-5570-laptop",
          "shortDescription": "Professional mobile workstation with powerful specs",
          "primaryImage": "https://example.com/images/dell-precision-front.jpg",
          "price": 2599.99,
          "comparePrice": 2999.99,
          "finalPrice": 2599.99,
          "isOnSale": true,
          "discountPercentage": 13.33,
          "stockQuantity": 15,
          "isInStock": true,
          "isLowStock": false,
          "brand": "Dell",
          "sku": "SHP12345678-LAP-DEL-I7-0001",
          "condition": "NEW",
          "status": "ACTIVE",
          "isFeatured": false,
          "isDigital": false,
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": true,
          "groupPrice": 2399.99,
          "startingFromPrice": 2599.99,
          "createdAt": "2025-01-23T10:00:00Z"
        },
        {
          "productId": "550e8400-e29b-41d4-a716-446655440003",
          "productName": "HP ZBook Studio G9",
          "productSlug": "hp-zbook-studio-g9",
          "shortDescription": "Creative professional mobile workstation",
          "primaryImage": "https://example.com/images/hp-zbook-studio.jpg",
          "price": 3299.99,
          "comparePrice": 3799.99,
          "finalPrice": 3299.99,
          "isOnSale": true,
          "discountPercentage": 13.16,
          "stockQuantity": 7,
          "isInStock": true,
          "isLowStock": true,
          "brand": "HP",
          "condition": "NEW",
          "status": "ACTIVE",
          "hasGroupBuying": true,
          "hasInstallments": true,
          "hasMultipleColors": false,
          "groupPrice": 3099.99,
          "createdAt": "2025-01-22T14:15:00Z"
        }
      ],
      "totalProducts": 12,
      "filterMetadata": {
        "appliedFilters": {
          "minPrice": 1000.00,
          "maxPrice": 5000.00,
          "brands": ["Dell", "HP"],
          "hasGroupBuying": true,
          "inStock": true,
          "onSale": true
        },
        "userType": "PUBLIC",
        "searchedStatuses": null,
        "hasActiveFilters": true
      }
    },
    "currentPage": 1,
    "pageSize": 20,
    "totalElements": 12,
    "totalPages": 1,
    "hasNext": false,
    "hasPrevious": false
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Response Fields:

Field	Description
products	Array of products matching all filter criteria
filterMetadata.appliedFilters	Summary of all active filter criteria
filterMetadata.userType	User permission level affecting available filters
filterMetadata.hasActiveFilters	Whether any filters are currently applied
filterMetadata.searchedStatuses	Product statuses included in filter (null for public)
totalElements	Total count of products matching all filters
shop	Shop information with verification status

Filter Performance Tips:

• Price Range: Most efficient filter, use when possible

• Category: Very efficient with database indexing

• Brand: Efficient with proper indexing

• Boolean Features: Fast filtering on feature flags

• Multiple Filters: Combining filters improves performance by reducing result set

• Pagination: Use appropriate page sizes (10-20) for best performance

Error Responses:

• 400 Bad Request: Invalid filter parameters (e.g., minPrice > maxPrice, invalid enums)

• 404 Not Found: Shop not found, not accessible, or category not found

• 422 Unprocessable Entity: Invalid UUID formats, out of range values, or conflicting parameters

---

Quick Reference Guide

Common HTTP Status Codes

• 200 OK: Successful GET/PUT/PATCH request

• 201 Created: Successful POST request

• 204 No Content: Successful DELETE request

• 400 Bad Request: Invalid request data

• 401 Unauthorized: Authentication required/failed

• 403 Forbidden: Insufficient permissions

• 404 Not Found: Resource not found

• 409 Conflict: Resource already exists

• 422 Unprocessable Entity: Validation errors

• 429 Too Many Requests: Rate limit exceeded

• 500 Internal Server Error: Server error

Authentication Types

• Bearer Token: Include Authorization: Bearer your_token in headers

• None: No authentication required for public endpoints

Data Format Standards

• Dates: Use ISO 8601 format (2025-01-23T14:30:00Z)

• Currency: Use decimal format with 2 decimal places (2599.99)

• UUIDs: Use standard UUID format (550e8400-e29b-41d4-a716-446655440000)

• Pagination: 1-based page numbering with limit, offset, total_count, has_more

• Boolean: Use true/false values consistently

Product Status Values

• DRAFT: Product is being created/edited (not public)

• ACTIVE: Product is live and available for purchase

• INACTIVE: Product is temporarily unavailable

• OUT_OF_STOCK: Product is out of stock

• ARCHIVED: Product is no longer sold but kept for history

Product Condition Values

• NEW: Brand new product

• USED_LIKE_NEW: Used but in excellent condition

• USED_GOOD: Used with minor wear

• USED_FAIR: Used with noticeable wear

• REFURBISHED: Professionally restored

• FOR_PARTS: Not functional, for parts only

Payment Interval Values

• DAYS: Payment intervals in days

• WEEKS: Payment intervals in weeks

• MONTHS: Payment intervals in months

Special Features

• Group Buying: Allows customers to form groups for discounted pricing

• Installment Payments: Enables payment plans with interest calculations

• Color Variations: Support for multiple colors with individual pricing

• Specifications: Technical details stored as key-value pairs

• Advanced Search: Full-text search with relevance ranking

• Dynamic Filtering: Multi-criteria filtering with combinations