Shop API

This documentation provides comprehensive details for the Shop API endpoints. The API supports creating, retrieving, updating, and deleting shops within the platform. Shops are associated with specific categories and can be managed by administrators or authorized users.

Base URL: http://localhost:8080

Authentication

Most Shop endpoints require Bearer token authentication. Include the access token in the Authorization header:

Authorization: Bearer <your_access_token>

Shop Endpoints

Method	Endpoint	Description	Authentication Required
POST	/shop	Create a new shop	Yes
GET	/shop	Retrieve list of shops	Yes
PUT	/shop/{id}	Update an existing shop	Yes
DELETE	/shop/{id}	Delete a shop	No
GET	/shop/public	Retrieve list of public shops with filters	No
GET	/shop/category/{categoryId}	Retrieve shops by category	No
GET	/shop/featured	Retrieve featured shops	No
GET	/shop/status	Retrieve shops by status	Yes (Admin/Super Admin)
PUT	/shop/approve/{id}	Approve a shop	Yes (Admin/Super Admin)
PUT	/shop/reject/{id}	Reject a shop	Yes (Admin/Super Admin)
PUT	/shop/suspend/{id}	Suspend a shop	Yes (Admin/Super Admin)
PUT	/shop/activate/{id}	Activate a shop	Yes (Admin/Super Admin)

---

Endpoint Details

1. Create Shop

POST /shop

Create a new shop with a specified name and category. The shop will be associated with a valid shop category.

Query Parameters

Parameter	Type	Required	Description
name	string	Yes	Name of the shop
categoryId	string	Yes	UUID of the shop category to associate with

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes

Example Request

curl -X 'POST' \
  'http://localhost:8080/shop?name=Royal%20Shop&categoryId=5e67ec97-9ed6-48ee-9d56-4163fe1711cb' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
  -d ''

Example Response

{
    "id": "cbfdcfa3-fb65-4fa3-9078-e0f8cc63ddbc",
    "name": "Royal Shop"
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the created shop
name	string	Name of the shop

---

2. Get Shops

GET /shop

Retrieve a list of shops with optional pagination support.

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum number of shops to return (default: 20)
offset	number	No	Number of shops to skip for pagination (default: 0)
categoryId	string	No	Filter shops by category ID

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/shop?limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
  "data": [
    {
      "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
      "name": "Piash Shop update",
      "categoryId": "9c95c44c-3767-4ca2-9486-e28e390b3741"
    }
  ],
  "metadata": {
    "totalCount": 1,
    "limit": 10,
    "skip": 0
  }
}

Response Fields

Field	Type	Description
data	array	Array of shop objects
data[].id	string	Unique identifier for the shop
data[].name	string	Name of the shop
data[].categoryId	string	UUID of the associated shop category

---

3. Update Shop

PUT /shop/{id}

Update an existing shop by its ID. You can modify the shop name and optionally change its category.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to update

Query Parameters

Parameter	Type	Required	Description
name	string	No	New name for the shop
categoryId	string	No	New category ID to associate with the shop

Headers

Header	Value	Required
Authorization	Bearer <access_token>	Yes

Example Request

curl -X 'PUT' \
  'http://localhost:8080/shop/a33b8912-e0b2-4058-9d7b-3c7ef9b935c7?name=Shop%20again%20update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
    "name": "Shop again update",
    "categoryId": "9c95c44c-3767-4ca2-9486-e28e390b3741"
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier of the updated shop
name	string	Updated name of the shop
categoryId	string	UUID of the associated shop category

---

4. Delete Shop

DELETE /shop/{id}

Delete a shop by its ID. This operation permanently removes the shop from the system.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to delete

Headers

Header	Value	Required
Authorization	Bearer <access_token>	No

Example Request

curl -X 'DELETE' \
  'http://localhost:8080/shop/d2836959-6bc5-49d0-bd98-e73255a915c5' \
  -H 'accept: application/json'

Example Response

{
    "id": "d2836959-6bc5-49d0-bd98-e73255a915c5"
  }
}

Response Fields

Field	Type	Description
data.id	string	ID of the deleted shop

---

Shop Public Endpoints

Shop Public Endpoints Table

Method	Endpoint	Description	Authentication Required
GET	/shop/public	Retrieve public shops with filters	No
GET	/shop/category/{categoryId}	Retrieve shops by category	No
GET	/shop/featured	Retrieve featured shops	No
GET	/shop/status	Retrieve shops by status	Yes (Admin/Super Admin)
PUT	/shop/approve/{id}	Approve a shop (Admin/Super Admin)	Yes
PUT	/shop/reject/{id}	Reject a shop (Admin/Super Admin)	Yes
PUT	/shop/suspend/{id}	Suspend a shop (Admin/Super Admin)	Yes
PUT	/shop/activate/{id}	Activate a shop (Admin/Super Admin)	Yes

---

5. Get Public Shops

GET /shop/public

Retrieve a list of public shops with optional status and category filters.

Query Parameters

Parameter	Type	Required	Description
status	string	No	Shop status to filter by (APPROVED, etc.)
category	string	No	UUID of the category to filter by
limit	number	No	Maximum number of shops to return (default: 20)
offset	number	No	Number of shops to skip for pagination (default: 0)

Headers

Header	Value	Required
accept	application/json	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/shop/public?status=APPROVED&category=5e67ec97-9ed6-48ee-9d56-4163fe1711cb&limit=10' \
  -H 'accept: application/json'

Example Response

[
    {
      "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
      "name": "Shop Name",
      "categoryId": "5e67ec97-9ed6-48ee-9d56-4163fe1711cb",
      "status": "APPROVED"
    }
  ]
}

Response Fields

Field	Type	Description
data	array	Array of shop objects matching the criteria
data[].id	string	Unique identifier for the shop
data[].name	string	Name of the shop
data[].categoryId	string	UUID of the category the shop belongs to
data[].status	string	Status of the shop (APPROVED, REJECTED, SUSPENDED, etc.)

---

6. Get Shops by Category

GET /shop/category/{categoryId}

Retrieve shops belonging to a specific category.

Path Parameters

Parameter	Type	Required	Description
categoryId	string	Yes	UUID of the category to get shops for

Headers

Header	Value	Required
accept	application/json	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/shop/category/5e67ec97-9ed6-48ee-9d56-4163fe1711cb' \
  -H 'accept: application/json'

Example Response

[
    {
      "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
      "name": "Shop Name",
      "categoryId": "5e67ec97-9ed6-48ee-9d56-4163fe1711cb",
      "status": "APPROVED"
    }
  ]
}

Response Fields

Field	Type	Description
data	array	Array of shop objects in the category
data[].id	string	Unique identifier for the shop
data[].name	string	Name of the shop
data[].categoryId	string	UUID of the category the shop belongs to
data[].status	string	Status of the shop

---

7. Get Featured Shops

GET /shop/featured

Retrieve a list of featured shops.

Headers

Header	Value	Required
accept	application/json	Yes

Example Request

curl -X 'GET' \
  'http://localhost:8080/shop/featured' \
  -H 'accept: application/json'

Example Response

[
    {
      "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
      "name": "Featured Shop",
      "categoryId": "5e67ec97-9ed6-48ee-9d56-4163fe1711cb",
      "status": "APPROVED"
    }
  ]
}

Response Fields

Field	Type	Description
data	array	Array of featured shop objects
data[].id	string	Unique identifier for the shop
data[].name	string	Name of the shop
data[].categoryId	string	UUID of the category the shop belongs to
data[].status	string	Status of the shop

---

8. Get Shops by Status

GET /shop/status

Retrieve shops filtered by status.

Query Parameters

Parameter	Type	Required	Description
status	string	Yes	Status to filter shops by (APPROVED, REJECTED, SUSPENDED, etc.)

Headers

Header	Value	Required
accept	application/json	Yes
Authorization	Bearer <access_token>	Yes (for admin access)

Example Request

curl -X 'GET' \
  'http://localhost:8080/shop/status?status=APPROVED' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

[
    {
      "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
      "name": "Approved Shop",
      "categoryId": "5e67ec97-9ed6-48ee-9d56-4163fe1711cb",
      "status": "APPROVED"
    }
  ]
}

Response Fields

Field	Type	Description
data	array	Array of shop objects with the specified status
data[].id	string	Unique identifier for the shop
data[].name	string	Name of the shop
data[].categoryId	string	UUID of the category the shop belongs to
data[].status	string	Status of the shop

---

9. Approve Shop

PUT /shop/approve/{id}

Approve a shop (Admin/Super Admin only).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to approve

Headers

Header	Value	Required
accept	application/json	Yes
Authorization	Bearer <access_token>	Yes (Admin/Super Admin)

Example Request

curl -X 'PUT' \
  'http://localhost:8080/shop/approve/a33b8912-e0b2-4058-9d7b-3c7ef9b935c7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
    "name": "Approved Shop",
    "status": "APPROVED"
  }
}

Response Fields

Field	Type	Description
data.id	string	Unique identifier of the approved shop
data.name	string	Name of the approved shop
data.status	string	New status of the shop (APPROVED)

---

10. Reject Shop

PUT /shop/reject/{id}

Reject a shop (Admin/Super Admin only).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to reject

Headers

Header	Value	Required
accept	application/json	Yes
Authorization	Bearer <access_token>	Yes (Admin/Super Admin)

Example Request

curl -X 'PUT' \
  'http://localhost:8080/shop/reject/a33b8912-e0b2-4058-9d7b-3c7ef9b935c7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
    "name": "Rejected Shop",
    "status": "REJECTED"
  }
}

Response Fields

Field	Type	Description
data.id	string	Unique identifier of the rejected shop
data.name	string	Name of the rejected shop
data.status	string	New status of the shop (REJECTED)

---

11. Suspend Shop

PUT /shop/suspend/{id}

Suspend a shop (Admin/Super Admin only).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to suspend

Headers

Header	Value	Required
accept	application/json	Yes
Authorization	Bearer <access_token>	Yes (Admin/Super Admin)

Example Request

curl -X 'PUT' \
  'http://localhost:8080/shop/suspend/a33b8912-e0b2-4058-9d7b-3c7ef9b935c7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
    "name": "Suspended Shop",
    "status": "SUSPENDED"
  }
}

Response Fields

Field	Type	Description
data.id	string	Unique identifier of the suspended shop
data.name	string	Name of the suspended shop
data.status	string	New status of the shop (SUSPENDED)

---

12. Activate Shop

PUT /shop/activate/{id}

Activate a shop (Admin/Super Admin only).

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Unique identifier of the shop to activate

Headers

Header	Value	Required
accept	application/json	Yes
Authorization	Bearer <access_token>	Yes (Admin/Super Admin)

Example Request

curl -X 'PUT' \
  'http://localhost:8080/shop/activate/a33b8912-e0b2-4058-9d7b-3c7ef9b935c7' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Example Response

{
    "id": "a33b8912-e0b2-4058-9d7b-3c7ef9b935c7",
    "name": "Activated Shop",
    "status": "APPROVED"
  }
}

Response Fields

Field	Type	Description
data.id	string	Unique identifier of the activated shop
data.name	string	Name of the activated shop
data.status	string	New status of the shop (APPROVED)

---

Error Handling

This API follows industry-standard error handling patterns (Stripe, GitHub, OpenAI):

Success Responses

• HTTP status code indicates success (200, 201, 204)
• Response body contains data directly (no wrapper object)
• No isSuccess or statusCode fields needed

Error Responses

Standard Error (400/401/403/404/500):

{
  "message": "Error description"
}

Validation Error (400):

{
  "message": "Validation failed",
  "errors": [
    {"field": "email", "message": "Invalid email format"},
    {"field": "password", "message": "Password must be at least 8 characters"}
  ]
}

Common Error Codes

Status Code	Description	Example Message
400	Bad Request	"Invalid email or password"
401	Unauthorized	"Authentication required"
403	Forbidden	"Insufficient permissions"
404	Not Found	"Product not found"
409	Conflict	"User already exists with this email"
500	Internal Server Error	"Internal server error"

All error messages are centralized and consistent across all endpoints.

---

Shop Management Guidelines

Public Access

• Public endpoints provide access to APPROVED shops only
• Featured shops are highlighted based on admin configuration
• Category-based filtering helps users discover relevant shops

Administrative Actions

• Approval/rejection affects shop visibility to customers
• Suspended shops are temporarily unavailable
• Activated shops return to approved state after suspension