⌘K

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

适用于完整创作台嵌入场景的 SaaS 基础版接入流程，涵盖应用创建、OAuth 授权、SaaS URL 获取与页面嵌入。

接入总览

组件版接入（返回编辑器链接）

📘 一、准备工作

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

注册登录韦尼克平台，并完成企业认证 & 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": ""
}

步骤四：通过 access_token 获取 SaaS URL 地址

接口地址：

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

请求参数说明：

Header

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer access_token	Bearer xxxxx

响应参数

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

响应示例

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

步骤五（可选）：刷新 access_token

refresh_token 有效期为 30 天。有效期内可以凭 refresh_token 调用 API 刷新 OAuth Access Token。

接口地址：

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

请求参数说明：

Header

创建 SaaS 应用后获取 refresh_token，调用刷新接口时放入 Authorization 头中。

参数名	类型	描述	示例值
Authorization	string	Authorization - Bearer refresh_token	Bearer xxxxx

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

Body

参数	类型	必填	说明
app_id	String	Y	应用 ID，在韦尼克平台创建 SaaS 应用后获得
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 'Content-Type: application/json' \
--header 'Authorization: Bearer ******' \
--data-raw '{
    "app_id":"*****"
}'

响应参数

参数	说明
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": ""
}

📌 常见问题（FAQ）

Q1：app_id 从哪里获取？

请在韦尼克平台“创建应用”后，在配置信息中获取。

Q2：code_challenge 和 code_verifier 要自己生成吗？

是的。前端或后端需要自行实现，或调用标准库进行计算。

Q3：用户 A 在 SaaS 页面中的生成 PPT 记录，其他用户也能看到吗？

如果未接入用户管理，文档创作台的记录可能是共享的。可以参考用户管理 API 做子用户隔离。

Q4：什么是安全域名？安全域名怎么设置？

安全域名是指在 OAuth 授权流程中，客户端允许使用的域名。

例如，假设你的前端应用部署在 https://b.yoo-ai.com/ 上，就需要将该地址添加到应用配置和步骤二的 redirect_uri 中。

这样，只有从该域名发起的授权请求才会被接受，其他域名的请求会被拒绝。

注意事项

应用级 Token 与 OAuth access_token 不是同一个概念
redirect_uri 必须与平台配置的安全域名保持一致
SaaS URL 具有时效性
如果只需要独立编辑器能力，建议改看组件版接入（返回编辑器链接）