> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/itp-guide/api/team-members.md).

# チームメンバー

チームへのユーザーの追加・削除、チーム内の役割の設定、チームメンバーの一覧を API で行えます。チーム自体の作成やシナリオの割り当ては「[チーム](https://docs.digitalhumans.jp/itp-guide/api/teams.md)」をご覧ください。

コード例の `BASE_URL`・`headers`・`API_KEY` は、「[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)」のコード例で定義したものです。

## エンドポイント一覧

| メソッド     | エンドポイント                                           | 内容                                                  |
| -------- | ------------------------------------------------- | --------------------------------------------------- |
| `POST`   | `/teams/{teamID}/users`                           | [チームにユーザーを追加する](#post-teams-teamid-users)           |
| `DELETE` | `/teams/{teamID}/users/{userID}`                  | [チームからユーザーを外す](#delete-teams-teamid-users-userid)   |
| `PUT`    | `/teams/{teamID}/users/{userID}/role`             | [チーム内の役割を設定する](#put-teams-teamid-users-userid-role) |
| `GET`    | `/teams/{teamID}/users/page/{page}/limit/{limit}` | [チームメンバーを一覧する](#get-teams-teamid-users-page)        |

すべてのエンドポイントは、APIキーが無効な場合に `401`（ボディは `error` キー）、レート制限を超えた場合に `429` を返します。詳しくは「[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)」「[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)」をご覧ください。

***

## チームにユーザーを追加する <a href="#post-teams-teamid-users" id="post-teams-teamid-users"></a>

1人以上のユーザーをチームに追加します。

```
POST /teams/{teamID}/users
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### リクエストボディ

```json
{
  "user_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f23456789012"
  ]
}
```

| フィールド      | 型               | 説明                  | 必須 |
| ---------- | --------------- | ------------------- | -- |
| `user_ids` | string\[]（UUID） | チームに追加するユーザー ID の一覧 | はい |

ユーザー ID は、[組織にユーザーを追加する](https://docs.digitalhumans.jp/itp-guide/api/users.md#post-users-add)のレスポンスの `results[].id`、または[組織のユーザーを一覧する](https://docs.digitalhumans.jp/itp-guide/api/users.md#get-users-page-page)で取得できます。

### レスポンス

| ステータス            | 内容                   |
| ---------------- | -------------------- |
| `204 No Content` | チームへの追加に成功。ボディはありません |
| `400`            | 不正なリクエスト             |
| `401`            | APIキーが無効             |
| `429`            | レート制限を超えた            |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/teams/{teamID}/users" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    f"{BASE_URL}/teams/{team_id}/users",
    headers=headers,
    json={"user_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]}
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/teams/${teamId}/users`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    user_ids: ['a1b2c3d4-e5f6-7890-abcd-ef1234567890']
  })
});
```

{% endtab %}
{% endtabs %}

***

## チームからユーザーを外す <a href="#delete-teams-teamid-users-userid" id="delete-teams-teamid-users-userid"></a>

ユーザーを1人、チームから外します。

```
DELETE /teams/{teamID}/users/{userID}
```

### パスパラメーター

| パラメーター   | 型            | 説明              |
| -------- | ------------ | --------------- |
| `teamID` | string（UUID） | チーム ID          |
| `userID` | string（UUID） | チームから外すユーザーの ID |

### レスポンス

| ステータス            | 内容                     |
| ---------------- | ---------------------- |
| `204 No Content` | チームから外すことに成功。ボディはありません |
| `401`            | APIキーが無効               |
| `404`            | 見つからない                 |
| `429`            | レート制限を超えた              |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X DELETE \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/teams/{teamID}/users/{userID}" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.delete(
    f"{BASE_URL}/teams/{team_id}/users/{user_id}",
    headers=headers
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/teams/${teamId}/users/${userId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
```

{% endtab %}
{% endtabs %}

***

## チーム内の役割を設定する <a href="#put-teams-teamid-users-userid-role" id="put-teams-teamid-users-userid-role"></a>

チーム内でのユーザーの役割を設定します。役割は `member`（通常のメンバー。既定値）または `manager`（チームマネージャー）です。チームマネージャーには、チームメンバーのアナリティクスを閲覧できるなど、追加の権限があります。

```
PUT /teams/{teamID}/users/{userID}/role
```

{% hint style="info" %}
ここで設定するのはチーム内の役割です。組織のロール（`MANAGER` など）とは別のものです。組織のロールは[ユーザーにロールを割り当てる](https://docs.digitalhumans.jp/itp-guide/api/users.md#post-users-roles-assign)で設定します。
{% endhint %}

### パスパラメーター

| パラメーター   | 型            | 説明      |
| -------- | ------------ | ------- |
| `teamID` | string（UUID） | チーム ID  |
| `userID` | string（UUID） | ユーザー ID |

### リクエストボディ

```json
{
  "role": "manager"
}
```

| フィールド  | 型      | 説明                            | 必須 |
| ------ | ------ | ----------------------------- | -- |
| `role` | string | 設定する役割。`member` または `manager` | はい |

### レスポンス

**204 No Content**: 役割の更新に成功しました。

### エラー

| コード   | 説明                                                                     |
| ----- | ---------------------------------------------------------------------- |
| `400` | 不正なリクエスト（役割の値が無い・正しくない、JSON ボディの形式が正しくない、`teamID`・`userID` が UUID でない） |
| `401` | APIキーが無効                                                               |
| `429` | レート制限を超えた                                                              |
| `500` | ユーザーがチームのメンバーではない                                                      |

{% hint style="info" %}
**先にユーザーをチームに追加してください。**\
まだチームに所属していないユーザーに役割を設定すると、`500` とボディ `{"message": "unable to updates a requested team"}` が返ります。[チームにユーザーを追加する](#post-teams-teamid-users)で追加してから、役割を設定してください。ユーザーを追加しないまま同じリクエストを繰り返しても、同じレスポンスが返ります。
{% endhint %}

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X PUT \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/teams/{teamID}/users/{userID}/role" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"role": "manager"}'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.put(
    f"{BASE_URL}/teams/{team_id}/users/{user_id}/role",
    headers=headers,
    json={"role": "manager"}
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/teams/${teamId}/users/${userId}/role`, {
  method: 'PUT',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ role: 'manager' })
});
```

{% endtab %}
{% endtabs %}

***

## チームメンバーを一覧する <a href="#get-teams-teamid-users-page" id="get-teams-teamid-users-page"></a>

チームのユーザーをページ単位で取得します。

```
GET /teams/{teamID}/users/page/{page}/limit/{limit}
```

### パスパラメーター

| パラメーター   | 型            | 説明                |
| -------- | ------------ | ----------------- |
| `teamID` | string（UUID） | チーム ID            |
| `page`   | integer      | ページ番号（1から始まる）     |
| `limit`  | integer      | 1ページあたりの件数（1〜100） |

### クエリパラメーター

| パラメーター        | 型      | 説明                                                                                                                                            |
| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `search`      | string | 検索語でメンバーを絞り込む                                                                                                                                 |
| `user_roles`  | string | 組織のロールで絞り込む（カンマ区切り。例: `USER,MANAGER`）                                                                                                         |
| `user_status` | string | 状態で絞り込む（カンマ区切り）。値は `active`、`inactive`、`invited`、`expired`（例: `active,inactive`）。このエンドポイントは状態として `expired` を返さないため、`expired` での絞り込みは使わないでください |

### レスポンス

**200 OK**

```json
{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "roles": ["USER"],
      "organization_roles": null,
      "status": "active",
      "team_role": "manager"
    }
  ],
  "records": 8
}
```

| フィールド                        | 型               | 説明                                                                            |
| ---------------------------- | --------------- | ----------------------------------------------------------------------------- |
| `users[].id`                 | string（UUID）    | ユーザー ID                                                                       |
| `users[].email`              | string          | メールアドレス                                                                       |
| `users[].name`               | string または null | 表示名。まだ名前を設定していないユーザーは `null`                                                  |
| `users[].roles`              | string\[]       | 組織で割り当てられたロール                                                                 |
| `users[].organization_roles` | null            | このエンドポイントでは `null` が返ります。`roles` を読んでください                                     |
| `users[].status`             | string          | `active`、`inactive`、`invited` のいずれか                                           |
| `users[].team_role`          | string          | このチーム内での役割。`member`（通常のメンバー）または `manager`（チームマネージャー）。チームメンバーの一覧のレスポンスにだけ含まれます |
| `records`                    | integer         | 条件に一致したメンバーの総数                                                                |

{% hint style="info" %}
**このエンドポイントが返す状態について**\
メンバーの状態は保存されている値のまま返されるため、有効期限を過ぎた招待も `invited` と表示されます。[組織のユーザーを一覧する](https://docs.digitalhumans.jp/itp-guide/api/users.md#get-users-page-page)では、同じメンバーが `expired` と表示されます。有効期限切れを状態に反映させたい場合は、そちらのエンドポイントを使ってください。
{% endhint %}

| ステータス | 内容        |
| ----- | --------- |
| `200` | 成功        |
| `401` | APIキーが無効  |
| `429` | レート制限を超えた |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/teams/{teamID}/users/page/1/limit/25" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    f"{BASE_URL}/teams/{team_id}/users/page/1/limit/25",
    headers=headers
)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  `${BASE_URL}/teams/${teamId}/users/page/1/limit/25`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const data = await response.json();
```

{% endtab %}
{% endtabs %}
