Skip to navigation

批次 API

逐筆結果放在回應 body 裡,以及不可混用的狀態字典與回應形狀

View as Markdown

客戶、商品、規格(SKU)、庫存、組合品、規格價格、組合品價格、點數額度、合約額度、後台使用者各自提供批次 API,讓你一次寫入多筆資料,不必逐筆呼叫單筆端點。十支批次 API共用同一套「先擋空批次、受理後一律 200、逐筆各自回報成功或失敗」的模型,但逐筆結果的狀態字典與欄位形狀分成好幾組,混用會直接讓你的解析邏輯出錯——這是本頁的重點。

空陣列或沒有 body 會先被拒絕

送出空陣列 [],或請求完全沒有 body,會在受理前就被直接擋下,回傳 400 empty_batch。這個檢查發生在「受理」這個動作之前——被擋下的請求不算數,不會出現在下一節「一律 200」的規則裡。

十支批次 API都遵守同一條規則:

  • POST /v1/companies/batch
  • POST /v1/products/batch
  • POST /v1/skus/batch
  • POST /v1/skus/stock/batch
  • POST /v1/bundles/batch
  • PUT /v1/prices/batch
  • PUT /v1/bundle-prices/batch
  • POST /v1/companies/point-quota/batch
  • POST /v1/companies/credit-quota/batch
  • PUT /v1/internal-users/batch

已受理的請求一律回傳 HTTP 200

只要陣列不是空的,這個請求就算已受理——批次 API永遠回傳 HTTP 200,即使陣列裡有一筆、甚至全部都處理失敗。逐筆的處理結果放在回應 body 的 items 裡,順序與送出的陣列相同;一筆失敗不會讓其他筆一起失敗,也不會讓整個請求失敗或改變外層的 HTTP 狀態碼。

201、404、409 這三個狀態碼只會出現在單筆端點(例如 POST /v1/companies、PUT /v1/products/{id}、PUT /v1/internal-users/{id})。批次 API不會回傳它們——批次 API對應的成功或失敗結果,一律藏在 200 回應的 items 裡,不會反映在 HTTP 狀態碼上。判斷批次裡某一筆有沒有成功,永遠是看那一筆的 status,不是看外層的 HTTP 狀態碼。

狀態字典與回應形狀,不可混用

批次 API的逐筆結果分成三種欄位形狀,對應兩套狀態字典:

端點方法狀態字典識別欄位錯誤欄位
/v1/companies/batchPOSTcreated/updated/failedindex(id 為新增或更新後的資料 id)errors(陣列)
/v1/products/batchPOSTcreated/updated/failedindexerrors(陣列)
/v1/skus/batchPOSTcreated/updated/failedindex(ids 可能有多個)errors(陣列)
/v1/bundles/batchPOSTcreated/updated/failedindex(ids 可能有多個)errors(陣列)
/v1/prices/batchPUTupdated/failed(不會是 created)index(id 為送出的 skuId)errors(陣列)
/v1/bundle-prices/batchPUTupdated/failed(不會是 created)index(id 為送出的 bundleId)errors(陣列)
/v1/internal-users/batchPUTupdated/failed(不會是 created)index(id 為實際被更新的使用者序號)errors(陣列)
/v1/skus/stock/batchPOSTok/failedskuId(另回傳 outerSysCode;一顆規格一列)error(字串或 null)
/v1/companies/point-quota/batchPOSTok/failedindex(另回傳 companyCode)error(字串或 null)
/v1/companies/credit-quota/batchPOSTok/failedindex(另回傳 companyCode)error(字串或 null)

三態字典:created/updated/failed

客戶、商品、規格、組合品四支批次 API,逐筆結果的 status 只有三種小寫值:

status意義
created這一筆新增成功
updated這一筆更新成功——依 id 直接更新,或依 outerSysCode 去重更新,判斷規則見「Upsert 與冪等」
failed這一筆失敗,原因在 errors 裡
POST /v1/products/batch 的回應
{
"items": [
{ "index": 0, "status": "created", "id": 101, "ids": [101], "errors": [] },
{ "index": 1, "status": "updated", "id": 42, "ids": [42], "errors": [] },
{ "index": 2, "status": "failed", "id": null, "ids": [], "errors": ["invalid_product_category_id"] }
]
}

index 是這一筆在送出陣列中的位置(從 0 起算);id 在成功時是新增或更新後的資料 id,失敗時是 null;errors 目前失敗時永遠只有一則,成功時是空陣列——但仍建議把它當「可能有多則」的陣列處理,不要在你端寫死長度一定是 1。

ids 列出這一筆新增或更新的所有資料 id(由小到大),失敗時是空陣列。幾乎都只有一個、與 id 相同;只有規格與組合品的批次(POST /v1/skus/batch、POST /v1/bundles/batch)只帶料號時,一筆可能同時更新同一料號的多顆規格:

POST /v1/skus/batch 的回應:料號 ERP-S-0004 放在兩個商品底下
{
"items": [
{ "index": 0, "status": "created", "id": 5001, "ids": [5001], "errors": [] },
{ "index": 1, "status": "updated", "id": 11, "ids": [11, 12], "errors": [] }
]
}

此時 id 是其中第一個。要把序號存回你的系統,請用 ids。組合品批次的 id/ids 都是組合 SKU 序號,可以直接拿去查詢或更新組合品價格。

同一種形狀,狀態範圍縮小為:updated/failed

PUT /v1/prices/batch、PUT /v1/bundle-prices/batch 用的是跟上面完全相同的回應形狀(index/status/id/ids/errors),可以套用同一支解析器,但 status 永遠不會是 created——這兩支端點只更新規格或組合品上既有的 price/sellPrice 欄位,skuId/bundleId 找不到對應資料時這一筆直接 failed(not_found),不會退回新增一筆。id 回傳的是你這一筆送出的 skuId(規格價格)或 bundleId(組合品價格,組合 SKU 序號),方便核對是哪一筆。

PUT /v1/internal-users/batch 也用這個形狀(index/status/id/ids/errors),status 同樣只會是 updated 或 failed,不會是 created:每一筆有 id 就用 id、沒有 id 才用 outerSysCode 找出要更新的後台使用者(兩者都帶時,outerSysCode 會被寫入成新代碼),找不到時該筆 failed(not_found),不會建立新使用者。id 回傳的是實際被更新的使用者序號,用 outerSysCode 定位時可以藉此把序號存回你的系統。可能的失敗原因見「錯誤碼」。

PUT /v1/prices/batch 的回應
{
"items": [
{ "index": 0, "status": "updated", "id": 501, "ids": [501], "errors": [] },
{ "index": 1, "status": "failed", "id": null, "ids": [], "errors": ["not_found"] }
]
}

二態字典:ok/failed,但有兩種不同形狀

庫存、點數額度、合約額度三支批次 API都用 ok/failed 這套二態字典,沒有 created/updated 的區分——因為三者的寫入都是覆蓋(絕對值快照),不是新增。但識別欄位不一樣,不能假設 ok/failed 一定對應同一個形狀:

POST /v1/skus/stock/batch 的回應
{
"items": [
{ "skuId": 1, "outerSysCode": null, "status": "ok", "error": null },
{ "skuId": 11, "outerSysCode": "ERP-S-0004", "status": "ok", "error": null },
{ "skuId": 12, "outerSysCode": "ERP-S-0004", "status": "ok", "error": null },
{ "skuId": null, "outerSysCode": "ERP-S-0099", "status": "failed", "error": "SKU not found" }
]
}

上面的請求送了三筆:skuId 1、料號 ERP-S-0004(放在兩個商品底下)、料號 ERP-S-0099(不存在)。

POST /v1/companies/point-quota/batch 的回應
{
"items": [
{ "index": 0, "companyCode": "ERP-C-1001", "status": "ok", "error": null },
{ "index": 1, "companyCode": "ERP-C-9999", "status": "failed", "error": "company_not_found" }
]
}

庫存批次用 skuId 識別這一列是哪個規格,沒有 index。⚠️ 庫存批次是一顆規格一列:用料號命中多顆規格時每一顆各回一列,依規格序號排在一起並帶回該筆的 outerSysCode;料號找不到時回一列 failed,skuId 為 null。回應列數可能多於請求筆數,請用 skuId 或 outerSysCode 對回原始請求。點數額度與合約額度批次用 index(原始陣列中的位置)識別,並附帶原樣回傳的 companyCode 方便核對——因為額度批次可能整批改用 companyId 指定客戶,companyCode 不是穩定的識別鍵,只能靠 index 對回原始請求。三者的錯誤欄位都是 error(單一字串或 null),這點與 created/updated/failed 家族的 errors(陣列)不同。

一支共用的批次結果解析器至少要處理三種形狀:index+errors(陣列;三態,或縮小值域後的二態 updated/failed)、skuId+outerSysCode+error(字串;庫存,一顆規格一列)、index+companyCode+error(字串;點數/合約額度)。狀態字典相同(例如都用 ok/failed)不代表欄位形狀也相同。

驗證順序:一筆資料同時觸發多個問題時,看哪一個先擋下

額度批次(POST /v1/companies/point-quota/batch、POST /v1/companies/credit-quota/batch)與規格價格批次(PUT /v1/prices/batch、PUT /v1/bundle-prices/batch 同理)都是先檢查金額欄位本身合不合法,才去反查客戶或規格是否存在——不是反過來。

具體來說:點數額度批次會先擋 missing_balance/invalid_balance/invalid_memo,合約額度批次會先擋 missing_credit_limit/invalid_credit_limit/invalid_memo,之後才嘗試用 companyId/companyCode 找出對應客戶。一筆資料如果同時沒帶必填的金額欄位、companyCode 又查無此人,回應的是 missing_balance/missing_credit_limit,不是 company_not_found——先修欄位本身的問題,companyCode 打錯這件事還輪不到被回報。PUT /v1/prices/batch、PUT /v1/bundle-prices/batch 是同樣的順序:invalid_price 排在 not_found 之前,price/sellPrice 超出範圍、skuId/bundleId 又查無資料時,回的是 invalid_price。

這條規則只影響「同一筆資料剛好同時觸發兩個問題」時你會先看到哪一個代碼;分開來看,每個代碼各自的觸發條件不受影響。

下一步