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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.