# 產品

### 產品 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 | 更新時間      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.firstline.cc/developer/api/product.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.