商品詳情 API

使用前先取得 API 金鑰

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

依商品 UUID 取得單一上架商品及啟用 SKU。缺貨商品仍可查詢；草稿、下架或不存在商品回傳 404。

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

請求標頭

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

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

Path 參數

名稱	型別	必填	說明
id	string (UUID)	是	商品列表回應的 `data[].id`，不是 slug 或 SKU

此接口不需要 Query 參數。

請求範例

curl 'https://api.tenoteno.com/v1/products/83df1a06-541e-4e25-8cb3-8cfc779a534a' \
  -H "Authorization: Bearer $TENO_API_KEY"

成功回應結構

名稱	型別	說明
data	ProductDetail	單一商品物件，不是陣列

ProductDetail

名稱	型別	說明
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	Category[]	啟用分類陣列，無分類時為 `[]`
attributes	object，值為 string[]	屬性 UUID 到屬性值陣列的對應；無屬性時為 `{}`
variants	Variant[]	啟用且未刪除的 SKU，沒有時為 `[]`；包含缺貨 SKU
images	ProductImage[]	依排序值排列的商品圖片，沒有時為 `[]`

名稱	型別	說明
id	string (UUID)	分類 ID
name	string	分類名稱
slug	string	分類識別名稱，可用於列表的 category 篩選
currency	string	目前回應附帶 `TWD`
url	string (URI)	目前回應自動附帶的網址欄位；分類篩選請使用 slug

Variant

名稱	型別	說明
id	string (UUID)	SKU 唯一識別碼
sku	string	SKU 編碼
title	string	規格標題
price	integer	售價，TWD 整數分
compare_at_price	integer 或 null	劃線價，TWD 整數分；未設定為 `null`
available	integer	可售數量，`max(庫存 − 預留數量, 0)`
options	VariantOption[]	規格選項，沒有時為 `[]`

VariantOption

名稱	型別	說明
name	string	規格名稱，例如「顏色」
value	string	規格值，例如「原木色」

ProductImage

名稱	型別	說明
url	string (URI)	圖片絕對網址
alt	string	替代文字，可為空字串
kind	string	圖片用途：`main`（主圖）或 `detail`（詳情圖）

成功回應範例

以下 UUID、網址及商品內容為示意資料，實際呼叫請使用商品列表中的 ID。

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": [
      {
        "id": "3c8a1404-d405-4a61-bfbe-828e65b82017",
        "name": "餐椅",
        "slug": "dining-chairs",
        "currency": "TWD",
        "url": "https://www.tenoteno.com/products/dining-chairs"
      }
    ],
    "attributes": {
      "041a854f-15b1-4111-8ce6-a69bbb5ba0d0": [
        "橡木"
      ]
    },
    "variants": [
      {
        "id": "d5b21602-fb55-482a-a466-3c94b3f5bc61",
        "sku": "OAK-CHAIR-NATURAL",
        "title": "原木色",
        "price": 125000,
        "compare_at_price": 150000,
        "available": 8,
        "options": [
          {
            "name": "顏色",
            "value": "原木色"
          }
        ]
      }
    ],
    "images": [
      {
        "url": "https://s3.tenoteno.com/catalog/oak-chair.jpg",
        "alt": "原木色橡木餐椅",
        "kind": "main"
      }
    ]
  }
}

錯誤回應

HTTP 狀態	error.code	說明
400	INVALID_INPUT	參數格式或範圍錯誤
401	UNAUTHORIZED	金鑰缺失、無效或已撤銷
404	NOT_FOUND	商品不存在、草稿或已下架
500	INTERNAL_ERROR	服務暫時無法處理請求

json

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

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

UUID 格式錯誤回傳 400。未提供有效金鑰時優先回傳 401。

商品詳情 API ​

請求標頭 ​

Path 參數 ​

請求範例 ​

成功回應結構 ​

ProductDetail ​

Category ​

Variant ​

VariantOption ​

ProductImage ​

成功回應範例 ​

錯誤回應 ​