market-backOfficce/API.md

# API Documentation #

Simple endpoint reference for the Marketplace Backoffice.

## Projects

### Get All Projects
```
GET /api/projects

Response:
[
  {
    "id": "dexar",
    "name": "dexar",
    "displayName": "Dexar Marketplace",
    "active": true,
    "logoUrl": "https://..."
  }
]
```

## Categories

### Get Categories for Project
```
GET /api/projects/:projectId/categories

Response:
[
  {
    "id": "cat1",
    "name": "Electronics",
    "visible": true,
    "priority": 1,
    "img": "https://...",
    "projectId": "dexar",
    "subcategories": [...]
  }
]
```

### Get Single Category
```
GET /api/categories/:categoryId

Response:
{
  "id": "cat1",
  "name": "Electronics",
  "visible": true,
  "priority": 1,
  "img": "https://...",
  "projectId": "dexar",
  "subcategories": [...]
}
```

### Create Category
```
POST /api/projects/:projectId/categories

Body:
{
  "name": "New Category",
  "visible": true,
  "priority": 10,
  "img": "https://..."
}

Response: (created category object)
```

### Update Category
```
PATCH /api/categories/:categoryId

Body: (any field to update)
{
  "name": "Updated Name",
  "visible": false,
  "priority": 5
}

Response: (updated category object)
```

### Delete Category
```
DELETE /api/categories/:categoryId

Response: 204 No Content
```

## Subcategories

### Get Subcategories
```
GET /api/categories/:categoryId/subcategories

Response:
[
  {
    "id": "sub1",
    "name": "Smartphones",
    "visible": true,
    "priority": 1,
    "img": "https://...",
    "categoryId": "cat1",
    "itemCount": 15,
    "hasItems": true,
    "subcategories": []
  }
]

Note: 
- Subcategories can have nested subcategories (recursive)
- If hasItems is true, cannot create child subcategories
```

### Get Single Subcategory
```
GET /api/subcategories/:subcategoryId

Response: (subcategory object with nested subcategories if any)
```

### Create Subcategory
```
POST /api/categories/:categoryId/subcategories

Note: categoryId can be either a category ID or a parent subcategory ID for nested structure

Body:
{
  "id": "custom-id",  // Optional, auto-generated if not provided
  "name": "New Subcategory",
  "visible": true,
  "priority": 10
}

Response: (created subcategory object)

Error: Returns 400 if parent subcategory already has items
```

### Update Subcategory
```
PATCH /api/subcategories/:subcategoryId

Body: (any field)
{
  "id": "new-id",  // ID is now editable (used for routing)
  "name": "Updated Name",
  "visible": false
}

Response: (updated subcategory object)
```

### Delete Subcategory
```
DELETE /api/subcategories/:subcategoryId

Response: 204 No Content
```

## Items

### Get Items (Paginated)
```
GET /api/subcategories/:subcategoryId/items?page=1&limit=20&search=phone&visible=true

Query Params:
- page: number (default: 1)
- limit: number (default: 20)
- search: string (optional - filters by name)
- visible: boolean (optional - filters by visibility)
- tags: string (optional - comma separated tags)

Response:
{
  "items": [
    {
      "id": "item1",
      "name": "iPhone 15 Pro",
      "visible": true,
      "priority": 1,
      "quantity": 50,
      "price": 1299,
      "currency": "USD",
      "imgs": ["https://...", "https://..."],
      "tags": ["new", "featured"],
      "simpleDescription": "Latest iPhone...",
      "description": [
        { "key": "Color", "value": "Black" },
        { "key": "Storage", "value": "256GB" }
      ],
      "subcategoryId": "sub1",
      "comments": [
        {
          "id": "c1",
          "text": "Great product!",
          "author": "John Doe",
          "stars": 5,
          "createdAt": "2024-01-10T10:30:00Z"
        }
      ]
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "hasMore": true
}
```

### Get Single Item
```
GET /api/items/:itemId

Response: (item object with all fields)
```

### Create Item
```
POST /api/subcategories/:subcategoryId/items

Body:
{
  "name": "New Product",
  "visible": true,
  "priority": 10,
  "quantity": 100,
  "price": 999,
  "currency": "USD",
  "imgs": ["https://..."],
  "tags": ["new"],
  "simpleDescription": "Product description",
  "description": [
    { "key": "Size", "value": "Large" }
  ]
}

Response: (created item object)
```

### Update Item
```
PATCH /api/items/:itemId

Body: (any field to update)
{
  "name": "Updated Name",
  "price": 899,
  "quantity": 80,
  "visible": false
}

Response: (updated item object)
```

**Example: Update only images**
```
PATCH /api/items/item123

Body:
{
  "imgs": ["https://new-image1.jpg", "https://new-image2.jpg"]
}

Note: Send the complete array of images (not just changed ones)
Response: (updated item object)
```

### Delete Item
```
DELETE /api/items/:itemId

Response: 204 No Content
```

### Bulk Update Items
```
PATCH /api/items/bulk

Body:
{
  "itemIds": ["item1", "item2", "item3"],
  "data": {
    "visible": true
  }
}

Response: 204 No Content
```

## Upload

### Upload Image
```
POST /api/upload

Body: multipart/form-data
- image: File

Response:
{
  "url": "https://cdn.example.com/image.jpg"
}
```

## Notes

- All endpoints return JSON
- Use PATCH for partial updates
- Priority: lower numbers = appears first
- Currency codes: USD, EUR, RUB, GBP, UAH
- Images: array of URLs
- Description: array of key-value pairs
- Auto-save triggers PATCH with single field every 500ms
### Business Rules

1. **Nested Subcategories**
   - Subcategories can have unlimited nesting levels
   - A subcategory with items (`hasItems: true`) cannot have child subcategories
   - Creating a subcategory under a parent with items will fail

2. **Item Management**
   - When first item is created in a subcategory, `hasItems` is set to true
   - When last item is deleted, `hasItems` is set to false
   - Items belong to the deepest subcategory in the hierarchy

3. **Comments**
   - Stars field is optional (1-5 rating)
   - createdAt is ISO 8601 timestamp
   - author is optional (can be anonymous)

4. **URL Structure for Marketplace**
   - Items: `/{categoryId}/{subcategoryId}/.../{itemId}`
   - Example: `/electronics/smartphones/iphone-15`
   - Example nested: `/electronics/smartphones/apple/iphone-15`