> For the complete documentation index, see [llms.txt](https://help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.firstline.cc/developer/api/product.md).

# 產品

### 產品 API (`api/product`)

{% hint style="success" %}
 此 API 為 2024-10-04 後版本 v.2.62.11 開放。
{% endhint %}

## 搜尋產品

**請求方法**: `GET`\
**端點**: `/api/v1/product`\
**說明**: 搜尋符合條件的產品列表。

**Curl 範例**

```bash
curl -X GET \
     -H "Content-Type: application/json" \
     '{
       "name": "手機",
       "sku": "SKU12345",
       "price__lower": 1000,
       "price__upper": 5000,
     }' \
     https://{API_HOST}/api/v1/product
```

**URL 參數**

| 參數名稱           | 類型     | 說明        |
| -------------- | ------ | --------- |
| `name`         | String | 產品名稱關鍵字搜尋 |
| `sku`          | String | 產品 SKU 編號 |
| `price__lower` | Number | 最低價格篩選    |
| `price__upper` | Number | 最高價格篩選    |

**回應範例**

```json
{
    "data": [
        {
            "id": 101,
            "name": "iPhone 15",
            "sku": "SKU12345",
            "description": "最新款iPhone 15，具有先進的功能。",
            "price": "999.99",
            "stock": 150,
            "category": "電子產品",
            "created_at": "2024-09-01 12:00:00",
            "updated_at": "2024-09-15 08:30:45"
        },
        // 更多產品資料...
    ],
    "links": {
        // 分頁相關連結
    },
    "meta": {
        // 分頁相關元數據
    }
}
```

***

## 取得單筆產品資料

**請求方法**: `GET`\
**端點**: `/api/v1/product/{product_id}`\
**說明**: 根據產品 ID 取得單筆產品詳細資料。

**Curl 範例**

```bash
curl -X GET \
     -H "Content-Type: application/json" \
     https://{API_HOST}/api/v1/product/101
```

**URL 參數**

| 參數名稱         | 類型     | 說明       |
| ------------ | ------ | -------- |
| `product_id` | Number | 產品的唯一識別碼 |

**回應範例**

```json
{
    "data": {
        "id": 101,
        "name": "iPhone 15",
        "sku": "SKU12345",
        "description": "最新款iPhone 15，具有先進的功能。",
        "price": "999.99",
        "stock": 150,
        "category": "電子產品",
        "created_at": "2024-09-01 12:00:00",
        "updated_at": "2024-09-15 08:30:45"
    }
}
```

***

## 新增產品

**請求方法**: `POST`\
**端點**: `/api/v1/product`\
**說明**: 新增一筆產品資料。

**Curl 範例**

```bash
curl -X POST \
     -H "Content-Type: application/json" \
     '{
       "name": "Galaxy S24",
       "sku": "SKU67890",
       "description": "最新款Galaxy S24，功能強大。",
       "price": 899.99,
       "stock": 200,
       "category": "電子產品"
     }' \
     https://{API_HOST}/api/v1/product
```

**表單資料**

| 欄位名稱          | 類型     | 說明        | 必填 |
| ------------- | ------ | --------- | -- |
| `name`        | String | 產品名稱      | 是  |
| `sku`         | String | 產品 SKU 編號 | 是  |
| `description` | String | 產品描述      | 否  |
| `price`       | Number | 產品價格      | 是  |
| `stock`       | Number | 庫存數量      | 是  |
| `category`    | String | 產品分類      | 是  |

**回應範例**

```json
{
    "data": {
        "id": 102,
        "name": "Galaxy S24",
        "sku": "SKU67890",
        "description": "最新款Galaxy S24，功能強大。",
        "price": "899.99",
        "stock": 200,
        "category": "電子產品",
        "created_at": "2024-10-04 09:15:30",
        "updated_at": "2024-10-04 09:15:30"
    }
}
```

***

## 更新產品資料

**請求方法**: `PUT`\
**端點**: `/api/v1/product/{product_id}`\
**說明**: 更新指定產品的資料。

**Curl 範例**

```bash
curl -X PUT \
     -H "Content-Type: application/json" \
     '{
       "price": 949.99,
       "stock": 180
     }' \
     https://{API_HOST}/api/v1/product/101
```

**URL 參數**

| 參數名稱         | 類型     | 說明       |
| ------------ | ------ | -------- |
| `product_id` | Number | 產品的唯一識別碼 |

**表單資料**

| 欄位名稱          | 類型     | 說明        | 必填 |
| ------------- | ------ | --------- | -- |
| `name`        | String | 產品名稱      | 否  |
| `sku`         | String | 產品 SKU 編號 | 否  |
| `description` | String | 產品描述      | 否  |
| `price`       | Number | 產品價格      | 否  |
| `stock`       | Number | 庫存數量      | 否  |
| `category`    | String | 產品分類      | 否  |

**回應範例**

```json
{
    "data": {
        "id": 101,
        "name": "iPhone 15",
        "sku": "SKU12345",
        "description": "最新款iPhone 15，具有先進的功能。",
        "price": "949.99",
        "stock": 180,
        "category": "電子產品",
        "created_at": "2024-09-01 12:00:00",
        "updated_at": "2024-10-04 10:25:50"
    }
}
```

***

#### 產品資料模型

以下是產品資料的結構與說明：

| **欄位名稱**      | **類型** | **說明**    |
| ------------- | ------ | --------- |
| `id`          | Number | 產品 ID     |
| `name`        | String | 產品名稱      |
| `sku`         | String | 產品 SKU 編號 |
| `description` | String | 產品描述      |
| `price`       | Number | 價格        |
| `stock`       | Number | 庫存數量      |
| `created_at`  | String | 建立時間      |
| `updated_at`  | String | 更新時間      |