批次同步客戶點數額度

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,與商品、規格批次端點的 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 排查步驟,請參閱「驗證與簽章」。

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