三方 ID 模式

在外部对接场景中，部分集团子公司只能使用自身的账号 ID。三方 ID 模式允许这些外部系统通过其原有的 三方 ID 访问 WPS365 开放接口，无需转换为内部 ID。

---

三方 ID 模式的使用场景

1. 接口调用
   在调用 WPS365 开放接口时，如果传入的 user_id 或 dept_id 是外部系统的 ID，需在请求头中设置 X-Kso-Id-Type: external。同时，接口返回的数据会根据当前模式返回相应的 ID，即当请求头中不传 X-Kso-Id-Type 字段或设置 X-Kso-Id-Type: internal 时，响应数据中的 ID 值为内部 ID。当请求头中设置 X-Kso-Id-Type: external 时，响应数据中的 ID 值为三方 ID。

2. 事件回调
   在事件回调数据中，WPS365 开放事件会平级新增具有 ex 前缀的字段，以便支持三方 ID 模式。

---

接口调用示例

用户示例接口

internal 模式请求示例：

POST https://openapi.wps.cn/v7/user/test
Headers:
  X-Kso-Id-Type: internal
Body:
{
    "user_ids": [
      "1",
      "2"
    ]
}

响应示例：

{
  "code": 200,
  "data": {
    "result": [
      {
        "id": "1",
        "name": "用户1"
      },
      {
        "id": "2",
        "name": "用户2"
      }
    ]
  }
}

external 模式请求示例：

POST https://openapi.wps.cn/v7/user/test
Headers:
  X-Kso-Id-Type: external
Body:
{
    "user_ids": [
      "third_user1",
      "third_user2"
    ]
}

响应示例：

{
  "code": 200,
  "data": {
    "result": [
      {
        "id": "third_user1",
        "name": "用户1"
      },
      {
        "id": "third_user2",
        "name": "用户2"
      }
    ]
  }
}

回调事件示例

在事件回调数据中，WPS365 开放事件会平级新增具有 ex 前缀的字段，以便支持三方 ID 模式。

以用户变更事件为例， 回调事件为：

{
  "users": [
    {
      "company_id": "1",
      "user_id": "1", // 内部用户id
      "ex_user_id": "third_user1", // 三方用户id
      "src": {
        "dept_ids": ["1"], // 内部部门id
        "ex_dept_ids": ["third_dept1"] // 三方部门id
      }
    }
  ]
}

使用规范

1. ID 模式一致性

   • 每次接口调用应使用同一种 ID 模式（internal 或 external）。
   • 如果遇到需要同时使用内部 ID 和外部 ID 的批量处理场景，需分两次调用接口：第一次调用使用 internal 模式，传递内部 ID；第二次调用使用 external 模式，传递三方 ID。

2. external 模式下的参数要求

   • 在 external 模式下，接口中的 user_id 和 dept_id 必须为三方 ID（或 external 模式下接口返回的 ID）。external 模式下，即使传入了内部 ID，也会被识别为三方 ID，可能导致报错 ID 不存在。
   • 接口返回的数据会根据当前模式返回相应的 ID。

3. 租户限制

   • 每个租户的三方 ID 仅限在该租户内使用，无法在其他租户中生效。
   • 三方 ID 是某个租户下的概念，调用接口时需确保传入的三方 ID 属于当前访问的租户。

---

常见问题

1. Q1: 是否可以在同一个接口调用中混用 internal 和 external ID？
   不可以。如遇到同时查询内部 ID 和三方 ID 的批量场景，请分两次调用接口，分别使用 internal 和 external 模式。

2. Q2: 使用正确的三方 ID 访问，但接口报错三方 ID 不存在？
   导致出现该报错的原因可能有以下几种：a. 访问的租户与三方 ID 所属的租户不一致，请确保你正在访问的租户与三方 ID 所在的租户一致。b. 三方 ID 确实不存在，请确认三方 ID 是否正确，或者验证三方 ID 是否已经被删除或失效。