parsshop-back/docs/products-api.md

Products API

Base URL: /api

All responses are wrapped by the global response interceptor:

{
  "success": true,
  "statusCode": 200,
  "path": "/api/products",
  "timestamp": "2026-03-25T10:00:00.000Z",
  "data": {}
}

Product Model

Each product now supports:

• sku
• title
• slug
• summary
• description
• technicalCode
• brand
• basePriceUSD
• salePriceUSD
• stock
• featured
• type
• status: draft | published | archived
• mainImageUrl
• imageGalleryUrls
• threeDModelUrl
• attributes: JSON object for technical specs/features
• tags: string array
• averageRating
• reviewsCount
• category

Public Product APIs

GET /api/products

Lists published products for storefront.

Query params:

• search
• type
• categoryId
• brand
• attributes as JSON string
• tags as JSON string array
• featured
• sort: newest | oldest | price_asc | price_desc | popular | top_rated
• page
• limit

Optional request header:

• x-product-type: Industrial | Automotive

Example:

GET /api/products?search=skf&featured=true&sort=price_asc&page=1&limit=20
x-product-type: Industrial

List response items are intentionally lightweight and include only fields needed for product cards / list pages. The attributes array is limited to the first 2 visible attributes, sorted by displayOrder.

GET /api/products/brands/:brandSlug

Lists published products for one brand by brand slug.

Supports the same query params as GET /api/products:

• search
• featured
• sort
• page
• limit

Optional request header:

• x-product-type: Industrial | Automotive

GET /api/products/brands/:brandSlug/filters

Returns available brand page filters relative to the selected brand and current query filters.

Response shape:

• categories: available categories with count
• attributes: available filterable attributes and their values with count
• stock: inStock and outOfStock

Optional request header:

• x-product-type: Industrial | Automotive

GET /api/products/categories/:categorySlug

Lists published products for one category by category slug.

Supports the same query params as GET /api/products:

• search
• featured
• sort
• page
• limit

Optional request header:

• x-product-type: Industrial | Automotive

GET /api/products/categories/:categorySlug/filters

Returns available category page filters relative to the selected category and current query filters.

Response shape:

• brands: available brands with count
• attributes: available filterable attributes and their values with count
• stock: inStock and outOfStock

Optional request header:

• x-product-type: Industrial | Automotive

GET /api/product/:slug

Returns one published product by slug with category and up to 10 approved reviews.

GET /api/products/:id

Returns one published product with category and up to 10 approved reviews.

GET /api/products/:id/reviews

Returns approved reviews for one published product.

POST /api/products/:id/reviews

Creates a review for a published product. New reviews are stored as pending approval.

Request body:

{
  "name": "Ali Rezaei",
  "email": "ali@example.com",
  "rating": 5,
  "title": "Excellent quality",
  "comment": "Good quality product with solid packaging."
}

Admin Product APIs

These endpoints require:

• Bearer token
• Admin role
• products.manage permission

GET /api/admin/products

Lists all products for admin panel, including drafts and archived items.

Query params:

• search
• type
• status
• categoryId
• brand
• attributes as JSON string
• tags as JSON string array
• featured
• sort: newest | oldest | price_asc | price_desc | popular | top_rated
• page
• limit

Optional request header:

• x-product-type: Industrial | Automotive

GET /api/admin/products/:id

Returns one product for admin panel.

POST /api/admin/products

Creates a product. Content type: multipart/form-data

Fields:

• sku
• title
• slug
• summary
• description
• technicalCode
• brand
• basePriceUSD
• salePriceUSD
• stock
• featured
• type
• status
• categoryId
• attributes as JSON string
• each item in attributes can include displayOrder
• tags as JSON string array
• existingMainImageUrl
• existingGalleryUrls as JSON string array
• existingThreeDModelUrl
• mainImage file
• images files
• model3d file

Notes:

• mainImage is the primary product image.
• images fills the gallery.
• model3d is for .glb, .gltf, or other supported 3D assets.
• If no new file is uploaded, existing URLs can be sent.

Example multipart fields:

sku=BRG-6006-2RS
title=SKF 6006-2RS Deep Groove Bearing
slug=skf-6006-2rs
summary=Industrial bearing for motors and gearboxes
description=Full product description
technicalCode=SKF-6006
brand=SKF
basePriceUSD=42.5
salePriceUSD=39.99
stock=28
featured=true
type=bearing
status=published
categoryId=<uuid>
attributes={"innerDiameter":"30mm","outerDiameter":"55mm","sealType":"2RS"}
tags=["bearing","skf","industrial"]

PATCH /api/admin/products/:id

Updates a product. Content type: multipart/form-data

Behavior:

• upload new mainImage to replace the old main image
• upload new images to replace the whole gallery
• upload new model3d to replace the old 3D model
• send existingGalleryUrls to keep only selected old gallery items
• send empty existingMainImageUrl or existingThreeDModelUrl to clear them

DELETE /api/admin/products/:id

Deletes product row and linked uploaded assets.

Admin Review APIs

GET /api/admin/products/reviews/list

Lists reviews for moderation.

Query params:

• productId
• isApproved
• isPinned
• page
• limit

PATCH /api/admin/products/reviews/:reviewId

Approves or pins a review.

Request body:

{
  "isApproved": true,
  "isPinned": false
}

When approval state changes, averageRating and reviewsCount on the product are recalculated.

DELETE /api/admin/products/reviews/:reviewId

Deletes a review and refreshes product review stats.

Category APIs

Current category endpoints:

• POST /api/categories
• GET /api/categories
• GET /api/categories/:id
• PATCH /api/categories/:id
• DELETE /api/categories/:id

Category object:

• id
• name
• slug
• type
• parent
• children

Rule:

• child category type must match parent category type

Frontend Integration Notes

• Public storefront should use /api/products
• Admin panel should use /api/admin/products
• Reviews submitted from storefront are pending until approved in admin
• attributes and tags should be managed as structured JSON on the frontend
• Use mainImageUrl, imageGalleryUrls, and threeDModelUrl as separate media sections in UI