⌘K

SaaS组件版接入指南

功能扩展API相关文档与使用指南

基础版接入（完整业务流程）

用户体系与事件回调

📘 一、准备工作

接入前，请先在韦尼克平台完成以下操作：

注册登录韦尼克平台，并完成企业认证 & Token 获取方式
创建一个 SaaS 应用（智能 PPT）

获取 app_id 和应用级 Token，并填入安全域名（对接地址的安全域名，以保证对接的安全性）

🔐 二、授权机制概述（OAuth + PKCE）

PKCE（Proof Key for Code Exchange）是一种 OAuth 2.0 的安全增强机制。相比传统授权流程，它能防止授权码被中间人拦截。

流程核心逻辑：

客户端生成 code_verifier，派生出 code_challenge 并发起授权请求
获取 code 后用 code_verifier 换取 access_token
使用 access_token 获取 SaaS URL 地址

🚦 三、完整授权流程

步骤一：生成临时密钥

客户端需生成一个随机字符串 code_verifier，并按如下方式计算出 code_challenge：

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

📌 通常推荐使用 SHA-256 算法，并使用 Base64URL 编码。

Python 示例：

# 生成随机 code_verifier
code_verifier = base64.urlsafe_b64encode(os.urandom(64)).rstrip(b'=').decode('utf-8')
 
# 生成 code_challenge（SHA256 + Base64URL 编码）
code_challenge = base64.urlsafe_b64encode(
    hashlib.sha256(code_verifier.encode('utf-8')).digest()
).rstrip(b'=').decode('utf-8')

步骤二：跳转用户进行授权

接口地址：

GET https://saas.api.yoo-ai.com/oauth/authorize

请求参数说明：

Header

应用级 Token 在准备工作中获取。创建 SaaS 应用后，可在配置信息中查看。

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer Token	Bearer Yoo-xxxxxxxxx

Query

参数	类型	必填	说明
app_id	String	Y	应用 ID，在韦尼克平台创建 SaaS 应用后获得
response_type	string	Y	固定为 `code`
state	string	Y	客户端生成的随机字符串，用于防止 CSRF（随机填写即可）
code_challenge	string	Y	步骤一生成的 `code_challenge`
redirect_uri	string	Y	安全域名，授权成功后跳转地址，需与应用配置一致

示例请求：

curl --location --request GET 'https://saas.api.yoo-ai.com/oauth/authorize?app_id=8295936608&response_type=code&state=*****&code_challenge=*****&redirect_uri=https://b.yoo-ai.com'

返回结果

HTTP 302 重定向至授权页，用户完成授权后跳转至你配置的 redirect_uri，URL 中携带参数：

https://b.yoo-ai.com/?code=*****&state=*****

📌 请注意：应从跳转后的 redirect_uri 中提取 code 参数。

步骤三：通过 code 获取 access_token

接口地址：

POST https://saas.api.yoo-ai.com/oauth/token

请求参数说明：

Header

应用级 Token 在准备工作中获取。创建 SaaS 应用后，可在配置信息中查看。

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer Token	Bearer Yoo-xxxxxxxxx

参数名	取值	说明
Content-Type	application/json	请求正文格式

Body

参数	类型	必填	说明
code	String	Y	上一步授权回调中获取的 `code` 参数
app_id	String	Y	应用 ID，在韦尼克平台创建 SaaS 应用后获得
code_verifier	String	Y	第一步生成的原始随机字符串
expire_date	Int	N	令牌过期时间（单位：Unix 秒时间戳，默认 86400 秒，即 1 天）
union_id	string	N	子用户 ID，相关说明可参考用户管理 API

示例请求：

curl --location --request POST 'https://saas.api.yoo-ai.com/oauth/token' \
--header 'User-Agent: Apifox/1.0.0 (https://apifox.com)' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ******' \
--header 'Accept: */*' \
--header 'Host: saas.api.yoo-ai.com' \
--header 'Connection: keep-alive' \
--data-raw '{
    "code":"*****",
    "app_id":"*****",
    "code_verifier":"******"
}'

响应参数

参数	说明
access_token	调用 API 所需的访问令牌
refresh_token	用于刷新 `access_token`（30 天有效）
expire_date	访问令牌过期时间，格式为 Unix time 时间戳，精度为秒

示例响应：

{
  "code": 200,
  "msg": "success",
  "data": {
    "access_token": "******",
    "refresh_token": "*****",
    "expire_date": 1754550781,
    "union_data": null
  },
  "request_id": ""
}

组件版功能选择

功能一：上传 JSON 文件 → 获取编辑器地址

接口地址：

POST https://saas.api.yoo-ai.com/saas/api/editor-ppt

请求参数：

Header

Authorization: Bearer {{access_token}}

Content-Type: application/json
Body

字段	类型	必填	说明
json_url	String	Y	授权码，即终端用户授权后，页面重定向的 URL 中 code 参数的值。
ref_url	String	Y	返回设置URL。

响应参数：

字段	类型	说明
saas_ppt	String	SaaS访问url地址。（单次使用生效，重新使用需使用ppt_id再次请求）
ppt_id	string	该份PPT的标识

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "saas_ppt": "https://ppt.yoo-ai.com/editor?code=f8Cutded3b",
        "ppt_id": "r6hfbHj9Dy"
    },
    "request_id": "YOO-saas68f5a15a48038"
}

获取历史PPT在线编辑链接

通过ppt_id可以重新获取编辑链接。该链接将加载PPT的内容，且内容为最后一次手动保存时的版本。

接口地址：

POST https://saas.api.yoo-ai.com/saas/api/editor-ppt

请求参数：

Header

Authorization: Bearer {{access_token}}

Content-Type: application/json
Body

字段	类型	必填	说明
ppt_id	string	Y	ppt标识

响应参数：

字段	类型	说明
saas_ppt	String	SaaS访问url地址。（单次使用生效，重新使用需使用ppt_id再次请求）
ppt_id	string	该份PPT的标识

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "saas_ppt": "https://ppt-test.yoo-ai.com/editor?code=33PbBZKarp",
        "ppt_id": "r6hfbHj9Dy"
    },
    "request_id": "YOO-saas68f743a2078e2"
}

功能二：Markdown → 获取编辑器地址

接口地址：

POST https://saas.api.yoo-ai.com/saas/api/md-ppt

请求参数：

Header

Authorization: Bearer {{access_token}}

Content-Type: application/json
Body

字段	类型	必填	说明
text	string	Y	Markdown数据

响应参数：

字段	类型	说明
saas_ppt	String	SaaS访问url地址。（单次使用生效，重新使用需再次请求）

响应示例：

{
    "code": 200,
    "msg": "success",
    "data": {
        "saas_ppt": "https://index.ppt.yoo-ai.com?code=Qv2CY6s3Tm"
    },
    "request_id": ""
}

辅助接口：查询 PPT 生成记录

接口地址：

POST https://saas.api.yoo-ai.com/saas/api/history

请求参数：

Header

Authorization: Bearer {{access_token}}

Content-Type: application/json
Body

字段	类型	必填	说明
page	Number	Y	页数
page_size	Number	Y	每页返回数

请求示例：

{
    "page":5,
    "page_size":10
}

响应参数：

字段	类型	说明
ppt_list	Array	PPT生成记录列表，包含每个记录的详细信息。
current_page	Number	当前页数
total	Number	总条数
last_page	Number	最后一页数

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "ppt_list": [
      {
        "title": "海滨儿童游乐区设计",
        "created_at": "2025-07-04 15:59:18",
        "app_id": "",
        "uid": ""
      },
      {
        "title": "海滨亲子乐园设计",
        "created_at": "2025-07-03 19:03:57",
        "app_id": "",
        "uid": ""
      }
    ],
    "current_page": 1,
    "total": 197,
    "last_page": 20
  },
  "request_id": "YOO-saas68a7dba6015e5"
}

📌 常见问题（FAQ）

Q1：为什么生成的编辑器地址是一次性的？

出于安全考虑，生成的 saas_ppt 有效期较短，需重新获取。

Q2：支持哪些输入方式？

目前支持 JSON 文件 和 Markdown 文本 两种方式生成 PPT 编辑器。

Q3：是否支持在线重新编辑？

支持在线重新编辑。只需记录每份PPT的 ppt_id，通过该ID可以重新获取编辑链接。该链接将加载PPT的内容，且内容为最后一次手动保存时的版本。