接口标准文档

1. 文档信息

文档名称：SERVICEME系统接口标准文档
版本号：v1.1
发布日期：2026-06-05
适用范围：适用于企业智能化场景，支持身份认证、知识问答、流程自动化、数据分析与内容生成等功能。接口采用标准 RESTful 架构，便于系统集成与跨平台应用，广泛用于客服、营销、财务、人力资源等业务模块，提升协同效率与智能决策能力。

2. 修订记录

版本号	修订日期	修订内容
v1.0	2025-07-18	初稿
v1.1	2026-06-05	新增跨域访问规范（CORS）说明

3. 概述

3.1 文档目的

说明文档的目标，例如：

本文档定义了SERVICEME系统的接口规范，包括请求格式、响应格式、错误码等，供调用方参考。

3.2 术语与缩写

API：应用程序接口
HTTP：超文本传输协议
JSON：JavaScript对象表示法
RESTful：一种API设计风格

3.3 接口设计原则

遵循RESTful风格（如适用）。
使用HTTPS协议保证安全性。
数据格式统一为JSON。
接口版本化管理（如/v1/xxx）。

4. 通用规范

4.1 请求规范

请求方法：GET/POST/PUT/DELETE等。
请求头（Headers）：
- Content-Type: application/json
- Authorization: Bearer {token}（如需要认证）。
请求参数：
- Query参数（GET）、Body参数（POST/PUT）。
- 必填/可选字段说明。

4.2 响应规范

响应格式：

{
  "code": 200,       // 状态码
  "message": "成功",  // 描述信息
  "data": {}         // 返回数据（可选）
}

HTTP状态码：
- 200：成功
- 400：请求参数错误
- 401：未授权
- 500：服务器内部错误

4.3 错误码表

错误码	含义	解决方案建议
200	成功	-
422	参数错误	-
40001	参数缺失	检查必填字段
50001	服务器内部错误	联系管理员

4.4 跨域访问规范（CORS）

4.4.1 背景

跨源资源共享是浏览器的安全机制，用于控制网页是否允许向不同域名的服务器发起请求。当前端应用与 API 服务部署在不同域名（或端口）时，浏览器会自动执行 CORS 校验。

4.4.2 NEXT 版本默认策略

SERVICEME NEXT 版本默认不允许跨域访问。即：当浏览器端页面直接请求 API 时，若请求的 Origin 未经服务端配置允许，请求将被拒绝。

4.4.3 与 LTS 版本的差异

对比项	LTS 版本	NEXT 版本
跨域限制	无限制（未对跨域做任何拦截）	默认禁止跨域访问
迁移影响	—	从 LTS 迁移至 NEXT 后，若此前依赖浏览器端跨域调用 API，将出现请求失败

迁移注意：如果您的系统从 LTS 升级到 NEXT，且存在前端跨域调用接口的场景，升级后这些请求将无法正常工作，需要提前申请跨域配置。

4.4.4 解决方式

如需开启跨域访问，请联系您对应的交付团队进行配置。交付团队将根据您的业务场景配置允许的来源域名。

4.4.5 常见现象

当遇到跨域问题时，浏览器开发者工具（Console）中通常会出现以下错误信息：

Access to XMLHttpRequest at 'https://api.xxx.com/...' from origin 'https://your-app.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

如果在浏览器控制台看到上述类似错误，说明当前请求受到跨域策略限制，请联系交付团队处理。

5. 接口详情

5.1 接口1：获取用户信息

接口路径：GET /lite_api/v1/iam/user/{user_id}
请求参数：

参数名类型必填说明
userId Path 是用户ID

参数名	类型	必填	说明
userId	Path	是	用户ID

请求示例：

GET /v1/iam/user/293456 HTTP/1.1
Authorization: Bearer abcdef123456

响应示例：

{
    "code": 200,
    "data": {
        "username": "string",
        "email": "string",
        "real_name": "",
        "nickname": "",
        "is_superuser": false,
        "avatar": "",
        "enable": true,
        "id": "string",
        "is_aad": false,
        "serial_number": "string",
        "created_at": "2019-08-24T14:15:22.123Z",
        "updated_at": "2019-08-24T14:15:22.123Z",
        "last_login": "2019-08-24T14:15:22.123Z",
        "roles": [],
        "user_roles": [],
        "organizations": [],
        "gender": 0,
        "birthday": "2019-08-24T14:15:22.123Z",
        "wechat": "string",
        "region": "string",
        "time_difference": 0,
        "join_time": "2019-08-24T14:15:22.123Z",
        "office_phone": "string",
        "mobile_phone": "string",
        "description": "string"
    },
    "message": "success"
}

5.2 接口2：创建用户

接口路径：POST /lite_api/v1/iam/user/
请求参数：

参数名类型必须说明
username string 是用户名
email string 是邮箱
real_name string 是真实姓名

参数名	类型	必须	说明
username	string	是	用户名
email	string	是	邮箱
real_name	string	是	真实姓名

请求示例：

{
    "username": "string",
    "email": "",
    "real_name": "",
}

响应示例：

{
    "username": "string",
    "email": "string",
    "real_name": "",
}

5.3 接口3：创建助手

接口路径：POST /lite_api/v1/robots/

请求参数：

参数名	类型	必须	说明
info	object	是	助手信息及名称
masks	array	否	助手面具
knowledge_bases	array	否	知识库
skills	array	否	技能
mcps	array	否	数据模型
data_sources	array	否	数据源
keywords_filter	object	否	关键词过滤
feedback_accounts	array	否	反馈帐号

请求示例：

{
    "info": {
        "name": "string",
        "weight": 0,
        "avatar_url": "string",
        "description": "",
        "prompt": "string",
        "prologue": "string",
        "robot_type": "",
        "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
        "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
        "product_position": "chat-x",
        "chat_rounds": 0,
        "user_id": "string",
        "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
        "split_type": "string",
        "load_type": "string",
        "spliter_json": "string",
        "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
        "user_skill_auths": [
            null
        ],
        "need_summary": true,
        "force_execute": true,
        "open_filter": true,
        "record_chat": true,
        "is_published": true,
        "category_ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ],
        "recommend_question": false,
        "feedback": false,
        "knowledge_config": {
            "search_mode": "hybrid",
            "k": 5,
            "doc_score": 0.7,
            "qa_score": 0.8,
            "metadata": "none",
            "show_reference": false
        },
        "editable": true,
        "question_guide": false,
        "operator_execute": false,
        "bi_config": {
            "query_rewrite": false,
            "divide_think": false
        }
    },
    "masks": [
        {
            "mask_set_id": "d0bee2ed-0859-4bb6-8598-f64d47a5a28b"
        }
    ],
    "knowledge_bases": [
        {
            "classification_id": "string",
            "classification_name": "string",
            "classification_icon": "string",
            "workspaces": []
        }
    ],
    "skills": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "mcps": [],
    "data_sources": [
        {
            "skill_group_id": "85161907-67ae-4ae2-8fee-99b7d6fcc3f8"
        }
    ],
    "keywords_filter": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
        "key_words": [
            "string"
        ],
        "review_input": true,
        "preset_reply_input": "string",
        "review_output": true,
        "preset_reply_output": "string"
    },
    "feedback_accounts": []
}

响应示例

{
    "code": 200,
    "data": null,
    "message": "success"
}

5.4 接口4：获取助手

接口路径：POST /lite_api/v1/robots/{robot_id}
请求参数：

参数名	类型	必须	说明
robot_id	string	是	助手ID
internal_use	boolean	否	是否内部使用

请求示例：

GET /lite_api/v1/robots/00001 HTTP/1.1
Authorization: Bearer abcdef123456

响应示例：

{
    "code": 200,
    "data": {
        "info": {
            "name": "string",
            "weight": 0,
            "avatar_url": "string",
            "description": "",
            "prompt": "string",
            "prologue": "string",
            "robot_type": "",
            "flow_id": "ef710584-0706-4b4b-b481-dd44a4541137",
            "cluster_group_id": "921cd751-fc17-4b9d-a7ec-91a434beaf0a",
            "product_position": "chat-x",
            "chat_rounds": 0,
            "user_id": "string",
            "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
            "split_type": "string",
            "load_type": "string",
            "spliter_json": "string",
            "embedding_id": "18e0b745-2b45-46cb-a826-bc9049d1152c",
            "user_skill_auths": [
                null
            ],
            "need_summary": true,
            "force_execute": true,
            "open_filter": true,
            "record_chat": true,
            "is_published": true,
            "category_ids": [
                "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ],
            "recommend_question": false,
            "feedback": false,
            "knowledge_config": {
                "search_mode": "hybrid",
                "k": 5,
                "doc_score": 0.7,
                "qa_score": 0.8,
                "metadata": "none",
                "show_reference": false
            },
            "editable": true,
            "question_guide": false,
            "operator_execute": false,
            "bi_config": {
                "query_rewrite": false,
                "divide_think": false
            },
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "manageable": false
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "robot_id": "8fe44936-b905-428b-ace5-566f232fcce8",
            "key_words": [
                "string"
            ],
            "review_input": true,
            "preset_reply_input": "string",
            "review_output": true,
            "preset_reply_output": "string"
        },
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 接口5：上传文件

接口路径：POST /Api/Workspace/File/UploadFiles
请求参数：

参数名	类型	必须	说明
Files	array	否	本次上传的文件
WorkspaceId	string	否	string
FullPath	string	否	文件要上传到的完整路径
IsCover	boolean	否	是否系统上传
UserId	integer	否	用户id (用于公开api)
UserEmail	string	否	用户邮箱(用于公开api)
OCRMode	string	否	OCR模式

响应示例：

{
    "success": true,
    "msg": "string",
    "data": [
        {
            "workspaceId": 0,
            "fullName": "string",
            "id": 0
        }
    ]
}

5.6 接口6：获取知识库列表

接口路径：GET /knowledge/v1/kb/me
请求参数：

参数名类型必填说明
locale Header 否语言区域，默认 en-US

参数名	类型	必填	说明
locale	Header	否	语言区域，默认 `en-US`

请求示例：

GET /knowledge/v1/kb/me HTTP/1.1
Authorization: Bearer abcdef123456
locale: zh-CN

响应示例：

{
        "code": 200,
        "data": [
                {
                        "id": "kb_001",
                        "name": "产品知识库",
                        "description": "用于存放产品说明、FAQ和操作手册",
                        "mode": 1
                }
        ],
        "message": "success"
}

5.7 接口7：创建知识库

接口路径：POST /knowledge/v1/kb/knowledge-base

请求参数：

参数名	类型	必须	说明
name	array	是	知识库名称，多语言数组
description	array	是	知识库描述，多语言数组
sort	integer	否	排序值
quota	object	否	知识库容量配置
parent_id	string	否	父级知识库ID
mode	integer	否	知识库模式，默认 `1`

请求示例：

{
        "name": [
                {
                        "locale": "zh-CN",
                        "content": "客户服务知识库"
                }
        ],
        "description": [
                {
                        "locale": "zh-CN",
                        "content": "用于维护客服问答和业务文档"
                }
        ],
        "sort": 0,
        "mode": 1
}

响应示例：

{
        "code": 200,
        "data": {
                "id": "kb_001",
                "name": "客户服务知识库"
        },
        "message": "success"
}

5.8 接口8：获取知识库详情

接口路径：GET /knowledge/v1/kb/knowledge-base/{kb_id}
请求参数：

参数名类型必填说明
kb_id Path 是知识库ID
locale Header 否语言区域，默认 en-US

参数名	类型	必填	说明
kb_id	Path	是	知识库ID
locale	Header	否	语言区域，默认 `en-US`

请求示例：

GET /knowledge/v1/kb/knowledge-base/kb_001 HTTP/1.1
Authorization: Bearer abcdef123456
locale: zh-CN

响应示例：

{
        "code": 200,
        "data": {
                "id": "kb_001",
                "name": "客户服务知识库",
                "description": "用于维护客服问答和业务文档",
                "mode": 1,
                "sort": 0
        },
        "message": "success"
}

5.9 接口9：创建知识库文件夹

接口路径：POST /knowledge/v1/file/ekb-folder
请求参数：

参数名类型必须说明
workspaceId Query 是所属知识库ID
name string 是文件夹名称
fullPath string 是文件夹完整路径

参数名	类型	必须	说明
workspaceId	Query	是	所属知识库ID
name	string	是	文件夹名称
fullPath	string	是	文件夹完整路径

请求示例：

POST /knowledge/v1/file/ekb-folder?workspaceId=1001 HTTP/1.1
Authorization: Bearer abcdef123456
Content-Type: application/json

{
        "name": "产品手册",
        "fullPath": "/客户资料/产品手册"
}

响应示例：

{
        "code": 200,
        "data": {
                "id": 501,
                "name": "产品手册",
                "fullPath": "/客户资料/产品手册"
        },
        "message": "success"
}

5.10 接口10：获取知识库目录树

接口路径：POST /knowledge/v1/file/ekb-folder-tree
请求参数：

参数名类型必须说明
workspaceId integer 是所属知识库ID
ignore_folder_ids array 否需要忽略的目录ID列表

参数名	类型	必须	说明
workspaceId	integer	是	所属知识库ID
ignore_folder_ids	array	否	需要忽略的目录ID列表

请求示例：

{
        "workspaceId": 1001,
        "ignore_folder_ids": [
                999
        ]
}

响应示例：

{
        "code": 200,
        "data": [
                {
                        "id": 501,
                        "name": "客户资料",
                        "children": [
                                {
                                        "id": 502,
                                        "name": "产品手册"
                                }
                        ]
                }
        ],
        "message": "success"
}

5.11 接口11：获取知识库文件列表

接口路径：POST /knowledge/v1/file/ekb-pagelist

请求参数：

参数名	类型	必须	说明
PageIndex	integer	否	页码，默认 `1`
PageSize	integer	否	每页数量，默认 `20`
OrderField	string	否	排序字段，默认 `modified`
OrderType	string	否	排序方式，默认 `desc`
Conditions	array	否	查询条件列表

请求示例：

{
        "PageIndex": 1,
        "PageSize": 20,
        "OrderField": "modified",
        "OrderType": "desc",
        "Conditions": [
                {
                        "fieldName": "workspaceId",
                        "fieldValue": "1001"
                }
        ]
}

响应示例：

{
        "code": 200,
        "data": {
                "items": [
                        {
                                "id": 7001,
                                "name": "产品介绍.pdf",
                                "objectType": 1,
                                "modified": "2026-05-17T10:00:00Z"
                        }
                ],
                "total": 1
        },
        "message": "success"
}

5.12 接口12：预览知识库文件

接口路径：GET /knowledge/v1/file/ekb-preview
请求参数：

参数名类型必填说明
c Query 是容器名称
n Query 是文件名或 Blob 名称
u Query 是用户ID
s Query 否来源系统，默认 ecm
w Query 否水印用户ID

参数名	类型	必填	说明
c	Query	是	容器名称
n	Query	是	文件名或 Blob 名称
u	Query	是	用户ID
s	Query	否	来源系统，默认 `ecm`
w	Query	否	水印用户ID

请求示例：

GET /knowledge/v1/file/ekb-preview?c=docs&n=abc123%2F产品介绍.pdf&u=10001&s=ecm HTTP/1.1
Authorization: Bearer abcdef123456

响应示例：

{
        "previewUrl": "https://example.com/preview/abc123",
        "expireAt": "2026-05-17T12:00:00Z"
}

5.13 接口13：下载知识库文件

接口路径：POST /knowledge/v1/file/download
请求参数：

参数名类型必须说明
fileId integer 是文件ID
objectType integer 是对象类型

参数名	类型	必须	说明
fileId	integer	是	文件ID
objectType	integer	是	对象类型

请求示例：

{
        "fileId": 7001,
        "objectType": 1
}

响应示例：

{
        "downloadUrl": "https://example.com/download/7001",
        "fileName": "产品介绍.pdf"
}

5.14 接口14：创建问答

接口路径：POST /knowledge/v1/qna

请求参数：

参数名	类型	必须	说明
answer	string	是	标准答案
enable	boolean	否	是否启用，默认 `true`
workspaceId	integer	是	所属知识库ID
questions	array	是	问题列表
metadataExpansion	object	否	扩展元数据

请求示例：

{
        "answer": "请登录系统后进入“我的申请”查看审批进度。",
        "enable": true,
        "workspaceId": 1001,
        "questions": [
                {
                        "content": "如何查看我的申请进度？",
                        "sort": 0
                }
        ]
}

响应示例：

{
        "code": 200,
        "data": {
                "id": 9001,
                "workspaceId": 1001,
                "enable": true
        },
        "message": "success"
}

5.15 接口15：获取问答列表

接口路径：POST /knowledge/v1/qna/pagelist

请求参数：

参数名	类型	必须	说明
PageIndex	integer	否	页码，默认 `1`
PageSize	integer	否	每页数量，默认 `20`
OrderField	string	否	排序字段，默认 `modified`
OrderType	string	否	排序方式，默认 `desc`
Conditions	array	否	查询条件列表

请求示例：

{
        "PageIndex": 1,
        "PageSize": 20,
        "OrderField": "modified",
        "OrderType": "desc",
        "Conditions": [
                {
                        "fieldName": "workspaceId",
                        "fieldValue": "1001"
                }
        ]
}

响应示例：

{
        "code": 200,
        "data": {
                "items": [
                        {
                                "id": 9001,
                                "question": "如何查看我的申请进度？",
                                "answer": "请登录系统后进入“我的申请”查看审批进度。",
                                "enable": true
                        }
                ],
                "total": 1
        },
        "message": "success"
}

6. 安全规范

认证方式：OAuth2.0/JWT/API Key。
数据加密：敏感字段需加密传输（如密码）。

限流策略：接口调用频率限制参考下表。

场景	常见限制	说明
开放API（如第三方调用）	10~100 次/分钟	例如微信支付、支付宝开放API通常限制50~200次/分钟（具体看接口等级）。
内部系统API	100~1000 次/分钟	内部服务间调用可放宽，但需避免单服务过度占用资源。
用户行为接口	5~60 次/分钟	例如登录、短信发送等敏感操作，需严格限制（如短信验证码接口通常限制1次/60秒）。
数据查询接口	100~5000 次/分钟	高频查询接口可适当放宽，但需配合缓存降低数据库压力。
高并发核心接口	动态限流（如令牌桶算法）	例如电商秒杀接口，可能结合熔断机制和弹性伸缩。

接口标准文档

1. 文档信息​

2. 修订记录​

3. 概述​

3.1 文档目的​

3.2 术语与缩写​

3.3 接口设计原则​

4. 通用规范​

4.1 请求规范​

4.2 响应规范​

4.3 错误码表​

4.4 跨域访问规范（CORS）​

4.4.1 背景​

4.4.2 NEXT 版本默认策略​

4.4.3 与 LTS 版本的差异​

4.4.4 解决方式​

4.4.5 常见现象​

5. 接口详情​

5.1 接口1：获取用户信息​

5.2 接口2：创建用户​

5.3 接口3：创建助手​

5.4 接口4：获取助手​

5.5 接口5：上传文件​

5.6 接口6：获取知识库列表​

5.7 接口7：创建知识库​

5.8 接口8：获取知识库详情​

5.9 接口9：创建知识库文件夹​

5.10 接口10：获取知识库目录树​

5.11 接口11：获取知识库文件列表​

5.12 接口12：预览知识库文件​

5.13 接口13：下载知识库文件​

5.14 接口14：创建问答​

5.15 接口15：获取问答列表​

6. 安全规范​

1. 文档信息

2. 修订记录

3. 概述

3.1 文档目的

3.2 术语与缩写

3.3 接口设计原则

4. 通用规范

4.1 请求规范

4.2 响应规范

4.3 错误码表

4.4 跨域访问规范（CORS）

4.4.1 背景

4.4.2 NEXT 版本默认策略

4.4.3 与 LTS 版本的差异

4.4.4 解决方式

4.4.5 常见现象

5. 接口详情

5.1 接口1：获取用户信息

5.2 接口2：创建用户

5.3 接口3：创建助手

5.4 接口4：获取助手

5.5 接口5：上传文件

5.6 接口6：获取知识库列表

5.7 接口7：创建知识库

5.8 接口8：获取知识库详情

5.9 接口9：创建知识库文件夹

5.10 接口10：获取知识库目录树

5.11 接口11：获取知识库文件列表

5.12 接口12：预览知识库文件

5.13 接口13：下载知识库文件

5.14 接口14：创建问答

5.15 接口15：获取问答列表

6. 安全规范