批次同步客戶點數額度

View as Markdown
批次覆蓋多個客戶的點數額度,逐筆結果互不影響。 `balance` 是絕對餘額,不是增減量,而且必填——省略會讓該筆失敗並帶 missing_balance,不會被視為保留現值,也不會被序列化的預設值 0 悄悄歸零;顯式送 0 合法,會把餘額真的歸零。負值一律失敗並帶 invalid_balance。 `enabled`、`memo` 則相反,是可省略的局部更新欄位:省略即更新時保留既有值、新增時套用預設值(`enabled` 預設 true、`memo` 預設空字串);`memo` 超過 200 字元整筆失敗並帶 invalid_memo。 客戶用 `companyId`(OrderUp 內部序號)或既有的 `companyCode`(貴端代碼,即 outerSysCode)擇一指定,兩者都有值時以 `companyId` 為準;兩者都沒給、或 `companyCode` 是空字串,整筆失敗並帶 missing_key;`companyCode` 反查不到客戶回 company_not_found,反查到一筆以上回 company_code_ambiguous——OrderUp 絕不會替你在多筆命中裡挑一筆,挑錯等於把甲客戶的點數寫到乙客戶頭上。 送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆結果放在回應 body 的 `items` 裡,用 `index`(這一筆在原始陣列中的位置)比對是哪一筆,而不是 `companyCode`——絕對值覆寫的批次沒有天然的識別鍵可以對回原始請求,`companyCode` 可能重複,也可能整批改用 `companyId`。逐筆狀態是小寫的 ok 或 failed,與商品、規格批次 API 的 created、updated、failed 不同。 ⚠️ **`enabled` 寫入後會被查詢端點原樣回報,但不會影響下單時的點數卡控**——下單期真正檢查的是餘額是否足夠,不會讀這個欄位;把它設成 false 不會讓這個客戶的點數變成無上限,這是目前刻意保留的現狀。

Authentication

X-Signaturestring
每個 /v1 請求都必須帶 `X-Client-Id`、`X-Timestamp`、`X-Nonce` 與 `X-Signature` 四個標頭。`X-Signature` 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。 canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱[「驗證與簽章」](/authentication)。

Request

This endpoint expects a list of objects.
companyIdlong or nullOptional

客戶序號,與 companyCode 擇一,兩者都有值時以這個欄位為準。

companyCodestring or nullOptional

貴端的客戶代碼,即 outerSysCode。companyId 省略時才會用到;查無對應客戶回 company_not_found,對到多筆回 company_code_ambiguous,OrderUp 不會替你挑一筆。

balancedouble or nullOptional

這個客戶當下的絕對點數餘額,不是增減量。必填——省略會讓整筆失敗並帶 missing_balance,不是保留既有值也不是歸零,避免只想改 enabled 或 memo 的呼叫不小心把餘額清空。必須大於或等於 0,負值回 invalid_balance;顯式送 0 合法。

enabledboolean or nullOptional

是否納入額度管控。可省略:更新時保留既有值,新增時預設 true。⚠️ 寫入後會被查詢端點原樣回報,但目前不會影響下單時的點數卡控,詳見批次同步端點的說明。

memostring or nullOptional

備註。可省略:更新時保留既有值,新增時預設空字串。長度上限 200 字元,超過整筆失敗並帶 invalid_memo。

Response

OK
itemslist of objects or nullOptional

逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error