七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
客户管理CRM 对接

CRM 接口对接

CRM 接口的鉴权、用户与订单信息、微信生态及企微群聊对接说明。

概述

企业 CRM 接口由企业开发者实现，并在七鱼管理后台的 CRM 信息对接配置页中填写。当访客接入时，七鱼会使用轻量对接中传入的 uid 调用企业接口，并携带企业配置的 appid 及获取到的 token。接口返回的数据会展示在客服工作台当前会话和历史会话的“更多信息”标签页中。

通过这些接口，企业可以向七鱼提供用户信息、订单信息等 CRM 数据，帮助客服更高效地了解访客并提供服务。

企业接口是一组由七鱼发起调用的 HTTP 或 HTTPS 接口。七鱼与企业 CRM 系统通过这些接口交换 JSON 数据：

  • 对于客服工作台前端发起的调用，浏览器会先发送 OPTIONS 预检请求，再发送 POST 请求；企业接口需要正确响应跨域请求。
  • 企业接口处理请求后，以 JSON 格式返回用户或订单数据。

为保证数据安全，企业需要提前为七鱼分配 appid 和 appsecret，用于接口调用认证。具体认证方式见下文。

本文档中的接口地址均为相对路径。完整 URL 需要在七鱼管理后台的 系统 → 扩展与集成 中配置。

跨域访问

由客服工作台前端发起的接口调用需要支持跨域访问。企业接口应根据请求来源返回以下响应头：

Access-Control-Allow-Headers: origin, x-csrftoken, content-type, accept, x-auth-code, X-App-Id, X-Token
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Origin: https://xxx.qiyukf.com

将 xxx 替换为企业在七鱼申请的二级域名。如果需要同时允许 HTTP 和 HTTPS 来源，应根据请求的 Origin 动态返回匹配的单个值；Access-Control-Allow-Origin 不支持用逗号同时声明多个来源。

更多信息请参考 W3C Cross-Origin Resource Sharing。

接口认证方式

接口认证分为新版和老版：

  • 2022 年 9 月 22 日之后创建的企业：在线业务获取用户信息时使用新版接入方式。
  • 2022 年 9 月 22 日之前创建的企业：加入白名单后，也可以在在线业务中使用新版接入方式；如需开通，请联系技术支持。
  • 呼叫业务：仍使用老版接入方式。

新版接口认证方式

POST 请求会携带以下 URL 参数：

参数参数说明
time当前 UTC 时间戳，即从 1970 年 1 月 1 日 00:00:00 UTC 到当前时间的秒数。
checksumSHA1(appSecret + md5 + time) 的小写十六进制字符串，其中 md5 为请求体的 MD5 哈希值。

checksum 的完整计算方式请参见通用说明 - 数据校验。

老版本接口认证方式

老版支持前端调用和后端调用。

接口认证方式有两种可选：

  • 如果企业提供获取 token 接口，后续请求使用 appid 和 token 认证。
  • 如果企业不提供获取 token 接口，或该接口返回空值，则后续请求直接使用 appsecret 作为 token。

认证参数传递方式也有两种可选：

  • 放在请求体 JSON 中，字段名为 appid 和 token。
  • 放在请求头中，字段名为 X-App-Id 和 X-Token。

后端调用

新版接入由七鱼服务端直接调用企业接口，通过 URL 中的 time 和 checksum 参数完成认证。

获取用户信息

接口请求地址

  • POST /get_user_info：在线会话获取用户信息。
  • POST /get_call_user_info：呼叫中心获取电话用户信息。

访客进入会话且七鱼需要获取详细信息时，会调用对应接口。在线会话使用新版认证模式，呼叫业务仍使用老版认证模式。

请求示例

新版认证方式

/get_user_info?time=1756800225&checksum=<checksum>

checksum 的计算方式请参见通用说明 - 数据校验。

老版认证方式

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan"
}

请求参数

参数类型必需说明
appidString是企业分配给网易七鱼系统的 appid
tokenString是当前有效的 token。
useridString是用户唯一标识。

注意： userid 来源于访客发起会话时，各端 SDK 初始化代码传递给七鱼的参数。

备注： 平台电商场景会额外传入 shopid，用于获取对应商户下的用户信息。

返回示例

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "uid": "zhangsan",
  "data": [
    { "key": "real_name", "value": "土豪" },
    { "key": "mobile_phone", "hidden": true, "value": "13800000000" },
    { "key": "email", "value": "13800000000@163.com" },
    { "index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "http://example.domain/user/zhangsan" },
    { "index": 1, "key": "sex", "label": "性别", "value": "先生" },
    { "index": 5, "key": "reg_date", "label": "注册日期", "value": "2015-11-16" },
    { "index": 6, "key": "last_login", "label": "上次登录时间", "value": "2015-12-22 15:38:54" },
    { "index": 7, "key": "tags", "label": "标签", "value": "企业,vip" },
    { "index": 8, "key": "leaderId", "value": "1001" },
    { "key": "单行文本", "label": "单行文本", "value": "我是单行文本", "isCustomField": true },
    { "key": "多行文本", "label": "多行文本", "value": "我是多行文本", "isCustomField": true },
    { "key": "下拉单选", "label": "下拉单选", "value": "下拉单选1", "isCustomField": true },
    { "key": "下拉多选", "label": "下拉多选", "value": "下拉多选1 ### 下拉多选2", "isCustomField": true },
    { "key": "时间", "label": "时间", "value": "1751981740311", "isCustomField": true }
  ]
}

返回参数

字段类型必需说明
rltInt / String是表明接口调用是否成功。值为0时表示接口调用成功。关于错误码的详细描述，见错误码节。
uidString否get_call_user_info 接口返回该字段，用于关联同一用户的手机号和 uid，打通呼叫与在线历史咨询记录。
dataArray是用一个数组表示用户详细信息的数据。

其中 data 使用数组描述用户详细信息，每个元素代表一个数据项。数据项以 key 和 value 为基础，并通过其他字段控制显示样式：

字段类型必需说明
keyString是数据项的名称，用于区别不同的数据。
valueMixed是该数据显示的值，类型不做限定，根据实际需要进行设定。
labelString是该项数据显示的名称。
indexInt否用于排序。数据项按 index 升序排列；未设置或值相同时，按照在 JSON 中出现的顺序排列。
hrefString否超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
isCustomFieldBoolean否是否将该数据项作为七鱼自定义字段保存。

微信生态获取用户信息

企业前期准备

  1. 由企业自行获取微信生态相关的用户唯一 ID。
    1. 获取微信公众号或小程序的 UnionID（微信官方 UnionID 机制说明）。

    2. 微信客服渠道不支持用户信息对接，因为第三方服务商无法获取 UnionID。详情见下图中的微信客服官方 API 说明。

      微信客服官网 API 说明
    3. 【企微场景】获取企微外部联系人的 UnionID 和明文 external_userid（获取外部联系人详情）。企业可通过这些标识关联企微联系人、公众号用户和小程序用户。仅当联系人是微信用户且企业绑定了微信开发者 ID 时，才能获取 UnionID。
    4. 【企微场景】企业微信不允许第三方服务商直接获取企业主体下的明文 ID。企业需要自行调用转换接口，将七鱼获取的密文 external_userid 转换为对应的明文 ID（自建应用与第三方应用的对接）。
  2. 企业需要自行维护 UnionID、明文 external_userid 与企业业务数据的映射关系。
    1. 建议使用 UnionID 和 external_userid 关联公众号、小程序及企微用户，并结合企业账号登录、手机号授权等方式，打通微信生态与其他渠道的用户数据。

接口请求地址

POST /get_user_info

在七鱼管理后台的 系统管理 → 扩展与集成 → 在线微信生态对接 URL 中配置完整地址。

请求参数

参数类型说明
appidString企业分配给七鱼的 App ID。
openidString当前渠道用户的 token。
useridString用户唯一标识。
sourceappidString渠道主体 App ID。
unionidString企微客服渠道（fromType=wx_cs）传密文 external_user_id；小红书渠道传 xiaohongshuUserId；其他微信生态渠道传 UnionID。微信客服渠道不支持获取 UnionID。
fromTypeString来源渠道类型。
wxworkUserIdString企微助手 ID。
wxworkUserNameString企微助手名称。
wxkfAccountIdString微信客服账号 ID。
xiaohongshuUserIdString小红书用户 ID。
external_user_idString企微客服账号 ID。

返回示例

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "uid": "zhangsan",
  "data": [
    { "key": "real_name", "value": "小明-七鱼" },
    { "key": "mobile_phone", "value": "15968136257" },
    { "key": "email", "value": "qiyu0@163.com" },
    { "key": "tags", "hidden": false, "label": "标签", "value": "test2000" },
    { "index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "http://example.domain/user/zhangsan" },
    { "index": 1, "key": "sex", "label": "性别", "value": "先生1" },
    { "index": 2, "key": "sexa", "label": "性别2", "value": "先生2" },
    { "index": 3, "key": "sexb", "label": "性别3", "value": "先生3" },
    { "index": 10, "key": "reg_date", "label": "注册日期", "value": "2015-11-16" },
    { "index": 11, "key": "last_login", "label": "上次登录时间", "value": "2015-12-22 15:38:54" },
    { "key": "飞书用户名", "label": "飞书用户名", "value": "3333", "isCustomField": true }
  ]
}
字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
uidString是用户唯一 ID，用于打通服务记录。
dataArray是用户详细信息数组。

data 使用数组描述用户详细信息，每个元素代表一个数据项。数据项以 key 和 value 为基础，并通过其他字段控制显示样式：

字段类型必需说明
keyString是数据项的名称，用于区别不同的数据。
valueMixed是该数据显示的值，类型不做限定，根据实际需要进行设定。
labelString是该项数据显示的名称。
indexInt否排序序号。按 index 升序排列；不设定index的数据项将排在后面；未设置或值相同时，按数据在 JSON 中出现的顺序排列。
hrefString否超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
mapString否与七鱼固定字段的映射关系，例如姓名为 real_name、手机号为 mobile_phone、邮箱为 email。映射成功后，数据会同步显示在当前会话和历史会话的“用户资料”中。
isCustomFieldBoolean否是否将该数据项作为七鱼自定义字段保存。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

企微客服群聊获取群信息

企业前期准备

  1. 完成企微自建应用接口对接，并获取群 chatid（获取客户群列表、获取客户群详情）。
  2. 维护企业微信群 chatid 与业务数据的映射关系，可结合群名称、群公告、群管理员等信息进行关联。

接口请求地址

POST /get_group_info

在七鱼管理后台的 系统管理 → 扩展与集成 → 在线企微客服群聊对接 URL 中配置完整地址。

返回示例

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "level": 1,
  "data": [
    { "key": "tags", "hidden": false, "label": "标签", "value": "test2000" },
    { "key": "leaderId", "hidden": false, "label": "负责人", "value": "12222" },
    { "index": 0, "key": "企微自定义字段名", "label": "企微自定义字段名", "value": "3333", "isCustomField": true },
    { "key": "单行文本", "label": "单行文本", "value": "我是单行文本", "isCustomField": true },
    { "key": "多行文本", "label": "多行文本", "value": "我是多行文本", "isCustomField": true },
    { "key": "下拉单选", "label": "下拉单选", "value": "下拉单选1", "isCustomField": true },
    { "key": "下拉多选", "label": "下拉多选", "value": "下拉多选1 ### 下拉多选2", "isCustomField": true },
    { "key": "时间", "label": "时间", "value": "1751981740311", "isCustomField": true },
    { "key": "新数字", "label": "新数字", "value": "122211", "isCustomField": true }
  ]
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
levelInt否VIP 等级。
dataArray是群详细信息数组。

data 使用数组描述群详细信息，每个元素代表一个数据项。数据项以 key 和 value 为基础，并通过其他字段控制显示样式：

字段类型必需说明
keyString是数据项名称，用于区分不同数据。
valueMixed是该数据显示的值，类型不做限定，根据实际需要进行设定。
labelString是该项数据显示的名称。
indexInt否排序序号。按 index 升序排列；未设置或值相同时，按数据在 JSON 中出现的顺序排列。
hrefString否超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
mapString否与七鱼固定字段的映射关系，例如姓名为 real_name、手机号为 mobile_phone、邮箱为 email。
isCustomFieldBoolean否是否将该数据项作为七鱼自定义字段保存。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

老版接入（前端调用）

老版接入主要由客服工作台前端调用企业接口，因此企业接口需要支持跨域访问。获取 token 是例外：该请求由七鱼服务端发起。

获取 token

接口请求地址

GET /get_token

七鱼服务端调用该接口获取 token，并根据返回的有效期决定下一次调用时间。

请求参数

参数类型必需说明
appidString是企业分配给七鱼的 App ID。
appsecretString是企业分配给七鱼的 App Secret。

返回示例

接口应该返回一段包含 token 和有效期的 JSON。

{
    "rlt": 0,
    "token": "qiyukf_security_token",
    "expires": 7200000
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
tokenString是后续接口调用时使用的有效 token。
expiresInt否token 的剩余有效时间，单位为毫秒，不是过期时间戳。未设置或小于等于 0 时默认为 2 小时；token 失效后，其他接口应返回错误码 2。

访客身份识别

七鱼通过用户唯一标识来识别访客身份，不同的接入渠道中所使用的用户唯一标识有所区别：

Web 接入

Web 端使用访客发起会话时上报的 uid 作为用户唯一标识。调用 ysf('config') 时将 uid 传给七鱼：

ysf('config', {
    uid: '123456'
});

Android SDK 接入

Android SDK 需要在发起会话时上报 uid。创建 YSFUserInfo 实例并设置 userId，然后调用 Unicorn.setUserInfo()：

YSFUserInfo userInfo = new YSFUserInfo();
userInfo.userId="uid";
Unicorn.setUserInfo(userInfo);

iOS SDK 接入

iOS SDK 需要在发起会话时上报 uid。创建 QYUserInfo 实例并设置 userId，然后调用 setUserInfo：

QYUserInfo *userInfo = [[QYUserInfo alloc] init];
userInfo.userId = @"uid";
[[QYSDK sharedSDK] setUserInfo:userInfo];

微信接入

使用微信授权接入时，七鱼以访客的 OpenID 作为用户唯一标识，企业需要维护 OpenID 与自身用户体系的映射关系。使用 H5 页面嵌入方式接入时，七鱼无法获取 OpenID，需要像 Web 接入一样，通过 ysf.config() 传入访客 uid。

电话接入

呼叫中心将以访客呼入电话号码作为用户唯一标识。

获取用户信息

接口请求地址

  • POST /get_user_info：在线会话获取用户信息。
  • POST /get_call_user_info：呼叫中心获取电话用户信息。

七鱼需要获取访客详细信息时，会调用对应接口。浏览器会先发送 OPTIONS 预检请求，再以 application/json 格式发送 POST 请求。

返回数据会显示在当前会话和历史会话右侧用户资料区的“更多信息”标签页中。

用户唯一标识会包含在 POST 请求体中。

请求示例

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan",
    "staffphone": "057189850000"
}

请求参数

参数类型必需说明
appidString是企业在七鱼侧的应用标识。
tokenString是当前有效的 token。
useridString是用户唯一标识。
staffphoneString否企业和用户联系时使用的中继号码。

注意： userid 来源于访客发起会话时，各端 SDK 初始化代码传递给七鱼的参数。

备注： 平台电商场景会额外传入 shopid，用于获取对应商户下的用户信息。

返回示例

接口应该返回一段包含用户数据的 JSON。

{
  "rlt": 0,
  "uid": "zhangsan",
  "data": [
    { "index": 0, "key": "account", "label": "账号", "value": "zhangsan", "href": "url" },
    { "index": 1, "key": "name", "label": "姓名", "value": "土豪", "edit": true, "map": "real_name", "href": "url" },
    { "index": 2, "key": "phone", "label": "手机", "value": "13800000000", "edit": true, "map": "mobile_phone", "href": "url" },
    { "index": 3, "key": "email", "label": "邮箱", "value": "13800000000@163.com", "edit": true, "map": "email", "href": "url" },
    { "index": 4, "key": "tags", "label": "标签", "value": "企业,vip" },
    {
      "index": 5,
      "key": "vip",
      "label": "会员",
      "value": [
        { "id": 0, "name": "类型一" },
        { "id": 1, "name": "类型三", "check": true },
        { "id": 2, "name": "类型二" }
      ],
      "select": true,
      "isCustomField": true
    }
  ],
  "modify_cb": "url"
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
uidString否get_call_user_info 接口返回该字段，用于关联同一用户的手机号和 uid，打通呼叫与在线历史咨询记录。
dataArray是用一个数组表示用户详细信息的数据。
modify_cbString否用户信息修改后的回调接口地址。配置后，客服可在七鱼工作台中更新客户信息。

data 使用数组描述用户详细信息，每个元素代表一个数据项。数据项以 key 和 value 为基础，并通过其他字段控制显示样式：

字段类型必需说明
keyString是数据项的名称，用于区别不同的数据。
valueMixed是该数据显示的值，类型不做限定，根据实际需要进行设定。
labelString是该项数据显示的名称。
indexInt否排序序号。按 index 升序排列；未设置或值相同时，按数据在 JSON 中出现的顺序排列。
hrefString否超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
editBoolean否是否允许编辑。为 true 时以输入框显示，修改后调用 modify_cb 提交更新。
mapString否与七鱼固定字段的映射关系，例如姓名为 real_name、手机号为 mobile_phone、邮箱为 email。
saveBoolean否是否将姓名、邮箱、手机号保存到七鱼。仅在轻量接入未传入这三个保留字段时生效。保存后可用于历史会话搜索和列表展示。
zoneBoolean否控制展示位置。未设置时仅显示在“更多信息”中；为 true 时，同时显示在呼叫中心“账户资料”和在线会话“用户信息”中。
isCustomFieldBoolean否是否将该数据项作为七鱼自定义字段保存。
selectBoolean否是否以下拉框展示。为 true 时，value 应为选项数组；可用 check: true 指定默认选项，否则默认选择第一项。
checkBoolean否与 select 配合使用，表示当前选项是否选中；同一组选项中只能有一个 check: true。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

更新用户信息

接口请求地址

POST {modify_cb}

接口接收用户唯一标识和修改后的字段。与查询接口不同，更新接口使用 application/x-www-form-urlencoded 提交数据。

接口地址由 get_user_info 返回的 modify_cb 指定。

请求示例

{
  "appid": "qiyukf",
  "token": "qiyukf_security_token",
  "userid": "zhangsan",
  "data": [
    { "key": "name", "value": "张三" }
  ]
}

请求参数

参数类型必需说明
appidString是企业在七鱼侧的应用标识。
tokenString是当前有效的 token。
useridString是用户唯一标识。
dataArray是用一个数组表示修改的用户信息数据。

注意： userid 来源于访客发起会话时，各端 SDK 初始化代码传递给七鱼的参数。

data 使用数组描述待更新的数据，每个元素由 key 和 value 组成：

字段类型必需说明
keyString是数据项名称，取自 get_user_info 返回的数据项 key。
valueString是修改后的值，统一按字符串传输。

返回示例

接口应该返回一段包含用户信息更新结果的 JSON。

{
  "rlt": 0,
  "data": [
    {
      "key": "name",
      "msg": "名字太长了。"
    }
  ]
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
dataArray否rlt 不为 0 时，包含各字段修改失败原因的数组。

data 中每个元素描述一个字段的修改失败原因：

字段类型必需说明
keyString是修改失败的字段名，对应请求数据项中的 key。
msgString是该字段修改失败的提示信息。

客服工作台采用失焦自动保存策略：输入框失去焦点时立即提交修改，因此每次只会更新一个字段。

获取订单信息

接口请求地址

  • POST /get_order：在线会话获取用户订单信息。
  • POST /get_call_order：呼叫中心获取用户订单信息。

七鱼调用 get_user_info 获取访客详细信息时，也会调用订单接口。浏览器会先发送 OPTIONS 预检请求，再以 application/json 格式发送 POST 请求。该接口既可承载电商订单信息，也可承载金融交易信息。

返回数据会显示在当前会话和历史会话右侧用户资料区的“更多信息”标签页中，并位于 get_user_info 返回的用户详细信息之后。用户唯一标识会包含在 POST 请求体中。

请求示例

{
    "appid": "qiyukf",
    "token": "qiyukf_security_token",
    "userid": "zhangsan",
    "count": 10,
    "from": 0
}

请求参数

参数类型必需说明
appidString是企业在七鱼侧的应用标识。
tokenString是当前有效的 token。
useridString是用户唯一标识。
countInt是单次请求返回的最大订单数，与 from 配合实现分页。
fromInt是订单列表偏移量，与 count 配合实现分页。

注意： userid 来源于访客发起会话时，各端 SDK 初始化代码传递给七鱼的参数。

备注： 平台电商场景会额外传入 shopid，用于获取对应商户下的订单信息。

返回示例

接口应该返回包含指定用户订单类数据列表的一段 JSON。

{
    "rlt": 0,
    "count": 2,
    "orders": [
        {
            "index": 0,
            "blocks": [
                {
                    "index": 0,
                    "is_title": true,
                    "data": [
                        {"index": 0, "key": "orderid", "label": "订单号", "value": "00001", "href": "url"}
                    ]
                },
                {
                    "index": 1,
                    "data": [
                        {"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
                        {"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"},
                        {"index": 2, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险", "href": "url"},
                        {"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"}
                    ]
                }
            ]
        },
        {
            "index": 1,
            "blocks": [
                {
                    "index": 0,
                    "is_title": true,
                    "data": [
                        {"index": 0, "key": "orderid", "label": "订单号", "value": "00002", "href": "url"}
                    ]
                },
                {
                    "index": 1,
                    "data": [
                        {"index": 0, "key": "product", "label": "产品名称", "value": "易钱包", "href": "url"},
                        {"index": 1, "key": "amount", "label": "支付金额", "value": "2000.00元"},
                        {"index": 2, "key": "basic_proc", "label": "基础产品", "value": "渤海人寿保险", "href": "url"},
                        {"index": 3, "key": "revenue_yesterday", "label": "昨日收益", "value": "1.00元"}
                    ]
                }
            ]
        }
    ]
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
countInt是表示该用户订单类数据的条目总数，而非此次请求返回的订单数量。用于控制分页。
ordersArray是用一个数组表示用户订单列表的数据。

订单列表有多层数据嵌套：

  • orders 中的每个元素表示一个订单。
  • 每个订单可以按内容拆分为多个展示区块，保存在 blocks 数组中。
  • 每个区块通过 data 数组保存具体数据；每个数据项以 key 和 value 为基础，并通过其他字段控制显示样式。

orders 中每个订单的数据定义如下：

字段类型必需说明
indexInt是订单排序序号。按 index 升序排列；值相同时，按订单在 JSON 中出现的顺序排列。
blocksArray是用一个数组表示该订单包含的区块。

blocks 中每个区块的数据定义如下：

字段类型必需说明
indexInt是区块排序序号。按 index 升序排列；值相同时，按区块在 JSON 中出现的顺序排列。
dataArray是用一个数组表示该区块包含的数据。
is_titleBoolean是是否作为订单标题行。为 true 时，区块以标题样式显示并控制订单展开或收起；该区块的 data 数组只能包含一个标题元素。每个 blocks 数组必须指定一个标题区块。

data 中每个数据项的定义如下：

字段类型必需说明
keyString是数据项的名称，用于区别不同的数据。
valueMixed是该数据显示的值，类型不做限定，根据实际需要进行设定。
labelString是该项数据显示的名称。
indexInt否数据项排序序号。按 index 升序排列；未设置或值相同时，按数据在 JSON 中出现的顺序排列。
hrefString否超链接地址。若指定该值，则该项数据将显示为超链接样式，点击后跳转到其值所指定的 URL 地址。
editBoolean否是否允许编辑。为 true 时以输入框显示，修改后调用 modify_cb 提交更新。
selectBoolean否是否以下拉框展示。为 true 时，value 应为选项数组；可用 check: true 指定默认选项，否则默认选择第一项。
checkBoolean否与 select 配合使用，表示当前选项是否选中；同一组选项中只能有一个 check: true。

注意： 返回的数据将根据预设的样式直接显示在网易七鱼页面相应的位置上。如果数据敏感、保密性要求高，应当在返回时就做脱敏处理。网易七鱼系统不会对数据做额外的处理。

更新订单信息

接口请求地址

POST {modify_cb}

接口接收用户唯一标识和修改后的订单字段。与查询接口不同，更新接口使用 application/x-www-form-urlencoded 提交数据。

接口地址由 get_order 返回的 modify_cb 指定。

请求示例

{
  "appid": "qiyukf",
  "token": "qiyukf_security_token",
  "userid": "zhangsan",
  "data": [
    { "key": "amount", "value": "3000元" }
  ]
}

请求参数

参数类型必需说明
appidString是企业在七鱼侧的应用标识。
tokenString是当前有效的 token。
useridString是用户唯一标识。
dataArray是待更新的订单字段数组。

注意： userid 来源于访客发起会话时，各端 SDK 初始化代码传递给七鱼的参数。

data 使用数组描述待更新的数据，每个元素由 key 和 value 组成：

字段类型必需说明
keyString是数据项名称，取自 get_order 返回的数据项 key。
valueString是修改后的值，统一按字符串传输。

返回示例

接口应该返回一段包含用户信息更新结果的 JSON。

{
  "rlt": 0,
  "data": [
    {
      "key": "amount",
      "msg": "金额格式不正确。"
    }
  ]
}

返回参数

字段类型必需说明
rltInt / String是调用结果。值为 0 表示成功，其他值见错误码。
dataArray否rlt 不为 0 时，包含各字段修改失败原因的数组。

data 中每个元素描述一个字段的修改失败原因：

字段类型必需说明
keyString是修改失败的字段名，对应请求数据项中的 key。
msgString是该字段修改失败的提示信息。

自定义接口参数

企业可以在访客接入时，通过扩展 CRM 配置为获取用户信息和获取订单信息接口添加自定义请求参数。

扩展 CRM 接入示例

ysf('config', {
  uid: '1442286211167',
  data: JSON.stringify([
    { key: 'real_name', value: '土豪' },
    { key: 'mobile_phone', hidden: true, value: '13800000000' },
    { key: 'email', value: '13800000000@163.com' },
    { index: 0, key: 'account', label: '账号', value: 'zhangsan', href: 'http://example.domain/user/zhangsan' },
    { index: 1, key: 'sex', label: '性别', value: '先生' },
    { index: 5, key: 'reg_date', label: '注册日期', value: '2015-11-16' },
    { index: 6, key: 'last_login', label: '上次登录时间', value: '2015-12-22 15:38:54' },
    { type: 'crm_param', key: 'startTime', value: '2017-05-20', area: 'user' },
    { type: 'crm_param', key: 'endTime', value: '2017-05-21', area: 'order' }
  ])
});
字段类型必需说明
typeString是固定为 crm_param，表示这是一个 CRM 自定义请求参数。
keyString是自定义请求参数名。
valueString是自定义请求参数值。
areaString否参数生效范围，可取 user 或 order。

area=user 时仅应用于获取用户信息接口，area=order 时仅应用于获取订单信息接口；未设置 area 时，同时应用于两个接口。

这篇文档有帮助吗？

轻量 CRM 对接

Web、iOS、Android SDK 提交用户资料的方式。

客户信息变更事件对接

客户信息变更和客户标签变更时，七鱼向企业侧接口推送事件的配置、鉴权、字段和响应约定。

目录

概述
跨域访问
接口认证方式
新版接口认证方式
老版本接口认证方式
后端调用
获取用户信息
接口请求地址
请求示例
请求参数
返回示例
返回参数
微信生态获取用户信息
企业前期准备
接口请求地址
请求参数
返回示例
企微客服群聊获取群信息
企业前期准备
接口请求地址
返回示例
返回参数
老版接入（前端调用）
获取 token
接口请求地址
请求参数
返回示例
返回参数
访客身份识别
Web 接入
Android SDK 接入
iOS SDK 接入
微信接入
电话接入
获取用户信息
接口请求地址
请求示例
请求参数
返回示例
返回参数
更新用户信息
接口请求地址
请求示例
请求参数
返回示例
返回参数
获取订单信息
接口请求地址
请求示例
请求参数
返回示例
返回参数
更新订单信息
接口请求地址
请求示例
请求参数
返回示例
返回参数
自定义接口参数
扩展 CRM 接入示例