Skip to navigation

Upsert 與冪等

新增、更新、去重的判斷規則

View as Markdown

客戶、商品、規格(SKU)、組合品的建立端點都是同一套 upsert 規則:同一支端點,依你送出的欄位自動判斷這一筆該新增、更新,還是去重成更新既有的一筆。目的是讓 ERP 端可以重複推送同一份資料而不會產生重複紀錄,即使中途重試也一樣安全。

三條判斷規則

依序判斷:

  1. body 帶 id —— 一律視為更新該筆,直接依 id 找到那筆資料並更新,不會再去比對 outerSysCode。
  2. body 沒帶 id,但 outerSysCode 命中既有資料 —— 改為更新命中的那一筆(這就是「冪等去重」:同一份 outerSysCode 重送多次,只會更新同一筆,不會越送越多筆)。
  3. 兩者都沒有命中 —— 新增一筆。

客戶與商品的 outerSysCode 比對範圍是整個租戶;規格與組合品的比對範圍則看有沒有帶 productId,見下方「規格與組合品:以料號為主」。

批次 API(/v1/companies/batch、/v1/products/batch、/v1/skus/batch、/v1/bundles/batch)逐筆套用同一套規則,一筆一筆各自判斷新增或更新,互不影響;哪一筆成功、哪一筆失敗、是新增還是更新,都會在回應的逐筆結果裡分別回報。

三個分支各自長什麼樣子

以 POST /v1/companies 為例,假設 id=501、outerSysCode="ERP-C-1001" 的客戶已經存在:

分支送出的 body結果
1. 帶 id{ "id": 501, "cellPhone": "02-2345-6789" }更新 id=501 那筆,不比對 outerSysCode
2. 不帶 id,outerSysCode 命中{ "outerSysCode": "ERP-C-1001", "cellPhone": "02-2345-6789" }ERP-C-1001 已存在(就是 501),改為更新 501
3. 都沒命中{ "outerSysCode": "ERP-C-2002", "name": "新客戶股份有限公司" }ERP-C-2002 不存在,新增一筆新客戶

分支 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 目前長這樣——

更新前:GET /v1/companies/501
{
"id": 501,
"outerSysCode": "ERP-C-1001",
"name": "測試客戶股份有限公司",
"shortName": "測試客戶",
"cellPhone": "02-1234-5678",
"shippingAddress": "台北市信義區松高路1號",
"internalUserId": 12,
"status": "Active"
}

只送 cellPhone 這一個欄位去更新:

PUT /v1/companies/501
{
"cellPhone": "02-2345-6789"
}

更新後再查一次,只有 cellPhone 變了,其餘欄位(包含沒有出現在請求裡的 name、shortName、shippingAddress、internalUserId)原封不動:

更新後:再次 GET /v1/companies/501
{
"id": 501,
"outerSysCode": "ERP-C-1001",
"name": "測試客戶股份有限公司",
"shortName": "測試客戶",
"cellPhone": "02-2345-6789",
"shippingAddress": "台北市信義區松高路1號",
"internalUserId": 12,
"status": "Active"
}

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 沒有機會覆蓋這個意圖。

PUT /v1/companies/501
{
"id": 999,
"cellPhone": "02-2345-6789"
}

這筆請求更新的是路徑上的 501,body 裡的 999 完全被忽略——不會去更新 id=999 那筆,也不會因為 999 不存在而報錯。回應裡的 id 也會是 501。