# Branch API

## Create Branch

`POST /api/branch`

Create a new branch.

### Headers
- `Authorization: Bearer <token>`
- `Content-Type: multipart/form-data`

### Body (multipart/form-data)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | Branch name |
| displayName | string | No | Short/display name for the branch |
| address | string | No | Branch address |
| phones | string[] | No | Array of phone numbers |
| images | file[] | No | Upload images (max 10 files, allowed: png, avif, webp, jpg, jpeg, gif, mp4, mp3, mov, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip. Max 10MB each) |
| isActive | boolean | No | Visibility status (default: true) |

### Response

```json
{
  "message": "Branch create success",
  "success": true,
  "data": {
    "_id": "...",
    "name": "...",
    "displayName": "...",
    "address": "...",
    "phones": [...],
    "imageUrls": ["https://cherryk.s3.ap-southeast-1.amazonaws.com/Branch/Images/1687154298_photo.jpg"],
    "isActive": true
  }
}
```

---

## Update Branch

`PUT /api/branch`

Update an existing branch.

### Headers
- `Authorization: Bearer <token>`
- `Content-Type: multipart/form-data`

### Body (multipart/form-data)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |
| displayName | string | No | Short/display name for the branch |
| address | string | No | Branch address |
| phones | string[] | No | Array of phone numbers |
| existingImageUrls | string[] | No | URLs of images to keep from the current set |
| images | file[] | No | Upload new images (max 10 files, allowed: png, avif, webp, jpg, jpeg, gif, mp4, mp3, mov, pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip. Max 10MB each) |
| isActive | boolean | No | Visibility status |

> **Image management:** Send `existingImageUrls` with URLs you want to keep. Upload new files via `images` field to add more. Omit a URL from `existingImageUrls` to remove that image (also deletes it from S3).

### Response

```json
{
  "success": true,
  "data": {
    "_id": "...",
    "name": "...",
    "displayName": "...",
    "address": "...",
    "phones": [...],
    "imageUrls": ["https://cherryk.s3.ap-southeast-1.amazonaws.com/Branch/Images/1687154298_photo.jpg"],
    "isActive": true
  }
}
```

---

## Get Branch

`GET /api/branch/:id`

Retrieve a branch by ID.

### Headers
- `Authorization: Bearer <token>`

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |

### Response

```json
{
  "success": true,
  "data": [
    {
      "_id": "...",
      "name": "...",
      "displayName": "...",
      "address": "...",
      "phones": [...],
      "imageUrls": [...],
      "isActive": true
    }
  ]
}
```

---

## Delete Branch

`DELETE /api/branch/:id`

Permanently delete a branch from the database. Also deletes all associated images from S3.

### Headers
- `Authorization: Bearer <token>`

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |

### Response

```json
{
  "success": true,
  "message": "Branch deleted successfully",
  "data": { "_id": "...", "name": "...", ... }
}
```

---

## Activate Branch

`POST /api/branch/:id/activate`

Set a branch's `isActive` to `true`.

### Headers
- `Authorization: Bearer <token>`

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |

### Response

```json
{
  "success": true,
  "data": { "isActive": true }
}
```

### Errors
- `404` — Branch not found

---

## Deactivate Branch

`POST /api/branch/:id/deactivate`

Set a branch's `isActive` to `false`.

### Headers
- `Authorization: Bearer <token>`

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |

### Response

```json
{
  "success": true,
  "data": { "isActive": false }
}
```

### Errors
- `404` — Branch not found

---

## List All Branches (Paginated)

`GET /api/branches`

Get a paginated list of branches.

### Headers
- `Authorization: Bearer <token>`

### Query Parameters

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| keyword | string | No | — | Search by branch name or display name (case-insensitive) |
| role | string | No | — | Filter by role |
| isActive | boolean | No | — | Filter by visibility status |
| limit | int | No | 10 | Items per page (max 100) |
| skip | int | No | 0 | Number of items to skip |

### Response

```json
{
  "success": true,
  "count": 0,
  "_metadata": {
    "current_page": 1,
    "per_page": 10,
    "page_count": 0,
    "total_count": 0
  },
  "list": []
}
```

---

## List All Branches V2

`GET /api/v2/branches`

V2 paginated list endpoint — accepts `page` and `limit` (not `skip`).

### Headers
- `Authorization: Bearer <token>`

### Query Parameters

| Param | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| keyword | string | No | — | Search by branch name or display name (case-insensitive) |
| role | string | No | — | Filter by role |
| isActive | boolean | No | — | Filter by visibility status |
| page | int | No | 1 | Page number (starts at 1) |
| limit | int | No | 10 | Items per page (max 100) |

### Response

```json
{
  "success": true,
  "count": 0,
  "_metadata": {
    "current_page": 1,
    "per_page": 10,
    "page_count": 0,
    "total_count": 0
  },
  "list": []
}
```

---

## Get Branch V2

`GET /api/v2/branch/:id`

V2 endpoint — returns a single branch object (not wrapped in an array). No population. Lighter response.

### Headers
- `Authorization: Bearer <token>`

### Parameters

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| id | string | Yes | Branch MongoId |

### Response

```json
{
  "success": true,
  "data": {
    "_id": "...",
    "name": "...",
    "displayName": "...",
    "address": "...",
    "phones": [...],
    "imageUrls": ["https://cherryk.s3.ap-southeast-1.amazonaws.com/Branch/Images/1687154298_photo.jpg"],
    "isActive": true
  }
}
```

### Errors
- `404` — Branch not found

---

## Get All Branches (Head Office)

`GET /api/head-office/branches`

Get all branches (no pagination, no auth required). Used by the head-office Cherry-K website.

### Response

```json
{
  "success": true,
  "data": [
    {
      "_id": "...",
      "name": "...",
      "displayName": "...",
      "address": "...",
      "phones": [...],
      "imageUrls": [...],
      "isActive": true
    }
  ]
}
```