Shops Management Service

⚠️ CRITICAL REQUIREMENTS

🔐 Authentication Required ALL endpoints in this service require Bearer token authentication unless specified as public. Requests without valid authentication will receive a 401 Unauthorized response.

🏪 Shop Ownership Validation CRITICAL: Shop update endpoints validate ownership. Only shop owners can modify their shops. Admin roles can access all shop details.

🎯 One Rating/Review Per User IMPORTANT: Users can only create ONE rating and ONE review per shop. Use update endpoints to modify existing ratings/reviews.

Service Overview

The Shops Management Service provides comprehensive shop management capabilities including shop creation, ratings, reviews, and category management. This service consists of four main components:

1. Shop Categories - Manage shop categorization

2. Shop Management - Create, update, and retrieve shop information

3. Rating System - 1-5 star rating functionality

4. Review System - Text-based review system with moderation

Base URL

/api/v1/shops

Authentication

All protected endpoints require authentication via Bearer token:

Authorization: Bearer {access_token}

Common Response Format

Success Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2024-12-09T10:30:00",
  "data": "Detailed error message or validation errors"
}

Data Models Overview

Shop Status Types

• PENDING - Awaiting admin approval

• ACTIVE - Active and operational

• SUSPENDED - Temporarily suspended by admin

• CLOSED - Permanently closed/inactive

• UNDER_REVIEW - Under admin review for policy violations

Shop Types

• PHYSICAL - Physical store only (brick-and-mortar)

• ONLINE - Online store only (e-commerce)

• HYBRID - Both physical and online presence

Verification Badges

• BRONZE - Basic verification (documents verified)

• SILVER - Enhanced verification (business registration + documents)

• GOLD - Premium verification (full compliance + good track record)

• PREMIUM - Highest level (partner status + excellent performance)

Review Status Types

• ACTIVE - Publicly visible review

• HIDDEN - Hidden by admin/moderation

• FLAGGED - Flagged for review

• UNDER_REVIEW - Under moderation review

Quick Start

1. Authentication: Obtain a Bearer token via the Authentication Service

2. Browse Categories: Get available shop categories (public endpoint)

3. Create Shop: Submit shop creation request with required fields

4. Manage Content: Add ratings and reviews to shops

5. Admin Operations: Approve shops and manage categories (admin only)

Rate Limiting

Standard rate limits apply to all endpoints:

• Authenticated users: Higher limits for most operations

• Public endpoints: Generous limits for browsing

• Admin operations: Standard authenticated limits

• Content creation: Rate limited to prevent spam

Rate limit exceeded response:

{
  "success": false,
  "httpStatus": "TOO_MANY_REQUESTS",
  "message": "Too many requests. Please wait before requesting again.",
  "action_time": "2024-12-09T10:30:00"
}