批次 API
逐筆結果放在回應 body 裡,以及不可混用的狀態字典與回應形狀
客戶、商品、規格(SKU)、庫存、組合品、規格價格、組合品價格、點數額度、合約額度、後台使用者各自提供批次 API,讓你一次寫入多筆資料,不必逐筆呼叫單筆端點。十支批次 API共用同一套「先擋空批次、受理後一律 200、逐筆各自回報成功或失敗」的模型,但逐筆結果的狀態字典與欄位形狀分成好幾組,混用會直接讓你的解析邏輯出錯——這是本頁的重點。
空陣列或沒有 body 會先被拒絕
送出空陣列 [],或請求完全沒有 body,會在受理前就被直接擋下,回傳 400 empty_batch。這個檢查發生在「受理」這個動作之前——被擋下的請求不算數,不會出現在下一節「一律 200」的規則裡。
十支批次 API都遵守同一條規則:
POST /v1/companies/batchPOST /v1/products/batchPOST /v1/skus/batchPOST /v1/skus/stock/batchPOST /v1/bundles/batchPUT /v1/prices/batchPUT /v1/bundle-prices/batchPOST /v1/companies/point-quota/batchPOST /v1/companies/credit-quota/batchPUT /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的逐筆結果分成三種欄位形狀,對應兩套狀態字典:
三態字典:created/updated/failed
客戶、商品、規格、組合品四支批次 API,逐筆結果的 status 只有三種小寫值:
index 是這一筆在送出陣列中的位置(從 0 起算);id 在成功時是新增或更新後的資料 id,失敗時是 null;errors 目前失敗時永遠只有一則,成功時是空陣列——但仍建議把它當「可能有多則」的陣列處理,不要在你端寫死長度一定是 1。
ids 列出這一筆新增或更新的所有資料 id(由小到大),失敗時是空陣列。幾乎都只有一個、與 id 相同;只有規格與組合品的批次(POST /v1/skus/batch、POST /v1/bundles/batch)只帶料號時,一筆可能同時更新同一料號的多顆規格:
此時 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 定位時可以藉此把序號存回你的系統。可能的失敗原因見「錯誤碼」。
二態字典:ok/failed,但有兩種不同形狀
庫存、點數額度、合約額度三支批次 API都用 ok/failed 這套二態字典,沒有 created/updated 的區分——因為三者的寫入都是覆蓋(絕對值快照),不是新增。但識別欄位不一樣,不能假設 ok/failed 一定對應同一個形狀:
上面的請求送了三筆:skuId 1、料號 ERP-S-0004(放在兩個商品底下)、料號 ERP-S-0099(不存在)。
庫存批次用 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。
這條規則只影響「同一筆資料剛好同時觸發兩個問題」時你會先看到哪一個代碼;分開來看,每個代碼各自的觸發條件不受影響。