追蹤文件站台與 API 的異動
2026 年 9 月 21 日
2026 年 9 月 21 日
客戶端點改名為 /v1/companies（breaking change）
/v1/customers、/v1/customers/{id}、/v1/customers/batch 全面下線，改為對應的 /v1/companies 路徑——欄位、驗證規則與去重行為都不變，純粹是路徑改名，沒有過渡期或別名。請直接把呼叫的網址換成 /v1/companies，不需要調整送出的欄位。
點數餘額同步端點下線，改用點數／合約額度家族
POST /v1/point-balances/batch 已下線，改由 POST /v1/companies/point-quota/batch 取代，並新增 GET /v1/companies/{id}/point-quota 讀取目前的點數水位。同時新增鏡像的合約額度家族：GET /v1/companies/{id}/credit-quota、POST /v1/companies/credit-quota/batch。兩個家族的 enabled 欄位意義並不對稱——合約額度的 enabled 會真的影響下單放行，點數額度的 enabled 目前只回報、不卡控。
新增組合商品與獨立的價格端點
新增組合商品（Bundle）家族：GET /v1/bundles、GET /v1/bundles/{id}、POST /v1/bundles、PUT /v1/bundles/{id}、POST /v1/bundles/batch，可用既有的一般規格當配方元件建立組合商品，並回傳依目前庫存動態算出的 availableQty。同時新增獨立的價格端點——一般規格的 GET /v1/skus/{id}/price、PUT /v1/prices/batch，以及組合商品的 GET /v1/bundles/{id}/prices、PUT /v1/bundle-prices/batch，可以只更新牌價與對外售價，不必重送整筆主檔。
商品與規格清單不再包含組合商品
GET /v1/products、GET /v1/skus 與對應的單筆查詢端點現在會濾掉組合商品，組合商品只會出現在新的「組合商品」家族底下。商品的建立與批次端點若 outerSysCode 命中一筆組合商品，會回傳 400 product_type_conflict，不會誤新增或誤更新到那筆組合商品；**規格（SKU）**的建立與批次端點若 productId 指向一筆組合商品，回傳的則是另一組英文散文句代碼（bundle product cannot receive SKUs through this API／bundle SKU cannot be updated through this API），不是 product_type_conflict——兩個家族的失敗代碼不同，請分別比對。
POST /v1/skus/stock/batch 新增一種逐筆失敗（breaking change）
skuId 指向組合品型別規格的那一筆，改版前回傳 ok 並靜默覆寫 inventoryQty；改版後回傳 failed，error 帶 bundle SKU stock cannot be set through this API，這顆規格的庫存不會被寫入。⚠️ 這是本次唯一一個影響既有上線端點的行為變更：如果貴端把批次回應裡任一筆 failed 當成整批失敗處理，第一次推送清單裡出現組合品規格序號時，就會開始持續回報庫存同步失敗。升級前請先確認例行同步的清單裡是否含有組合品的規格序號。