Upsert 與冪等
新增、更新、去重的判斷規則
客戶、商品、規格(SKU)、組合品的建立端點都是同一套 upsert 規則:同一支端點,依你送出的欄位自動判斷這一筆該新增、更新,還是去重成更新既有的一筆。目的是讓 ERP 端可以重複推送同一份資料而不會產生重複紀錄,即使中途重試也一樣安全。
三條判斷規則
依序判斷:
- body 帶
id—— 一律視為更新該筆,直接依id找到那筆資料並更新,不會再去比對outerSysCode。 - body 沒帶
id,但outerSysCode命中既有資料 —— 改為更新命中的那一筆(這就是「冪等去重」:同一份outerSysCode重送多次,只會更新同一筆,不會越送越多筆)。 - 兩者都沒有命中 —— 新增一筆。
客戶與商品的 outerSysCode 比對範圍是整個租戶;規格與組合品的比對範圍則看有沒有帶 productId,見下方「規格與組合品:以料號為主」。
批次 API(/v1/companies/batch、/v1/products/batch、/v1/skus/batch、/v1/bundles/batch)逐筆套用同一套規則,一筆一筆各自判斷新增或更新,互不影響;哪一筆成功、哪一筆失敗、是新增還是更新,都會在回應的逐筆結果裡分別回報。
三個分支各自長什麼樣子
以 POST /v1/companies 為例,假設 id=501、outerSysCode="ERP-C-1001" 的客戶已經存在:
分支 1 與分支 2 的差別只在有沒有帶 id——兩者最終都會落到「更新 501」,但走的是不同的判斷路徑;重送分支 2 的 body 一百次,也只會有一筆 id=501 的客戶被反覆更新,不會變成一百筆客戶。
規格與組合品:以料號為主
規格(SKU)與組合品不一定要屬於商品,所以第 2 條的比對範圍取決於有沒有帶 productId:
- 帶了非 0 的
productId:只比對這個商品底下同料號(outerSysCode)的規格。不同商品下的相同料號是不同的規格,不會互相匹配。找不到就在這個商品底下新增。 - 只帶料號(
productId省略或帶 0):在整個租戶內比對料號(去除前後空白、不分大小寫)。同一個料號可能放在好幾個商品底下,這一筆會更新每一顆同料號的規格,而且不會改動它們所屬的商品;找不到才新增一顆未加入商品的規格。回應的ids列出所有被更新的規格,id是其中第一顆。
所以只管料號、不知道商品的 ERP,每次都可以只送料號(或固定送 "productId": 0)重複推送:第一次新增,之後都是更新。組合品(/v1/bundles)用的是同一套規則,只是比對的對象換成組合 SKU。
一般規格與組合 SKU 不會互相轉換。/v1/skus 的料號只屬於組合 SKU 時回 400 outerSysCode belongs to a bundle SKU; use /v1/bundles,在指定商品下命中組合 SKU 時回 400 bundle SKU cannot be updated through this API;反過來,/v1/bundles 的料號屬於一般規格時回 400 product_type_conflict。這幾種情況都不會改為新增,完整對照見「錯誤碼」。
依 id 指定的更新(PUT /v1/skus/{id}、PUT /v1/bundles/{id},或批次項目帶 id)不能帶 "productId": 0:更新不會把規格移出商品,要保留所屬商品就不要送這個欄位。沒有 id 的項目帶 0 則與省略相同。
部分合併:省略的欄位永遠不會被清空
更新(不管是依 id 直接更新,還是依 outerSysCode 去重出來的更新)一律是部分合併:只有你實際送出的欄位會被寫入,省略的欄位維持原本的值。 這代表:
- 只想改一個欄位時,body 裡只需要放那一個欄位,不需要把整筆資料重新送一次。
- 省略某個欄位不會把它清空或重設成預設值——例如更新客戶時只送
shippingAddress,客戶原本的name、shortName、cellPhone都會維持不變。 - 這條規則只適用於更新。新增時省略字串欄位視為空字串,省略數字欄位(例如規格的
price、sellPrice、quantityPrecision)視為 0,因為新增沒有「原本的值」可以保留。
實際看一次:客戶 id=501 目前長這樣——
只送 cellPhone 這一個欄位去更新:
更新後再查一次,只有 cellPhone 變了,其餘欄位(包含沒有出現在請求裡的 name、shortName、shippingAddress、internalUserId)原封不動:
status 不受這條規則影響,因為它本來就不是 upsert 請求裡的欄位——透過本 API 建立的客戶一律是 Active,狀態變更由後台維護。
PUT /{id}:路徑上的 id 永遠優先
PUT /v1/companies/{id}、PUT /v1/products/{id}、PUT /v1/skus/{id}、PUT /v1/bundles/{id} 這四支路徑帶 id 的更新端點,路徑上的 id 永遠優先於 body 裡的 id——即使 body 另外指定了一個不同的 id,也一律以路徑上的為準,body 裡的 id 會被忽略。這是為了避免呼叫端不小心把更新導向另一筆資料:路徑已經明確表示「要更新哪一筆」,body 的 id 沒有機會覆蓋這個意圖。
這筆請求更新的是路徑上的 501,body 裡的 999 完全被忽略——不會去更新 id=999 那筆,也不會因為 999 不存在而報錯。回應裡的 id 也會是 501。