企业接口接入

七鱼调用企业接口、事件推送、页面嵌入和企业侧请求响应格式约定。

服务端 API 中有两类方向相反的接入能力：

类型	调用方向	典型场景
企业调用七鱼 OpenAPI	企业服务器 -> 七鱼服务器	创建工单、查询会话、上传订单、查询统计
企业提供接口给七鱼调用	七鱼服务器或七鱼工作台 -> 企业服务器	CRM 信息、订单信息、工单回调、消息事件推送、机器人动态内容

企业调用七鱼 OpenAPI 时，请阅读通用说明和具体业务接口页。企业提供接口给七鱼调用时，请先阅读本页的调用方向、鉴权、CORS 和响应约定，再进入对应业务目录查看字段、示例和异常处理。

文档位置

场景	业务目录	说明
CRM 对接	客户管理 / CRM 对接	轻量 CRM、CRM 接口、用户认证和 CORS 约束
客户资料与客户标签事件	客户管理 / 客户信息变更事件对接	客户信息变更事件、客户标签变更事件
在线消息、事件、商品订单、实时推送	在线系统 / 在线消息接口	在线消息接口、在线事件、商品和订单查询、实时消息推送
在线工具条与工作台嵌入	在线系统 / 在线工具条对接	登录获取 SDK 接入地址、`postMessage` 事件、通知、文件预览、会话协助和转接
在线消息体结构	在线系统 / 消息类型说明	`msgType` 对应的消息体结构和解析建议
iframe 页面嵌入	系统设置 / iframe 对接详细说明	客服工作台加载企业 iframe 页面时的参数、签名和兼容校验
机器人动态内容	在线机器人 / 对话接入与动态能力 / 服务先知	服务先知、一触即达、动态卡片和返回模板
独立机器人消息接口	在线机器人 / 机器人会话 / 机器人消息接口概览	会话生命周期和通用结构
呼叫事件与工具条	呼叫系统 / 呼叫系统接入	呼叫事件、IVR、通话记录同步、呼叫工具条 SDK 和小程序呼叫插件
工单回调与开放能力	工单系统 / 工单回调与开放能力	工单推送、条件接口、触发器、SLA 和异步条件回调
企微事件与卡片	企微管理 / 小程序卡片接入	小程序卡片 postMessage 和企微账号事件 URL
系统动态枚举	系统设置 / 自定义字段 / 自定义字段对接	自定义字段动态枚举的企业侧接口格式约定

调用方向

场景	调用方向	说明
企业调用七鱼 OpenAPI	企业服务器 -> 七鱼服务器	企业在请求中携带 `appKey`、`time`、`checksum` 等鉴权参数。
企业提供 HTTP 接口	七鱼服务器或七鱼工作台 -> 企业服务器	企业在七鱼后台配置 URL，七鱼按业务场景发起请求或推送事件。
企业嵌入页面	七鱼工作台浏览器 -> 企业页面	通常是 iframe 加载，适合展示企业侧页面，不是 JSON API。

鉴权方式

OpenAPI checksum

企业调用七鱼 OpenAPI 时，通常使用通用说明 - 七鱼签名中的数据校验规则：

checksum = SHA1(appSecret + md5 + time)
md5 = MD5(请求体原文).toLowerCase()
time = 秒级时间戳

企业接口 token

CRM 信息和订单信息接口通常支持 token 模式。企业在七鱼后台配置 appId、appSecret 和获取 token 的接口，七鱼获取 token 后在后续业务请求中携带 appid、token 等参数。

企业接口 header checkSum

机器人服务先知、一触即达等场景使用 header 签名：

checkSum = SHA1(appSecret + nonce + time)
time = 秒级时间戳
nonce = 随机字符串

事件 URL 验证 checksum

在线实时消息推送保存 URL 时，企业需要校验 query 参数，并在 1 秒内直接返回解密后的明文字符串。返回内容不要包 JSON、不要加引号、不要带 BOM 或换行。

CORS 要求

如果企业接口由七鱼工作台浏览器直接调用，例如 CRM 用户信息、订单信息或部分 iframe 扩展能力，企业接口需要同时处理 OPTIONS 预检和 POST 请求。

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://{corpCode}.qiyukf.com

响应约定

企业侧接口的响应结构以具体业务页面为准。实现时请特别注意：

业务页面要求返回纯文本时，不要包 JSON。

业务页面要求返回 JSON 时，字段名、类型和枚举值需要严格按页面说明返回。

URL 验证、事件推送、机器人动态内容、工单条件接口等场景的超时要求不同，请以对应业务页面为准。

如果业务页面给出了错误码或兜底响应，企业侧接口应按对应规则返回，避免七鱼侧无法识别失败原因。