WooCommerce REST API 轉接器

一套可直接替換的 STOAR REST API，對應 WooCommerce v3 的線路格式——相同的 URL 路徑（/wp-json/wc/v3/...）、相同的扁平查詢參數語法、相同的 JSON 回應欄位名稱、相同的驗證選項。現有的 WooCommerce 用戶端函式庫（例如 automattic/woocommerce PHP／JS、klarna/woocommerce-rest-api Node）無需修改即可與 STOAR 溝通。

本轉接器是 STOAR 可擴充的 API 轉接器框架的第二個實作（第一個是 Magento）。它示範了一種本質上截然不同的供應商風格——扁平查詢參數而非巢狀 searchCriteria[…]、Basic Auth 而非只有 Bearer、狀態詞彙為 processing／completed 而非 paid／delivered——如何在同一個資料層上與 Magento 並存。

目錄 #

• 快速上手
• 驗證
• 端點
  • 列出訂單
  • 取得單筆訂單
  • 列出備註
  • 新增備註
  • 列出退款
  • 建立退款
  • 列出商品
  • 取得單筆商品
• 查詢參數
• 欄位對應（WooCommerce ↔ STOAR）
• 狀態轉換
• 回應結構
• 實際範例
• 錯誤結構
• 流量限制

快速上手 #

# 1. Get a Sanctum token with woocommerce:admin ability — issued via /manager/api-tokens
#    or via the Magento token endpoint (POST /rest/V1/integration/admin/token), then
#    grant the woocommerce:admin ability inside /manager.
TOKEN="2|L5pXj63e881lkgtHPK7Hjozyq7Pb3trHCy0iaDRf76405f72"

# 2. List the last 5 orders (Bearer auth — STOAR extension; works alongside Basic)
curl -s "https://app.stoar.ai/wp-json/wc/v3/orders?per_page=5&orderby=date&order=desc" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.[] | {id, status, total, currency}'

# 3. Use HTTP Basic just like a real WooCommerce store
curl -s "https://app.stoar.ai/wp-json/wc/v3/products?per_page=3" \
  -u "any-key:$TOKEN"

# 4. Or stuff credentials into the query string (still over HTTPS only)
curl -s "https://app.stoar.ai/wp-json/wc/v3/products?consumer_key=any&consumer_secret=$TOKEN"

驗證 #

WooCommerce 支援三種驗證風格；本轉接器全部接受，並在內部轉換成同一套 Sanctum personal-access-token 檢查。Token 由 STOAR 的 /manager/api-tokens 頁面核發（或以程式方式透過 AdminUser::createToken('label', ['woocommerce:admin']) 產生）。

對應到 Sanctum

轉接器會忽略 consumer_key（可以傳入任意字串——"any-key" 就可以）。consumer_secret 必須是一個有效的 Sanctum personal-access token，且其 abilities 陣列包含 woocommerce:admin。

這個對應純粹是一層解讀；從 STOAR 的角度來看，每個 WC 請求都只是以 Bearer 驗證的 Sanctum 請求。同一列 personal-access-token 記錄可同時支援：

• 使用 /rest/V1/orders 的 Magento 用戶端（需要 magento:admin 能力）
• 使用 /wp-json/wc/v3/orders 的 WooCommerce 用戶端（需要 woocommerce:admin 能力）

您可以核發一個同時具備兩種能力的 token，或分開核發——由您決定。

顧客 token

顧客範圍的端點尚未提供。woocommerce:customer 能力保留供日後使用。

端點 #

所有路徑都相對於 /wp-json/wc/v3（原封不動沿用 WordPress REST 命名空間）。

GET /wp-json/wc/v3/orders

列出訂單。

授權： Bearer／Basic／查詢參數，需具備 woocommerce:admin 能力。

查詢參數： 見查詢參數。

回應（200）： 訂單的扁平 JSON 陣列。分頁資訊放在標頭中，不在內文裡：

HTTP/1.1 200 OK
X-WP-Total:      150
X-WP-TotalPages: 8
Content-Type:    application/json

[
  { /* order */ },
  { /* order */ }
]

為什麼用標頭而不是外層結構？ 這正是 WooCommerce 的實際慣例——與 Magento 的 {items, search_criteria, total_count} 包裝不同。WC 用戶端函式庫（Automattic 官方的 PHP／JS 用戶端）會讀取 X-WP-Total 來驅動分頁游標。

GET /wp-json/wc/v3/orders/{id}

以數字 id 取得單筆訂單。

回應（200）： 見回應結構。

錯誤：

{
  "code":    "woocommerce_rest_shop_order_invalid_id",
  "message": "Invalid shop_order ID.",
  "data":    { "status": 404, "id": 99999 }
}

GET /wp-json/wc/v3/orders/{id}/notes

列出該訂單的狀態歷程記錄，重新整理成 WooCommerce 備註的形式。

回應（200）：

[
  {
    "id":               42,
    "author":           "system",
    "date_created":     "2026-04-10T12:00:00+00:00",
    "date_created_gmt": "2026-04-10T12:00:00+00:00",
    "note":             "Payment received",
    "customer_note":    false,
    "_links":           { "self": [...], "collection": [...], "up": [...] }
  }
]

customer_note 恆為 false，因為 Stoar 在資料層級並不區分顧客可見的備註與僅限後台的備註。

POST /wp-json/wc/v3/orders/{id}/notes

新增一則備註（對應為 Stoar 中一筆新的 OrderStatusLog 記錄）。

請求：

{ "note": "Customer phoned to confirm delivery slot" }

customer_note（bool）會被接受，但目前沒有實際作用。

回應（201）： 新備註，結構與 GET .../notes 的項目相同。

錯誤：

• 400 rest_invalid_param——缺少 note
• 404——未知的訂單 id

GET /wp-json/wc/v3/orders/{id}/refunds

列出某訂單的退款。Stoar 沒有獨立的退款資料表——轉接器會回傳下列兩者之一：

• 當 refunded_amount === 0 時回傳 []，或
• 回傳 [{...}]，內含一筆合成的退款記錄，其 id === parent_id === order.id

[
  {
    "id":               123,
    "parent_id":        123,
    "date_created":     "2026-04-12T08:00:00+00:00",
    "amount":           "30.00",
    "reason":           "",
    "refunded_by":      0,
    "refunded_payment": true,
    "meta_data":        [],
    "line_items":       [],
    "api_refund":       true
  }
]

POST /wp-json/wc/v3/orders/{id}/refunds

發出退款。會委派給 Stoar 既有的 Order::processRefund()，它再透過 StripeService::processRefund() 呼叫 Stripe。全額退款時 Stoar 會把訂單標記為 refunded，部分退款則累加 refunded_amount。

請求：

{ "amount": 30, "reason": "Customer changed mind" }

兩個欄位都是選填。若省略 amount，Stoar 會退還全部剩餘可退金額。

回應（201）： 上述結構的退款記錄。

錯誤：

• 404——未知的訂單 id
• 422 woocommerce_rest_invalid_state——訂單不可退款（沒有 Stripe payment intent，或狀態不是 paid/processing/shipped/delivered）

GET /wp-json/wc/v3/products

列出商品。

查詢參數： 見查詢參數。

回應（200）： 扁平陣列，附 X-WP-Total／X-WP-TotalPages 標頭。

GET /wp-json/wc/v3/products/{id}

以數字 id 取得單筆商品（不像 Magento 使用 SKU）。

回應（200）： 見回應結構。

錯誤： 404 woocommerce_rest_product_invalid_id。

查詢參數 #

WooCommerce 使用扁平的查詢字串參數——遠比 Magento 巢狀的 searchCriteria[…] 文法單純。轉換成同一套與供應商無關的 OrderQuery／ProductQuery 值物件，是在轉接器的 Search/OrderQueryParser 與 Search/ProductQueryParser 類別中完成的。

共通參數（訂單 + 商品）

僅限訂單

僅限商品

未知的參數會被靜默忽略（與 WC 行為一致）。無法轉換成合理值的篩選值（例如對商品下 ?status=on-hold）會產生空群組，而不是回傳 400。

欄位對應（WooCommerce ↔ STOAR） #

訂單

訂單 line_item

商品

狀態轉換 #

WooCommerce 與 Stoar 使用不同的狀態詞彙。轉接器會雙向轉換：篩選時（?status=processing）把 WC 值對應到 Stoar；序列化回應時再把 Stoar 的 status 對應回 WC。

訂單狀態

商品狀態

商品類型

對應到 null 的篩選值（例如對商品下 ?status=trash）會被靜默忽略——不會回報錯誤。

回應結構 #

訂單——附註解範例

{
  "id":             456,
  "parent_id":      0,
  "number":         "456",
  "order_key":      "abc123…",
  "created_via":    "checkout",
  "version":        "8.5.0",
  "status":         "processing",
  "currency":       "EUR",
  "date_created":   "2026-04-10T09:00:00+00:00",
  "date_modified":  "2026-04-10T09:30:00+00:00",
  "discount_total": "0.00",
  "discount_tax":   "0.00",
  "shipping_total": "5.00",
  "shipping_tax":   "0.00",
  "cart_tax":       "10.00",
  "total":          "115.00",
  "total_tax":      "10.00",
  "prices_include_tax": false,
  "customer_id":    45,
  "customer_note":  "",
  "billing":        { /* WC address shape (flat) */ },
  "shipping":       { /* WC address shape (flat) */ },
  "payment_method": "stripe",
  "payment_method_title": "Credit / Debit Card",
  "transaction_id": "pi_test_…",
  "date_paid":      "2026-04-10T09:05:00+00:00",
  "date_completed": null,
  "cart_hash":      "",
  "meta_data":      [
    { "id": 0, "key": "_stoar_status",       "value": "paid" },
    { "id": 0, "key": "_stoar_lookup_token", "value": "abc123…" }
  ],
  "line_items": [
    {
      "id":            456,
      "name":          "Widget",
      "product_id":    789,
      "variation_id":  12,
      "quantity":      2,
      "tax_class":     "",
      "subtotal":      "100.00",
      "subtotal_tax":  "10.00",
      "total":         "100.00",
      "total_tax":     "10.00",
      "taxes":         [],
      "meta_data":     [],
      "sku":           "WID-1-A",
      "price":         50
    }
  ],
  "tax_lines":      [],
  "shipping_lines": [
    {
      "id":           0,
      "method_title": "Standard",
      "method_id":    "flat_rate",
      "instance_id":  "",
      "total":        "5.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    []
    }
  ],
  "fee_lines":    [],
  "coupon_lines": [],
  "refunds":      [],
  "_links":       {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders/456" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders" }]
  }
}

商品——節錄範例

{
  "id":                 789,
  "name":               "Widget",
  "slug":               "widget",
  "permalink":          "https://app.stoar.ai/product/widget",
  "type":               "simple",
  "status":             "publish",
  "featured":           true,
  "catalog_visibility": "visible",
  "description":        "<p>A great widget</p>",
  "short_description":  "Great widget",
  "sku":                "WID-1",
  "price":              "79.99",
  "regular_price":      "99.99",
  "sale_price":         "79.99",
  "on_sale":            true,
  "purchasable":        true,
  "manage_stock":       true,
  "stock_quantity":     42,
  "stock_status":       "instock",
  "weight":             "1.5",
  "categories":         [{ "id": 5, "name": "Widgets", "slug": "widgets" }],
  "images":             [
    { "id": 0, "src": "products/widget.webp", "name": "primary",   "position": 0, "alt": "" },
    { "id": 0, "src": "products/g1.webp",     "name": "gallery-1", "position": 1, "alt": "" }
  ],
  "attributes":         [],
  "variations":         [],
  "meta_data":          [
    { "id": 0, "key": "_stoar_id", "value": "789" },
    { "id": 0, "key": "_stoar_low_stock_threshold", "value": "3" }
  ],
  "_links":             {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/products/789" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/products" }]
  }
}

對於可組態／variable 商品，variations 會填入規格 id，stock_quantity 則是各規格庫存的加總。

實際範例 #

正式環境對 GET /wp-json/wc/v3/orders/10126 的即時回應（USD $936.98，兩個簡單商品明細，以 PayID 付款）。個資已匿名化。

請求

GET /wp-json/wc/v3/orders/10126
Authorization: Bearer 2|L5pXj63e881lkgtHPK7Hjozyq7Pb3trHCy0iaDRf76405f72

回應

{
  "id":               10126,
  "parent_id":        0,
  "number":           "10126",
  "order_key":        "REDACTED-FOR-DOCS",
  "created_via":      "checkout",
  "version":          "8.5.0",
  "status":           "processing",
  "currency":         "USD",
  "date_created":     "2025-06-03T04:56:43+00:00",
  "date_modified":    "2025-06-03T04:56:43+00:00",
  "discount_total":   "0.00",
  "discount_tax":     "0.00",
  "shipping_total":   "0.00",
  "shipping_tax":     "0.00",
  "cart_tax":         "0.00",
  "total":            "936.98",
  "total_tax":        "0.00",
  "prices_include_tax": false,
  "customer_id":      5794,
  "customer_note":    "",
  "billing": {
    "first_name": "Jane",
    "last_name":  "Doe",
    "company":    "",
    "address_1":  "1 Example Street",
    "address_2":  "",
    "city":       "Phoenix",
    "state":      "AZ",
    "postcode":   "85001",
    "country":    "US",
    "email":      "",
    "phone":      "+1-555-0100"
  },
  "shipping":         { /* same shape as billing */ },
  "payment_method":   "payid",
  "payment_method_title": "PayID",
  "transaction_id":   "",
  "date_paid":        null,
  "date_completed":   null,
  "cart_hash":        "",
  "meta_data": [
    { "id": 0, "key": "_stoar_status",       "value": "paid" },
    { "id": 0, "key": "_stoar_lookup_token", "value": "REDACTED-FOR-DOCS" }
  ],
  "line_items": [
    {
      "id":           30219,
      "name":         "Reloop Terminal Mix 8",
      "product_id":   112238,
      "variation_id": 95589,
      "quantity":     3,
      "tax_class":    "",
      "subtotal":     "897.00",
      "subtotal_tax": "0.00",
      "total":        "897.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    [],
      "sku":          "RELOOP_TERMINALMIX8_025-DEF",
      "price":        299
    },
    {
      "id":           30220,
      "name":         "Premium Skateboard Socks",
      "product_id":   51706,
      "variation_id": 33857,
      "quantity":     2,
      "tax_class":    "",
      "subtotal":     "39.98",
      "subtotal_tax": "0.00",
      "total":        "39.98",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    [],
      "sku":          "SK8-SOCK-027-DEF",
      "price":        19.99
    }
  ],
  "tax_lines":      [],
  "shipping_lines": [
    {
      "id":           0,
      "method_title": "Free Shipping",
      "method_id":    "flat_rate",
      "instance_id":  "",
      "total":        "0.00",
      "total_tax":    "0.00",
      "taxes":        [],
      "meta_data":    []
    }
  ],
  "fee_lines":    [],
  "coupon_lines": [],
  "refunds":      [],
  "_links":       {
    "self":       [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders/10126" }],
    "collection": [{ "href": "https://app.stoar.ai/wp-json/wc/v3/orders" }]
  }
}

整合者應注意的細節

這些與 Magento 的注意事項重疊——底層的 Stoar 資料是同一份，只是以不同的外層結構呈現：

錯誤結構 #

WooCommerce 的錯誤格式為：

{
  "code":    "machine_readable_code",
  "message": "Human-readable message",
  "data":    { "status": 404, "id": 99999 }
}

……而非 Magento 的 {message, parameters, trace}。

data.status 永遠與 HTTP 狀態碼一致。有意義時會加上資源專屬的鍵（data.id）。

流量限制 #

保護 Magento 的同一組以 Sanctum token 為鍵的節流機制（api-rest，預設每分鐘 60 次請求）同樣保護 WC 路由。兩者都可在 /manager/api-settings 全域設定。觸發時，回應會使用 WC 的錯誤外層結構：

{
  "code":    "woocommerce_rest_too_many_requests",
  "message": "Too many requests. Please retry after a short pause.",
  "data":    { "status": 429 }
}

設定介面的完整操作說明請見 Magento 文件的「流量限制」一節。

延伸閱讀 #

• app/Api/Core/OrderRepository.php、app/Api/Core/ProductRepository.php——每個轉接器都倚賴的抽象邊界
• app/Api/Adapters/WooCommerce/Support/StatusTranslator.php——雙向詞彙對應
• WooCommerce REST API 參考文件——本轉接器所對應的上游規格