跳到主要内容

电商系统对接指南

本文面向技术对接人员，说明第三方电商系统如何与微语客服系统完成基础数据、业务对象和客服入口的集成。

适用场景：

  • 商城 H5、PC Web、App 接入在线客服
  • 在客服侧展示店铺、商品、订单上下文
  • 将电商用户体系映射为客服访客体系
  • 将业务系统中的订单、商品数据同步到客服工作台

核心概念区分​

在微语系统中，需要明确区分两类身份：

1. 注册用户 User​

注册用户对应后端 UserEntity，是系统中的正式账号。

典型特征：

  • 需要登录
  • 可以被分配组织、角色、权限
  • 可以作为管理员、客服、主管、运营人员等后台账号
  • 可以参与 RBAC 权限控制
  • 具备 username、email、mobile、currentOrganization、currentRoles 等账号属性

典型用途：

  • 登录管理后台
  • 作为客服接待访客
  • 作为管理员维护店铺、商品、订单、组织、角色权限

2. 访客 Visitor​

访客对应后端 VisitorEntity，是会话侧的轻量身份。

典型特征：

  • 默认无需登录
  • 不参与后台权限控制
  • 不分配管理员、客服、主管等系统角色
  • 主要用于承载会话中的访客身份、来源渠道和扩展资料
  • 具备 visitorUid、nickname、avatar、mobile、email、extra 等会话属性

典型用途：

  • 网站访客发起咨询
  • App 用户进入客服会话
  • 电商会员在商品页、订单页咨询客服

3. 两者之间的关系​

请重点区分以下事实：

  • 业务系统中的“已登录会员”在接入客服时，通常仍然映射为微语的 VisitorEntity
  • 前端传入 visitorUid 仅用于标识会话访客身份，并不等于创建了后台 UserEntity
  • 传入 nickname、avatar、mobile、email 只是补充访客资料，并不会自动获得任何后台权限
  • 只有显式创建并分配角色的 UserEntity，才能成为管理员、客服、主管等后台用户

简化理解：

  • UserEntity 负责“登录与权限”
  • VisitorEntity 负责“会话与访客身份”

推荐接入顺序​

建议按以下顺序推进，便于快速形成最小可用闭环：

  1. 获取 Token，打通 API 认证
  2. 梳理注册用户 User 与访客 Visitor 的边界
  3. 对接访客信息，保证会话身份可识别
  4. 对接组织信息，确定数据归属组织
  5. 对接店铺信息，建立业务店铺上下文
  6. 对接商品信息，让客服识别咨询商品
  7. 对接订单信息，让客服识别咨询订单
  8. 对接客服、工作组与路由策略
  9. 接入会话历史、售后等扩展能力

最小闭环方案​

如果希望先快速上线一个可工作的电商客服入口，最少需要完成以下内容：

  1. 获取 accessToken
  2. 在前端初始化客服组件时传入 org、sid、t
  3. 传入 visitorUid、nickname、avatar
  4. 在商品详情页传入 goodsInfo
  5. 在订单详情页传入 orderInfo

完成后即可实现：

  • 访客从电商页面进入客服会话
  • 客服侧看到访客身份
  • 客服侧看到当前商品或订单上下文

对接前提​

开始之前请确认以下信息已经准备完成：

  • 微语服务端访问地址，例如 http://127.0.0.1:9003
  • 对应组织的 orgUid
  • 工作组 uid、客服 uid 或机器人 uid
  • 电商系统的用户主键、店铺主键、商品主键、订单主键定义
  • 是否需要管理端主动同步商品、订单、店铺数据
  • 是否需要访客端 H5 直连，还是通过前端 SDK 集成

主键映射建议​

为避免后续排查困难，建议从一开始就区分“微语系统 uid”和“业务系统主键”：

  • uid：微语系统内部记录主键，通常由系统生成
  • visitorUid：第三方业务用户主键，建议直接使用电商用户 id
  • shopUid：第三方业务店铺主键
  • goodsUid：第三方业务商品主键
  • orderUid：订单中的商品主键，不是订单记录 uid

建议：

  • 不要把微语内部 uid 当作外部系统主键长期保存
  • 外部系统应长期持有自己的业务主键，并映射到 visitorUid、shopUid、goodsUid
  • 调用查询详情、更新、删除接口时，再使用微语返回的记录 uid

数据归属原则​

电商系统接入时，数据通常按组织和店铺两层归属：

  • orgUid：用于组织级隔离，是大部分管理端接口的必要条件
  • shopUid：用于标识具体店铺，适用于多店铺场景
  • visitorUid：用于将会话与业务用户绑定

推荐做法：

  • 单组织单店铺：所有接口固定传 orgUid，按需传 shopUid
  • 单组织多店铺：商品、订单、客服路由都显式带上 shopUid
  • 多组织多租户：优先保证组织隔离，再处理店铺维度

Token信息对接​

用途：

  • 调用管理端 API
  • 后台同步商品、订单、店铺数据
  • 做服务端到服务端集成

注册用户对接​

建议重点关注：

  • 注册用户是后台账号，对应 UserEntity
  • 注册用户可被赋予角色和权限，例如管理员、客服、主管
  • 注册用户需要登录后才能访问后台及管理端 API
  • 如果业务侧只是把已登录会员带入聊天窗口，不代表该会员会成为系统注册用户

访客信息对接​

建议重点关注：

  • 访客对应 VisitorEntity
  • 访客默认无需登录
  • 访客不参与后台角色与权限体系
  • 前端聊天组件中传入的 visitorUid、nickname、avatar 本质上是在描述访客身份
  • 如果业务系统已有会员体系，建议将会员 id 稳定映射到 visitorUid

组织信息对接​

建议重点关注：

  • 获取并固定业务使用的 orgUid
  • 不同组织之间不要复用访客或店铺上下文

权限信息对接​

适用场景：

  • 多角色后台
  • 客服、主管、管理员权限隔离
  • 店铺数据的查询、修改、导出权限控制

店铺信息对接​

典型用途：

  • 在管理端维护电商店铺资料
  • 将客服、工作组与店铺绑定
  • 在多店铺场景下区分商品和订单归属

商品信息对接​

典型用途：

  • 商品详情页打开客服时，将当前商品上下文带给客服
  • 通过管理端接口导入或同步商品数据
  • 让客服工作台右侧展示咨询商品信息

订单信息对接​

典型用途：

  • 订单详情页发起售前、售后咨询
  • 将订单状态、商品信息、收货信息同步给客服
  • 通过 orgUid + visitorUid 在客服侧查询用户最近订单

一对一客服对接​

适用场景：

  • 指定专属客服
  • 会员客服、VIP 客服
  • 二线技术支持或售后专员

工作组对接​

适用场景：

  • 售前、售后、物流、退换货分组接待
  • 按业务线或店铺路由到不同工作组

访客历史会话对话​

推荐对接链路​

链路一：商品详情页咨询​

  1. 前端页面拿到当前登录会员
  2. 将该会员映射为访客身份，组装 visitorUid、nickname、avatar
  3. 组装当前商品 goodsInfo
  4. 打开客服组件或跳转 H5 会话页
  5. 客服侧查看商品卡片并继续沟通

链路二：订单详情页咨询​

  1. 前端页面拿到当前登录会员和订单数据
  2. 将该会员映射为访客身份，组装 visitorUid
  3. 组装 orderInfo
  4. 打开客服组件
  5. 客服侧查看订单状态、商品、收货信息

链路三：后台批量同步商品/订单​

  1. 服务端获取 accessToken
  2. 定时任务或事件驱动调用管理端 API
  3. 使用创建接口或 Excel 导入同步数据
  4. 客服工作台按访客或组织查询上下文信息

实施建议​

前端集成建议​

  • 商品页和订单页优先使用 SDK 动态传参
  • H5 跳转场景注意 URL 编码和长度限制
  • 图片地址统一使用 HTTPS
  • 对于 extra 字段，优先传结构化 JSON 字符串

服务端同步建议​

  • 管理端同步建议由服务端发起，不建议在浏览器暴露后台写接口能力
  • 为商品、订单、店铺建立幂等规则，避免重复导入
  • 订单状态变化时可按业务需要做增量更新

安全建议​

  • 不要在前端硬编码管理端账号密码
  • accessToken 应仅用于受控服务端调用或可信管理端页面
  • 订单收货地址、手机号等敏感信息建议脱敏后再展示给客服

常见问题​

1. 应该先同步商品订单，还是先接前端聊天入口？​

建议先打通前端聊天入口和访客身份，再逐步补商品、订单同步。这样上线速度更快，也便于分阶段验收。

这里的“用户身份”在大多数电商接入场景中，指的是“业务会员映射为访客身份”，不是先创建后台注册用户。

2. 商品和订单一定要走管理端 API 吗？​

不一定。访客发起会话时，可以直接通过 goodsInfo、orderInfo 将当前上下文传给客服组件。管理端 API 更适合做后台沉淀、批量导入和统一查询。

3. 多店铺场景怎么区分？​

建议所有商品、订单、路由配置都显式绑定 shopUid，不要只靠名称区分。

4. 如何避免 uid 混用？​

外部系统始终保存自己的业务主键，调用微语更新、删除、详情接口时再使用微语返回的记录 uid。

同时请区分：

  • 后台账号使用 UserEntity 体系
  • 会话侧身份使用 VisitorEntity 体系
  • 前端常传的 visitorUid 不是后台 UserEntity.uid

验收清单​

上线前至少确认以下事项：

  • 可以通过登录接口正常获取 accessToken
  • 前端可正常打开客服组件或 H5 会话页
  • 访客身份在客服侧可识别
  • 商品详情页能正确展示商品上下文
  • 订单详情页能正确展示订单上下文
  • 多店铺场景下数据不会串店
  • 管理端查询、导出接口返回符合预期
编辑此页
最后由 jack ning 于 更新

这页文档对您有帮助吗？