接口标准文档

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 /webapi/lite_api/v1/iam/user/{user_id}
请求参数：

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

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

请求示例：

GET /webapi/lite_api/v1/iam/user/234567 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 /webapi/lite_api/v1/iam/user/
请求参数：

参数名类型必须说明
username string 是用户名
real_name string 是真实姓名
is_aad boolean 是是否为 AAD 域账号
is_superuser boolean 是是否超级管理员账号
avatar string 是用户头像

参数名	类型	必须	说明
username	string	是	用户名
real_name	string	是	真实姓名
is_aad	boolean	是	是否为 AAD 域账号
is_superuser	boolean	是	是否超级管理员账号
avatar	string	是	用户头像

请求示例：

{
    "username": "string",
    "real_name": "string",
    "is_aad": false,
    "is_superuser": false,
    "avatar": ""
}

响应示例：

{
    "code": 200,
    "data": {
        "username": "string",
        "email": "",
        "real_name": "string",
        "nickname": "",
        "is_superuser": false,
        "avatar": "",
        "enable": true,
        "id": "0000046446975123456",
        "is_aad": false,
        "serial_number": "",
        "created_at": "2026-07-21T09:02:18.709790",
        "updated_at": "2026-07-21T09:02:18.709607",
        "last_login": null,
        "roles": [],
        "user_roles": [],
        "organizations": [],
        "gender": 0,
        "birthday": null,
        "wechat": "",
        "region": "",
        "time_difference": 8,
        "join_time": null,
        "office_phone": "",
        "mobile_phone": "",
        "description": ""
    },
    "message": "success"
}

5.3 接口3：创建助手

接口路径：POST /webapi/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：获取助手信息

接口路径：GET /webapi/lite_api/v2/api/robot/{robot_id}
认证方式：HTTP Bearer 认证。
- 请求头：Authorization: Bearer {token}（必填）
路径参数：

参数名类型必填说明
robot_id UUID 是机器人唯一标识

参数名	类型	必填	说明
robot_id	UUID	是	机器人唯一标识

请求示例：

GET /webapi/lite_api/v2/api/robot/a1b2c3d4-5678-90ef-ghij-klmnopqrstuv HTTP/1.1
Authorization: Bearer YOUR_BEARER_TOKEN_HERE

响应示例（200）：

{
    "code": 200,
    "data": {
        "info": {
            "name": "示例机器人",
            "id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv",
            "avatar_url": "https://example.com/avatar.png",
            "description": "这是一个示例机器人",
            "prompt": "你是一个智能助手",
            "prologue": "欢迎使用示例机器人",
            "robot_type": "chat",
            "product_position": "assistant"
        },
        "masks": [],
        "knowledge_bases": [],
        "skills": [],
        "mcps": [],
        "data_sources": [],
        "keywords_filter": null,
        "feedback_accounts": []
    },
    "message": "success"
}

5.5 接口5：上传文件

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

参数名	类型	必须	说明
Files	array	是	本次上传的文件
WorkspaceId	string	是	string
fullPath	string	否	文件要上传到的完整路径

响应示例：

{
    "code": 200,
    "data": [
        {
            "id": "000060269455675392",
            "fullName": "String",
            "scan_status": {}
        }
    ],
    "message": "文件上传成功"
}

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

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

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

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

请求示例：

GET /webapi/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 /webapi/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 /webapi/knowledge/v1/kb/knowledge-base/{kb_id}
请求参数：

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

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

请求示例：

GET /webapi/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 /webapi/knowledge/v1/file/ekb-folder
请求参数：

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

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

请求示例：

POST /webapi/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 /webapi/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.11 接口11：预览知识库文件

接口路径：GET /webapi/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 /webapi/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.12 接口12：下载知识库文件

接口路径：POST /webapi/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.13 接口13：创建问答

接口路径：POST /webapi/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.14 接口14：获取问答列表

接口路径：POST /webapi/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"
}

5.15 接口15：QnA 列表查询

接口路径：POST /webapi/lite_api/v2/api/qa_list
认证方式：HTTP Bearer 认证。
- 请求头：Authorization: Bearer {token}（必填）

请求参数（JSON Body）：

参数名	类型	必须	说明
query	string	是	搜索查询词
k	integer	否	返回的顶级结果数量
knowledge_ids	array[string]\| null	否	指定搜索的知识库 ID 列表
search_mode	string	否	搜索模式：`hybrid` / `embedding` / `text`
qa_score	number	是	QA 阈值
llm_use	boolean	否	是否使用大模型处理
metadata	string	否	元数据处理方式：`none` / `filter` / `weight`

请求示例：

{
    "query": "如何使用API进行图片上传",
    "k": 20,
    "knowledge_ids": [
        "kb123",
        "kb456"
    ],
    "search_mode": "hybrid",
    "qa_score": 1,
    "llm_use": false,
    "metadata": "none"
}

响应示例（200）：

{
    "code": 200,
    "data": [
        {
            "metadata": null,
            "documentid": "doc_001",
            "chunkid": "chunk_001",
            "filename": "api-guide.pdf",
            "content": "上传接口支持 multipart/form-data",
            "score": 0.95,
            "rank_score": 0.91,
            "question": "如何使用API进行图片上传",
            "timestamp": "2026-07-21T09:30:00Z",
            "url": null,
            "type": "QA"
        }
    ],
    "message": "qa retrieved successfully"
}

验证错误示例（422）：

{
    "code": 422,
    "data": {
        "detail": []
    },
    "message": "Validation Error"
}

状态码说明：
- 200：请求成功，返回 IResponseModel[QAResponseList]
- 422：参数校验错误，返回

5.16 接口16：外部知识库检索

接口路径：POST /webapi/lite_api/v2/api/retrieval
接口说明：用于连接团队内独立维护的知识库，适配 Dify 对接及交付二次开发。
认证方式：HTTP Bearer 认证。
- 请求头：Authorization: Bearer {API_KEY}（必填）

请求参数（JSON Body）：

参数名	类型	必须	说明
knowledge_id	string	是	知识库唯一 ID
query	string	是	用户查询内容
retrieval_setting	object	是	检索参数配置
metadata_condition	object	否	元数据筛选条件（当前预留，不生效）

retrieval_setting 字段说明：

参数名	类型	必须	说明
top_k	integer	是	返回的最大结果数
score_threshold	number	是	相关性阈值，范围 0~1
search_type	string	否	检索模式：`hybrid` / `embedding` / `text`，默认 `hybrid`
hybridpipeline	UUID	否	高级编排 pipeline ID

请求示例：

{
    "knowledge_id": "your-knowledge-id",
    "query": "你的问题",
    "retrieval_setting": {
        "top_k": 2,
        "score_threshold": 0.5
    }
}

响应示例（200）：

{
    "records": [
        {
            "metadata": {
                "Url": "{host}/knowledge-webapi/#/share/preview?fileId=4534399061070970880&objectType=2&previewType=file&mode=login",
                "FileName": "demo.pdf",
                "FileId": "4534399061070970880",
                "FilePath": "/",
                "Created": "2026-01-21T05:23:02.2404442Z",
                "page": 5
            },
            "score": 0.61544959,
            "title": "demo.pdf",
            "content": "Dify：GenAI 应用程序的创新引擎"
        }
    ]
}

常见错误：
- 403：AccessDeniedException，缺少访问权限。
- 500：InternalServerException，服务器内部错误。
- 业务错误码如下：

error_code	说明
1001	Authorization 头格式无效（应为 `Bearer <api-key>`）
1002	授权失败

说明：该接口受产品权限控制，仅可验证权限，无法校验知识库是否存在。超管传入不存在的知识库 ID 时，通常返回空结果。

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：QnA 列表查询​

5.16 接口16：外部知识库检索​

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：QnA 列表查询

5.16 接口16：外部知识库检索

6. 安全规范