批次同步客戶點數額度
批次覆蓋多個客戶的點數額度,逐筆結果互不影響。
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
每個 /v1 請求都必須帶 X-Client-Id、X-Timestamp、X-Nonce 與 X-Signature 四個標頭。X-Signature 是以 client secret 對 canonical string 做 HMAC-SHA256 後的 Base64。
canonical string 的組成、可複製的簽章範例與 401 排查步驟,請參閱「驗證與簽章」。
Request
客戶序號,與 companyCode 擇一,兩者都有值時以這個欄位為準。
貴端的客戶代碼,即 outerSysCode。companyId 省略時才會用到;查無對應客戶回 company_not_found,對到多筆回 company_code_ambiguous,OrderUp 不會替你挑一筆。
這個客戶當下的絕對點數餘額,不是增減量。必填——省略會讓整筆失敗並帶 missing_balance,不是保留既有值也不是歸零,避免只想改 enabled 或 memo 的呼叫不小心把餘額清空。必須大於或等於 0,負值回 invalid_balance;顯式送 0 合法。
是否納入額度管控。可省略:更新時保留既有值,新增時預設 true。⚠️ 寫入後會被查詢端點原樣回報,但目前不會影響下單時的點數卡控,詳見批次同步端點的說明。
備註。可省略:更新時保留既有值,新增時預設空字串。長度上限 200 字元,超過整筆失敗並帶 invalid_memo。
Response
逐筆的處理結果,順序與送出的陣列相同,一筆對一筆。