> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# メンバー API

> 組織メンバーの一覧・管理、統計、クォータ、Add-On Cap の API。

## このドキュメントについて

Qoder UI 外でメンバーとクォータを管理する**インテグレーション**向け。事前に **[API キーの取得](/ja/account/teams/openapi/get-api-key)** を完了し、**[共通仕様](/ja/account/teams/openapi/conventions)** を参照してください。

### 前提条件

* 有効な API キー：`Authorization: Bearer <api_key>`。
* キーは対象組織に紐づき、呼び出し元の権限が操作を許可している必要があります。

## API 一覧

### 1. メンバー一覧

`GET /v1/organizations/{organization_id}/members`

組織のメンバーリストをページネーションで取得します。キーワード検索をサポートします。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

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

| パラメータ            | 型       | 必須  | 説明                       |
| ---------------- | ------- | --- | ------------------------ |
| `email`          | string  | いいえ | メール完全一致検索                |
| `includeDeleted` | string  | いいえ | `true` に設定すると削除済みメンバーを含む |
| `maxResults`     | integer | いいえ | ページサイズ（デフォルト 20、最大 100）  |
| `nextToken`      | string  | いいえ | ページネーションカーソル             |

#### 成功レスポンス（200 OK）

**デフォルトクエリ（アクティブメンバーのみ）：**

```json theme={null}
{
  "members": [
    {
      "id": "member_abc123",
      "name": "Alice",
      "email": "alice@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_ghi789",
      "name": "Charlie",
      "role": "org_member",
      "status": "ENABLED",
      "joinedAt": "2025-07-10T14:30:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": "eyJwYWdlIjogMn0="
}
```

> 一部のメンバーレコードでは `email` フィールドが**返されない**場合があります。インテグレーション時はオプションフィールドとして処理してください。

**削除済みメンバーを含む（**`**includeDeleted=true**`**）：**

```json theme={null}
{
  "members": [
    {
      "id": "member_abc123",
      "name": "Alice",
      "email": "alice@example.com",
      "role": "org_admin",
      "status": "ENABLED",
      "joinedAt": "2025-06-01T08:00:00Z"
    },
    {
      "id": "member_def456",
      "name": "Bob",
      "email": "bob@example.com",
      "role": "org_member",
      "status": "DELETED",
      "joinedAt": "2025-03-15T10:00:00Z",
      "deletedAt": "2026-02-01T12:00:00Z"
    }
  ],
  "maxResults": 20,
  "nextToken": ""
}
```

> `deletedAt` は削除済みメンバーにのみ返されます。アクティブメンバーにはこのフィールドは含まれません。`nextToken` が空文字列の場合は最終ページです。

#### レスポンスフィールド

| フィールド                 | 型               | 説明                                                                                                                                  |
| --------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `members`             | array           | メンバーリスト                                                                                                                             |
| `members[].id`        | string          | メンバー ID                                                                                                                             |
| `members[].name`      | string          | メンバー名                                                                                                                               |
| `members[].email`     | string          | メンバーメール（空の場合あり）                                                                                                                     |
| `members[].role`      | string          | ロール名（例：`org_admin`、`org_member`）                                                                                                    |
| `members[].status`    | string          | メンバーステータス：`ENABLED`（アクティブ）、`DISABLED`（停止済み）、`UNACTIVATED`（未アクティブ化）、`APPROVE_PENDING`（承認待ち）、`APPROVE_DECLINED`（承認拒否）、`DELETED`（削除済み） |
| `members[].joinedAt`  | string          | 参加日時（ISO 8601）                                                                                                                      |
| `members[].deletedAt` | string または null | 削除日時（ISO 8601）；アクティブメンバーには返されない                                                                                                     |
| `maxResults`          | int32           | このリクエストのページサイズ                                                                                                                      |
| `nextToken`           | string          | 次ページカーソル；空は最終ページ                                                                                                                    |

***

### 2. メンバー詳細取得

`GET /v1/organizations/{organization_id}/members/{member_id}`

単一メンバーの詳細情報を取得します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### 成功レスポンス（200 OK）

**アクティブメンバー：**

```json theme={null}
{
  "id": "member_abc123",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2025-06-01T08:00:00Z"
}
```

**削除済みメンバー（**`**GetMember**` **は削除済みメンバーも自動的に含む）：**

```json theme={null}
{
  "id": "member_def456",
  "name": "Bob",
  "email": "bob@example.com",
  "role": "org_member",
  "status": "DELETED",
  "joinedAt": "2025-03-15T10:00:00Z",
  "deletedAt": "2026-02-01T12:00:00Z"
}
```

#### レスポンスフィールド

「メンバー一覧」の `members[]` フィールドと同一です。

***

### 3. メンバー統計取得

`GET /v1/organizations/{organization_id}/members/statistics`

組織メンバーに関する統計データを取得します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### 成功レスポンス（200 OK）

```json theme={null}
{
  "totalMembers": 50,
  "billableMembers": 45,
  "adminMembers": 3,
  "purchasedSeats": 100,
  "remainingSeats": 55
}
```

#### レスポンスフィールド

| フィールド             | 型     | 説明        |
| ----------------- | ----- | --------- |
| `totalMembers`    | int32 | 総メンバー数    |
| `billableMembers` | int32 | 課金対象メンバー数 |
| `adminMembers`    | int32 | 管理者数      |
| `purchasedSeats`  | int32 | 購入済みシート数  |
| `remainingSeats`  | int32 | 残りシート数    |

***

### 4. メンバー削除

`DELETE /v1/organizations/{organization_id}/members/{member_id}`

組織からメンバーを削除します。削除前に、現在の課金サイクル内での使用量を確認します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### 成功レスポンス（200 OK）

**現サイクルで使用量あり（シート解放はサイクル終了まで遅延）：**

```json theme={null}
{
  "id": "member_abc123",
  "hasBillingCycleUsage": true
}
```

**現サイクルで使用量なし（シートを即時解放可能）：**

```json theme={null}
{
  "id": "member_abc123",
  "hasBillingCycleUsage": false
}
```

#### レスポンスフィールド

| フィールド                  | 型      | 説明                                |
| ---------------------- | ------ | --------------------------------- |
| `id`                   | string | 削除されたメンバーの ID                     |
| `hasBillingCycleUsage` | bool   | 現在の課金サイクル内で使用量があるか（シート解放タイミングに影響） |

#### エラーレスポンス

**メンバーがチームに所属していない（404）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}
```

**メンバー数不足（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "InsufficientMembers",
  "message": "The number of organization members cannot be less than the minimum requirement"
}
```

***

### 5. メンバークォータ取得

`GET /v1/organizations/{organization_id}/members/{member_id}/quota`

指定メンバーの完全な使用状況を取得します。プランクォータ、リソースパッククォータ、合計クォータ、組織共有パッククォータを含みます。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### 成功レスポンス（200 OK）

**組織共有パックあり、ステータス正常：**

```json theme={null}
{
  "userId": "user_abc123",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 350.5,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "resourcePackageQuota": {
    "quotaSummary": {
      "usedValue": 100.0,
      "limitValue": 500.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 450.5,
      "limitValue": 1500.0,
      "unit": "credits"
    }
  },
  "sharedQuota": {
    "quotaSummary": {
      "usedValue": 200.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "active"
}
```

**組織共有パックなし、使用量超過：**

```json theme={null}
{
  "userId": "user_def456",
  "planQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "totalQuota": {
    "quotaSummary": {
      "usedValue": 1000.0,
      "limitValue": 1000.0,
      "unit": "credits"
    }
  },
  "lastResetAt": "2026-03-01T00:00:00Z",
  "nextResetAt": "2026-04-01T00:00:00Z",
  "status": "restricted"
}
```

> 組織に共有パックがない場合 `sharedQuota` は返されません。メンバーにリソースパックがない場合 `resourcePackageQuota` は返されません。`status` が `restricted` の場合、使用量上限に達しています。

#### レスポンスフィールド

| フィールド                  | 型               | 説明                                  |
| ---------------------- | --------------- | ----------------------------------- |
| `userId`               | string          | ユーザー ID                             |
| `planQuota`            | object          | プランクォータ情報                           |
| `resourcePackageQuota` | object          | リソースパッククォータ情報                       |
| `totalQuota`           | object          | 合計クォータ情報（プラン + リソースパック）             |
| `sharedQuota`          | object または null | 組織共有パッククォータ（組織に共有パックがない場合は返されない）    |
| `lastResetAt`          | string          | 前回リセット日時（ISO 8601）                  |
| `nextResetAt`          | string          | 次回リセット日時（ISO 8601）                  |
| `status`               | string          | ユーザーステータス：`active` または `restricted` |

**クォータサマリーフィールド**

| フィールド        | 型       | 説明              |
| ------------ | ------- | --------------- |
| `usedValue`  | float64 | 使用量             |
| `limitValue` | float64 | クォータ上限          |
| `unit`       | string  | 単位（例：`credits`） |

***

### 6. メンバークォータ一括取得

`POST /v1/organizations/{organization_id}/members/batchGetQuota`

複数メンバーのクォータと使用状況を一度に取得します。[メンバークォータ取得](#5-メンバークォータ取得)と同じ範囲を返します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### リクエストボディ（JSON）

| フィールド       | 型         | 必須 | 検証                  | 説明            |
| ----------- | --------- | -- | ------------------- | ------------- |
| `memberIds` | string\[] | はい | 1～100 件の空でないメンバー ID | クォータを取得するメンバー |

```json theme={null}
{
  "memberIds": ["member_abc123", "member_def456"]
}
```

#### 成功レスポンス（200 OK）

```json theme={null}
{
  "quotas": [
    {
      "memberId": "member_abc123",
      "userId": "user_abc123",
      "planQuota": {
        "quotaSummary": {
          "usedValue": 350.5,
          "limitValue": 1000.0,
          "unit": "credits"
        }
      },
      "resourcePackageQuota": {
        "quotaSummary": {
          "usedValue": 100.0,
          "limitValue": 500.0,
          "unit": "credits"
        }
      },
      "totalQuota": {
        "quotaSummary": {
          "usedValue": 450.5,
          "limitValue": 1500.0,
          "unit": "credits"
        }
      },
      "sharedQuota": {
        "quotaSummary": {
          "usedValue": 200.0,
          "limitValue": 1000.0,
          "unit": "credits"
        }
      },
      "lastResetAt": "2026-03-01T00:00:00Z",
      "nextResetAt": "2026-04-01T00:00:00Z",
      "status": "active"
    },
    {
      "memberId": "member_def456",
      "userId": "user_def456"
    }
  ]
}
```

`quotas` 配列は、重複を含めて `memberIds` と同じ順序で返されます。メンバーにクォータレコードがない場合、その要素には `memberId` と `userId` のみが含まれます。組織に存在しないメンバーが 1 件でもある場合、リクエスト全体が `404 NotFound` となり、部分成功は返しません。

#### レスポンスフィールド

| フィールド                           | 型      | 説明                                        |
| ------------------------------- | ------ | ----------------------------------------- |
| `quotas`                        | array  | メンバークォータの結果一覧                             |
| `quotas[].memberId`             | string | メンバー ID                                   |
| `quotas[].userId`               | string | ユーザー ID                                   |
| `quotas[].planQuota`            | object | Plan クォータ情報。データがない場合は省略                   |
| `quotas[].resourcePackageQuota` | object | リソースパッケージクォータ情報。データがない場合は省略               |
| `quotas[].totalQuota`           | object | 合計クォータ情報。データがない場合は省略                      |
| `quotas[].sharedQuota`          | object | 組織共有パッケージクォータ。データがない場合は省略                 |
| `quotas[].lastResetAt`          | string | 前回リセット時刻（ISO 8601）。データがない場合は省略            |
| `quotas[].nextResetAt`          | string | 次回リセット時刻（ISO 8601）。データがない場合は省略            |
| `quotas[].status`               | string | `active` または `restricted`。クォータデータがない場合は省略 |

***

### 7. メンバー Add-On Cap 更新

`PUT /v1/organizations/{organization_id}/members/{member_id}/addon-cap`

メンバーの Shared Add-On クォータキャップを更新します（Big Model Credits クォータに基づく）。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明      |
| ----------------- | ------ | -- | ------- |
| `organization_id` | string | はい | 組織 ID   |
| `member_id`       | string | はい | メンバー ID |

#### リクエストパラメータ（JSON）

| フィールド      | 型              | 必須 | バリデーション       | 説明                           |
| ---------- | -------------- | -- | ------------- | ---------------------------- |
| `addOnCap` | int64 または null | はい | 非負の整数または null | クォータキャップ；`null` は無制限、`0` は無効 |

#### リクエスト例

**クォータキャップを設定：**

```json theme={null}
{
  "addOnCap": 1000
}
```

**無制限に設定：**

```json theme={null}
{
  "addOnCap": null
}
```

#### 成功レスポンス（200 OK）

```json theme={null}
{
  "memberId": "member_abc123",
  "email": "alice@example.com",
  "addOnCap": 1000
}
```

**無制限の場合：**

```json theme={null}
{
  "memberId": "member_abc123",
  "email": "alice@example.com",
  "addOnCap": null
}
```

#### レスポンスフィールド

| フィールド      | 型              | 説明                      |
| ---------- | -------------- | ----------------------- |
| `memberId` | string         | メンバー ID                 |
| `email`    | string         | メンバーメール                 |
| `addOnCap` | int64 または null | 現在のクォータキャップ；`null` は無制限 |

#### エラーレスポンス

**addOnCap 形式無効（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
```

**メンバーがチームに所属していない（404）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "UserNotTeamMember",
  "message": "User is not a member of this team"
}
```

***

### 8. メンバー Add-On Cap 一括更新

`POST /v1/organizations/{organization_id}/batchUpdateAddOnCap`

指定メンバーの Shared Add-On クォータキャップを一括更新します（Big Model Credits クォータに基づく）。1リクエストあたり最大100メンバー、全メンバーに同じキャップを設定します。

#### パスパラメータ

| パラメータ             | 型      | 必須 | 説明    |
| ----------------- | ------ | -- | ----- |
| `organization_id` | string | はい | 組織 ID |

#### リクエストパラメータ（JSON）

| フィールド       | 型              | 必須 | バリデーション       | 説明                           |
| ----------- | -------------- | -- | ------------- | ---------------------------- |
| `addOnCap`  | int64 または null | はい | 非負の整数または null | クォータキャップ；`null` は無制限、`0` は無効 |
| `memberIds` | string\[]      | はい | 1〜100 個の非空文字列 | 更新対象のメンバー ID リスト             |

#### リクエスト例

**一括でクォータキャップを設定：**

```json theme={null}
{
  "addOnCap": 1000,
  "memberIds": ["member_abc123", "member_def456"]
}
```

**一括で無制限に設定：**

```json theme={null}
{
  "addOnCap": null,
  "memberIds": ["member_abc123"]
}
```

#### 成功レスポンス（200 OK）

```json theme={null}
{
  "members": [
    {
      "memberId": "member_abc123",
      "previousAddOnCap": 500
    },
    {
      "memberId": "member_def456",
      "previousAddOnCap": null
    }
  ]
}
```

> `previousAddOnCap` が `null` の場合、そのメンバーは以前制限なし（無制限）でした。

#### レスポンスフィールド

| フィールド                        | 型              | 説明                                 |
| ---------------------------- | -------------- | ---------------------------------- |
| `members`                    | array          | 更新結果リスト、リクエストの `memberIds` と同じ順序   |
| `members[].memberId`         | string         | メンバー ID                            |
| `members[].previousAddOnCap` | int64 または null | 更新前のクォータキャップ；`null` は以前無制限だったことを示す |

#### エラーレスポンス

**addOnCap 形式無効（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "InvalidAddOnCapFormat",
  "message": "Invalid addOnCap format"
}
```

**memberIds が空（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not be empty"
}
```

**memberIds が 100 件超過（400）**

```json theme={null}
{
  "requestId": "req_abc123",
  "code": "BadRequest",
  "message": "memberIds must not exceed 100"
}
```

***

## エラーコード

| エラーコード                     | HTTP ステータス | 説明                                           |
| -------------------------- | ---------- | -------------------------------------------- |
| `BadRequest`               | 400        | リクエストパラメータが無効（例：member\_id が空、addOnCap が負の数） |
| `InvalidBatchQuotaRequest` | 400        | 一括クォータ取得の JSON リクエストボディが無効                   |
| `InvalidAddOnCapFormat`    | 400        | addOnCap 形式が無効                               |
| `InsufficientMembers`      | 400        | 組織メンバー数が最低要件を下回ることはできない                      |
| `Unauthorized`             | 401        | API キーが欠落または無効                               |
| `Forbidden`                | 403        | この組織へのアクセス権限なし                               |
| `NotFound`                 | 404        | メンバーが見つからない                                  |
| `UserNotTeamMember`        | 404        | ユーザーはこのチームのメンバーではない                          |
| `InternalError`            | 500        | サーバー内部エラー                                    |

エラーレスポンスの形式は [共通仕様](/ja/account/teams/openapi/conventions) の **エラーレスポンス** を参照してください。

***

## 使用例

### メンバー一覧

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?maxResults=20" \
  -H "Authorization: Bearer <api_key>"
```

### メールでメンバー検索

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?email=alice@example.com" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー一覧（削除済みを含む）

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members?includeDeleted=true" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー詳細取得

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー統計取得

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/statistics" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー削除

```bash theme={null}
curl -X DELETE "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123" \
  -H "Authorization: Bearer <api_key>"
```

### メンバー Add-On Cap 更新

```bash theme={null}
curl -X PUT "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/addon-cap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000
  }'
```

### メンバークォータ取得

```bash theme={null}
curl -X GET "https://api.qoder.com/v1/organizations/org_xxx/members/member_abc123/quota" \
  -H "Authorization: Bearer <api_key>"
```

### メンバークォータ一括取得

```bash theme={null}
curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/members/batchGetQuota" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": ["member_abc123", "member_def456"]
  }'
```

### メンバー Add-On Cap 一括更新

```bash theme={null}
curl -X POST "https://api.qoder.com/v1/organizations/org_xxx/batchUpdateAddOnCap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "addOnCap": 1000,
    "memberIds": ["member_abc123", "member_def456"]
  }'
```