Skip to navigation

批次更新後台使用者

View as Markdown

批次更新多位後台使用者,逐筆結果互不影響。每一筆有 id 就用 id 指出要更新哪一位使用者,沒有 id 才用 outerSysCode,其餘欄位(name、email、password、roleId、status)與 PUT /v1/internal-users/{id} 相同,都是部分合併——省略的欄位維持原值。

兩個鍵都沒給(或沒有 id 且 outerSysCode 只有空白)該筆失敗並帶 key_required。用 outerSysCode 找人時,前後空白會被忽略,之後做大小寫敏感的完全比對(ABC 與 abc 是不同的代碼);查無,或屬於其他租戶,一律帶 not_found,兩種情況無法區分。outerSysCode 沒有唯一性限制,同租戶內若有兩位以上的使用者用同一個代碼,該筆失敗並帶 ambiguous_outer_sys_code,兩位都不會被更新——請先用 GET /v1/internal-users 查出重複的使用者,改用 id 指定,或先修正資料。

⚠️ 只更新、不新增:這支端點不會建立使用者,逐筆狀態一律是 updated 或 failed,不會是 created;回傳的 id 是實際被更新的使用者序號,可以存回你的系統供日後直接使用。建立使用者請用 POST /v1/internal-users。

⚠️ 同時帶 id 與 outerSysCode 時,以 id 找人,outerSysCode 會被寫入成這位使用者的新代碼。 新代碼前後空白會被去除;只有空白代表清空代碼;要保留現有代碼請省略這個欄位。id 查無時該筆帶 not_found,不會改用 outerSysCode 找人。只帶 outerSysCode 時,它只是用來找人的鍵,不會被改寫。

改變 roleId,或把 status 設為 Inactive,會立即讓該使用者既有的登入階段失效。每一筆各自提交、不是整批交易,所以同一批裡較後面那筆的「唯一系統管理員」檢查,看得到前面幾筆已經寫入的結果;使用者若是租戶目前唯一還能登入的系統管理員,把他改成非管理員角色或設為 Inactive 的那一筆會失敗並帶 last_active_admin(在這支端點它出現在逐筆的 errors,外層仍是 HTTP 200)。欄位長度超限、status 不合法、roleId 不合法等錯誤,字串與 PUT /v1/internal-users/{id} 相同。

送出空陣列或沒有 body 會在受理前被拒絕,回傳 400 empty_batch;已受理的請求一律回傳 HTTP 200,逐筆的處理結果放在回應 body 的 items 裡,單筆失敗不會讓其他筆一起失敗。

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.
idlong or nullOptional

鍵:要更新的後台使用者序號,優先於 outerSysCode。帶了 id 時一律以它找人,同時帶的 outerSysCode 會被寫入成新代碼。不存在或屬於其他租戶時,該筆失敗並帶 not_found,不會改用 outerSysCode 找人。id 與 outerSysCode 都沒給回傳 key_required。

outerSysCodestring or nullOptional

ERP 端的使用者代碼,依是否帶 id 有兩種用途。

沒帶 id:用來找人的鍵,不會被改寫。前後空白會被忽略,之後做大小寫敏感的完全比對;只有空白視為沒給。查無或屬於其他租戶回傳 not_found(對不到任何使用者的代碼,包含長度超過 50 字元的,一律是 not_found);同租戶內有兩位以上的使用者用同一個代碼,該筆失敗並帶 ambiguous_outer_sys_code,不會更新其中任何一位。

有帶 id:要寫入的新代碼。前後空白會被去除;只有空白代表清空代碼;省略保留現有值。長度上限 50 字元,超過回傳 outer_sys_code_too_long。和 PUT /v1/internal-users/{id} 一樣不檢查是否與其他使用者重複。

namestring or nullOptional

姓名。省略保留現有值。長度上限 30 字元,超過回傳 name_too_long。

emailstring or nullOptional

電子郵件。省略保留現有值。長度上限 100 字元,超過回傳 email_too_long。

passwordstring or nullOptional

登入密碼。省略表示不改密碼,這是保留原密碼的唯一方式。

roleIdlong or nullOptional

角色序號。省略保留現有角色;帶入時必須指向呼叫端所屬租戶的既有角色,否則該筆失敗並帶 invalid_role_id。改變這個欄位會立即讓該使用者既有的登入階段失效。

statusstring or nullOptional

帳號狀態,只接受 Active 或 Inactive(大小寫不敏感),其他值該筆失敗並帶 invalid_status。省略保留現有狀態;設為 Inactive 會立即讓該使用者既有的登入階段失效。

Response

OK
itemslist of objects or nullOptional

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

Errors

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