> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.orderupb2b.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.orderupb2b.com/_mcp/server.

# 批次更新後台使用者

PUT https://api.example.com/v1/internal-users/batch
Content-Type: application/json

批次更新多位後台使用者，逐筆結果互不影響。每一筆有 `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` 裡，單筆失敗不會讓其他筆一起失敗。

Reference: https://docs.orderupb2b.com/api-規格/internal-users/batch-update-internal-users

## Authentication

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

## Request

### Body (application/json)

This endpoint expects a list of InternalUserBatchUpdateRequest.

- `list of InternalUserBatchUpdateRequest`

## Response

### 200

OK

- `items` (list of BatchItemResult, optional, nullable) — 逐筆的處理結果，順序與送出的陣列相同，一筆對一筆。

## Errors

### 400 Bad Request Error

Bad Request

- `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。

### 401 Unauthorized Error

Unauthorized

- `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。

### 403 Forbidden Error

Forbidden

- `error` (string, optional, nullable) — 錯誤代碼，固定為 snake_case 字串，依代碼判斷失敗原因。

### 500 Internal Server Error

Internal Server Error

- `code` (string, optional, nullable) — 錯誤代碼字串。
- `message` (string, optional, nullable) — 對應的錯誤說明文字。

## Types

### InternalUserBatchUpdateRequest

PUT /v1/internal-users/batch 陣列中的一筆。只更新、不新增：有 `id` 就用 `id` 找出要更新的使用者，沒有 `id` 才用 `outerSysCode`（兩者都沒給，該筆失敗），其餘欄位與 PUT /v1/internal-users/\{id} 相同，是部分合併，省略的欄位維持原值。沒有 account 欄位，帳號一旦建立就不能改。

- `id` (long, optional, nullable) — 鍵：要更新的後台使用者序號，優先於 `outerSysCode`。帶了 `id` 時一律以它找人，同時帶的 `outerSysCode` 會被寫入成新代碼。不存在或屬於其他租戶時，該筆失敗並帶 not_found，不會改用 `outerSysCode` 找人。`id` 與 `outerSysCode` 都沒給回傳 key_required。
- `outerSysCode` (string, optional, nullable) — ERP 端的使用者代碼，依是否帶 `id` 有兩種用途。 沒帶 `id`：用來找人的鍵，不會被改寫。前後空白會被忽略，之後做大小寫敏感的完全比對；只有空白視為沒給。查無或屬於其他租戶回傳 not\_found（對不到任何使用者的代碼，包含長度超過 50 字元的，一律是 not\_found）；同租戶內有兩位以上的使用者用同一個代碼，該筆失敗並帶 ambiguous\_outer\_sys\_code，不會更新其中任何一位。 有帶 `id`：要寫入的新代碼。前後空白會被去除；只有空白代表清空代碼；省略保留現有值。長度上限 50 字元，超過回傳 outer\_sys\_code\_too\_long。和 PUT /v1/internal-users/\{id} 一樣不檢查是否與其他使用者重複。
- `name` (string, optional, nullable) — 姓名。省略保留現有值。長度上限 30 字元，超過回傳 name_too_long。
- `email` (string, optional, nullable) — 電子郵件。省略保留現有值。長度上限 100 字元，超過回傳 email_too_long。
- `password` (string, optional, nullable) — 登入密碼。省略表示不改密碼，這是保留原密碼的唯一方式。
- `roleId` (long, optional, nullable) — 角色序號。省略保留現有角色；帶入時必須指向呼叫端所屬租戶的既有角色，否則該筆失敗並帶 invalid_role_id。改變這個欄位會立即讓該使用者既有的登入階段失效。
- `status` (string, optional, nullable) — 帳號狀態，只接受 Active 或 Inactive（大小寫不敏感），其他值該筆失敗並帶 invalid_status。省略保留現有狀態；設為 Inactive 會立即讓該使用者既有的登入階段失效。

### BatchItemResult

批次陣列中每一筆的處理結果，依原始索引一筆對一筆回報，方便比對是哪一筆成功、哪一筆失敗。

- `index` (integer, optional) — 這一筆在原始批次陣列中的索引位置（從 0 起算），用來比對是哪一筆。
- `status` (string, optional, nullable) — 這一筆的結果。created=新增、updated=更新、failed=失敗（原因見 errors）。
- `id` (long, optional, nullable) — 新增或更新成功時，這一筆資料的 id；`ids` 有多個時是其中第一個。失敗時為 null。
- `ids` (list of long, optional, nullable) — 這一筆新增或更新的所有資料 id，由小到大。幾乎都只有一個，與 `id` 相同；只有規格批次（POST /v1/skus/batch）只帶料號時，一筆可能同時更新同一料號的多顆規格，這裡會全部列出。失敗時為空陣列。
- `errors` (list of string, optional, nullable) — 失敗時的錯誤訊息，目前永遠只有一則；成功時為空陣列。雖然是陣列形狀，仍建議把它當「可能有多則」的陣列處理，不要假設長度一定是 1。

## Examples

**Request**

```json
[
  {}
]
```

**Response**

```json
{
  "items": [
    {
      "index": 1,
      "status": "string",
      "id": 1,
      "ids": [
        1
      ],
      "errors": [
        "string"
      ]
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.example.com/v1/internal-users/batch"

payload = [{}]
headers = {
    "X-Signature": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.example.com/v1/internal-users/batch';
const options = {
  method: 'PUT',
  headers: {'X-Signature': '<apiKey>', 'Content-Type': 'application/json'},
  body: '[{}]'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/internal-users/batch"

	payload := strings.NewReader("[\n  {}\n]")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("X-Signature", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/internal-users/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["X-Signature"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {}\n]"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.example.com/v1/internal-users/batch")
  .header("X-Signature", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("[\n  {}\n]")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.example.com/v1/internal-users/batch', [
  'body' => '[
  {}
]',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-Signature' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.example.com/v1/internal-users/batch");
var request = new RestRequest(Method.PUT);
request.AddHeader("X-Signature", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {}\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-Signature": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [[]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.example.com/v1/internal-users/batch")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```