用户数据互通 API

用户数据互通（Channel User）是开放平台面向合作方 B 端系统的服务对服务接口（S2S）。 合作方通过此组接口将自身用户、家庭组、家庭成员数据写入晓葆平台，实现健康档案、 权益卡、AI 解读等能力与合作方用户体系的双向打通。

概述

接口路径前缀：/open/v1/channel/users

鉴权说明

所有接口均为 B 端 S2S 调用，需在 HTTP Header 中携带以下三个字段：

一步注册绑定

将合作方 App 用户、家庭组（多组）、家庭成员一次性绑定到开放平台。

• 幂等键：(app_id, channel_user_id)，重复调用返回已有映射，不产生重复用户。
• family_groups 和 family_members 均为可选，仅传 user 时为纯建档。
• family_members[].app_group_id 必须存在于本次 family_groups 列表中。

请求体（application/json）：

user 对象：

family_groups 单项：

family_members 单项：

请求示例：

POST /open/v1/channel/users
X-App-Id: 100023
X-Timestamp: 1743494400
X-Signature: d41d8cd98f00b204e9800998ecf8427e

{
  "channel_user_id": "partner_u_8801",
  "user": {
    "name": "张三",
    "phone": "13800138000",
    "gender": "male",
    "birth_date": "1985-06-15"
  },
  "family_groups": [
    { "app_group_id": 501, "name": "张三家庭" }
  ],
  "family_members": [
    {
      "app_user_id": "partner_m_1001",
      "app_group_id": 501,
      "name": "张三",
      "relationship": "SELF",
      "gender": "male",
      "birth_date": "1985-06-15",
      "is_default": true
    }
  ]
}

成功响应（首次注册 201 Created，幂等命中 200 OK）：

{
  "success": true,
  "code": 0,
  "message": "绑定成功",
  "data": {
    "open_user_id": 10086,          // 开放平台用户ID，请持久化存储
    "channel_user_id": "partner_u_8801",
    "created": true,                // false 表示幂等命中已有记录
    "family_groups": [
      { "family_group_id": 2001, "app_group_id": 501 }
    ],
    "family_members": [
      { "member_id": 3001, "app_user_id": "partner_m_1001" }
    ]
  },
  "timestamp": "2026-04-01T10:00:00+08:00"
}

全量用户快照

返回指定用户的基础信息、全部有效家庭组及家庭成员的完整快照。 App 侧收到用户互通类 Webhook 后，调用此接口对齐本地数据。

路径参数：

查询参数（可选）：

成功响应（200 OK）：

{
  "success": true,
  "code": 0,
  "message": "获取成功",
  "data": {
    "user": {
      "open_user_id": 10086,
      "name": "张三",
      "nickname": null,
      "gender": "male",
      "avatar": null,
      "phone": "138****8000",     // 脱敏：前3后4
      "email": null,
      "birth_date": "1985-06-15",
      "status": "ACTIVE",
      "registered_at": "2026-04-01 10:00:00"
    },
    "family_groups": [
      {
        "family_group_id": 2001,
        "app_group_id": 501,
        "name": "张三家庭",
        "member_count": 1
      }
    ],
    "family_members": [
      {
        "member_id": 3001,
        "app_user_id": "partner_m_1001",
        "app_group_id": 501,
        "family_group_id": 2001,
        "name": "张三",
        "relationship": "SELF",
        "gender": "male",
        "birth_date": "1985-06-15",
        "phone": null,
        "id_type": null,
        "height": null,
        "weight": null,
        "blood_type": null,
        "is_default": true,
        "updated_at": "2026-04-01 10:00:00"
      }
    ]
  },
  "timestamp": "2026-04-01T10:00:00+08:00"
}

更新用户基础信息

PATCH 语义：只传需要变更的字段，未传字段保持不变。 成功后触发 Webhook：user.profile.updated。

请求体（所有字段均为可选）：

成功响应（200 OK）：

{ "success": true, "code": 0, "message": "更新成功", "timestamp": "..." }

新增或更新家庭组

以 app_group_id 为幂等键 upsert。相同 app_group_id 重复提交只更新 name，不产生重复记录。 成功后触发 Webhook：user.family_group.created（含更新语义）。

请求体：

成功响应（新建 201，更新 200）：

{
  "success": true,
  "code": 0,
  "message": "家庭组创建成功",
  "data": {
    "family_group_id": 2001,
    "app_group_id": 501,
    "name": "张三家庭",
    "created": true          // false 表示已存在并更新
  },
  "timestamp": "..."
}

解散家庭组

软标记家庭组为已解散（status=0），并级联软删除组内所有家庭成员。 成功后触发 Webhook：user.family_group.deleted。

路径参数：

成功响应（200 OK）：

{ "success": true, "code": 0, "message": "家庭组已解散", "timestamp": "..." }

新增或更新家庭成员

以 app_user_id 为幂等键 upsert。通过 app_group_id 指定归属家庭组（开放平台自动解析为 family_group_id）。 成功后触发 Webhook：user.family_member.created 或 user.family_member.updated。

请求体：

relationship 枚举（常用值）：

成功响应（新建 201，更新 200）：

{
  "success": true,
  "code": 0,
  "message": "家庭成员添加成功",
  "data": {
    "member_id": 3001,                    // 开放平台成员ID，请持久化存储
    "app_user_id": "partner_m_1001",
    "created": true
  },
  "timestamp": "..."
}

删除家庭成员

软删除家庭成员（写入 deleted_at），不物理删除数据。 成功后触发 Webhook：user.family_member.deleted。

路径参数：

成功响应（200 OK）：

{ "success": true, "code": 0, "message": "家庭成员已删除", "timestamp": "..." }

Webhook 事件

所有写入操作成功后，平台会向应用配置的 Webhook URL 推送事件通知（异步）：

错误码