商品列表 API

使用前先取得 API 金鑰

請先登入 https://www.tenoteno.com/account/api-keys，建立並取得您的 API 金鑰，再透過 Authorization: Bearer <API_KEY> 呼叫接口。

查詢所有上架商品，包含缺貨商品；不返回草稿或下架商品。

項目	值
方法	`GET`
URL	`https://api.tenoteno.com/v1/products`
認證	Bearer API Key

請求標頭

名稱	型別	必填	說明
Authorization	string	是	`Bearer <API_KEY>`，使用個人中心建立的金鑰

請求不需要 Body。成功回應為 application/json，HTTP 狀態為 200，並帶有 X-Request-Id。金額皆為 TWD 整數分，125000 表示 NT$1,250；時間使用 ISO 8601。

Query 參數

所有參數均為選填，透過 URL Query String 傳入。

名稱	型別	預設值	限制與說明
page	integer	`1`	1–10000，從 1 開始
pageSize	integer	`24`	1–100，每頁筆數
q	string	`""`	最多 200 字；搜尋名稱、slug 或啟用且未刪除 SKU，忽略大小寫
category	string	`""`	最多 200 字；分類 slug，包含啟用子分類；空字串表示不限分類
sort	string (enum)	`""`	`""`、`price-asc` 或 `price-desc`；依最低啟用 SKU 價格排序，無價格商品置後

預設依精選、商品排序值、建立時間及 ID 穩定排序。沒有符合條件的商品或頁碼超出結果時，data 為空陣列。

請求範例

curl --get 'https://api.tenoteno.com/v1/products' \
  -H "Authorization: Bearer $TENO_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=24' \
  --data-urlencode 'q=餐椅' \
  --data-urlencode 'sort=price-asc'

成功回應結構

名稱	型別	說明
data	ProductSummary[]	商品陣列，可為空
pagination	Pagination	分頁資訊

ProductSummary

名稱	型別	說明
id	string (UUID)	商品唯一識別碼，用於詳情接口
slug	string	商品網址識別名稱
name	string	商品名稱
description	string	商品描述，可能包含 HTML；可為空字串
materials	string	材質，可為空字串
dimensions	string	尺寸，可為空字串
created_at	string (date-time)	建立時間
updated_at	string (date-time)	最後更新時間
currency	string	固定為 `TWD`
url	string (URI)	商城商品絕對網址
categories	string[]	啟用分類名稱陣列，無分類時為 `[]`
available	boolean	是否至少有一個啟用且未刪除 SKU 的可售庫存大於 0
price	integer 或 null	啟用且未刪除 SKU 的最低價格，包含缺貨 SKU；沒有啟用 SKU 時為 `null`
image	string (URI) 或 null	主圖絕對網址，未設定時為 `null`

Pagination

名稱	型別	說明
total	integer	符合篩選條件的商品總數
page	integer	本次請求頁碼
pageSize	integer	本次請求每頁筆數
pages	integer	總頁數，無結果時仍為 `1`

成功回應範例

以下為示意資料；將回應中的 data[0].id 用於商品詳情 API。

json

{
  "data": [
    {
      "id": "83df1a06-541e-4e25-8cb3-8cfc779a534a",
      "slug": "oak-chair",
      "name": "橡木餐椅",
      "description": "實木餐椅，適合日常餐敘。",
      "materials": "橡木",
      "dimensions": "寬 45 × 深 50 × 高 80 cm",
      "created_at": "2026-11-01T02:00:00.000Z",
      "updated_at": "2026-11-06T04:00:00.000Z",
      "currency": "TWD",
      "url": "https://www.tenoteno.com/products/oak-chair",
      "categories": [
        "餐椅"
      ],
      "available": true,
      "price": 125000,
      "image": "https://s3.tenoteno.com/catalog/oak-chair.jpg"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "pageSize": 24,
    "pages": 1
  }
}

錯誤回應

HTTP 狀態	error.code	說明
400	INVALID_INPUT	參數格式或範圍錯誤
401	UNAUTHORIZED	金鑰缺失、無效或已撤銷
500	INTERNAL_ERROR	服務暫時無法處理請求

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "requestId": "d37ab519-68b0-46c7-95ea-78d46da23bf6"
}

入口超過限流時回傳 429，可能為非 JSON。更多說明見錯誤與限制。

商品列表 API ​

請求標頭 ​

Query 參數 ​

請求範例 ​

成功回應結構 ​

ProductSummary ​

Pagination ​

成功回應範例 ​

錯誤回應 ​