统一认证平台 - 账号同步 (M2M)

1. 概述

用于将外部业务系统（如 OA、CRM）的用户账号关系同步到本平台。支持批量调用。

Base URL: {{API_BASE_URL}}

2. 认证方式

此接口不使用签名算法，而是使用 App Access Token。

Header: X-App-Access-Token: <YOUR_TOKEN>
Token 可在平台管理界面的应用详情页查看。

3. 同步接口 (Sync)

创建、更新或删除用户映射关系。

URL: POST /apps/mapping/sync
Content-Type: application/json

逻辑

增改模式 (UPSERT):
- 根据 mobile 查找用户。
- 新建用户: 若用户不存在，必须提供 name（姓名）。english_name（英文名）可选，如未提供会自动生成并确保唯一性。
- 已有用户: 不允许修改 name、mobile、english_name 等用户基本信息。但可以修改映射信息（mapped_key、mapped_email、is_active）。
- 建立或更新该用户与当前应用的映射 (mapped_key, mapped_email, is_active)。
删除模式 (DELETE):
- 仅删除该用户在当前应用下的映射关系。
- 不删除平台上的用户账号。
- 必须提供 mapped_key，且须与平台上该映射记录中的外部账号一致（用于校验）。

Request Body

Field	Type	Required	Description
`mobile`	string	Yes	用户手机号 (平台唯一标识)，须为 11 位中国大陆手机号（`1[3-9]` 开头）
`name`	string	Conditional	用户姓名 (新建用户必填，已有用户不允许修改)
`english_name`	string	Optional	英文名/拼音 (新建用户可选，如未提供会自动生成；已有用户不允许修改)
`mapped_key`	string	Yes	外部系统用户 ID（映射账号，1～100 字符；可修改）
`mapped_email`	string	No	外部系统邮箱 (可修改)
`is_active`	boolean	No	映射状态 (默认 true，可修改)
`sync_action`	string	No	操作类型: `UPSERT` (增改, 默认) 或 `DELETE` (删除映射)

示例 1: 新增用户 (UPSERT)

curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "name": "张三",
           "mapped_key": "user_1001",
           "mapped_email": "zhangsan@example.com",
           "sync_action": "UPSERT"
         }'

注意：english_name 可以不提供，系统会自动生成。

示例 2: 更新已有用户的映射信息 (UPSERT)

curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "mapped_email": "zhangsan_new@example.com",
           "is_active": true,
           "sync_action": "UPSERT"
         }'

注意：已有用户不能修改 name、mobile、english_name，只能修改映射信息。

示例 3: 删除映射 (DELETE)

curl -X POST "{{API_BASE_URL}}/apps/mapping/sync" \
     -H "Content-Type: application/json" \
     -H "X-App-Access-Token: eyJhbGci..." \
     -d '{
           "mobile": "13800138000",
           "mapped_key": "user_1001_updated",
           "sync_action": "DELETE"
         }'

（mapped_key 须与当前平台上该用户在本应用下的映射账号一致。）

Response (200)

{
  "id": 123,           // 映射记录 ID
  "user_id": 456,      // 平台用户 ID
  "user_mobile": "13800138000",
  "mapped_key": "user_1001",
  "is_active": true    // 删除模式下会返回 false
}

4. 错误码

400 Bad Request:
- 参数错误（如手机号格式非法、缺少 mapped_key、新建用户未提供 name）
- 已有用户尝试修改 name、mobile 或 english_name
- 姓名/英文名已存在（新建用户时）
- 映射关系冲突（mapped_key 或 mapped_email 已被占用）
- DELETE 时 mapped_key 与平台记录不一致，或历史数据缺少外部账号
403 Forbidden: Token 无效。

account_sync.md 4.1 KB History Raw