上传文件
POST/openapi/v1/files/upload
上传文档文件，获取 FileId 供创建信封时引用。
- 单次最多上传 20 个文件，结果顺序与请求一致
- FileId 有效期 24 小时，过期须重新上传
- 支持格式：
pdf/doc/docx/xls/xlsx/html/jpg/jpeg/png/bmp/txt - 大小限制：图片（jpg / jpeg / png / bmp）≤ 10 MB；其他文档 ≤ 60 MB
- 非 PDF 源文件（如 xlsx / docx / html 等）需先调用创建文件转换任务转成 PDF 后再用于创建信封
请求参数
Header 参数
Authorization必填string
Bearer <access_token>
X-Operator-User-Id选填string
操作用户 ID。授权码模式下无需传（自动使用授权用户）；客户端凭据模式下可选，不填时使用系统用户 ID。
Body 请求体
application/jsonFiles必填array<object>
文件列表，至少 1 个，最多 20 个
FileName必填string
文件名，须包含扩展名，例如 contract.pdf
FileBody必填string
文件内容，Base64 编码。支持格式：pdf / doc / docx / xls / xlsx / html / jpg / jpeg / png / bmp / txt。大小限制：图片（jpg / jpeg / png / bmp）≤ 10 MB；其他文档 ≤ 60 MB
请求示例
{
"Files": [
{
"FileName": "contract.pdf",
"FileBody": "JVBERi0xLjQK..."
},
{
"FileName": "appendix.pdf",
"FileBody": "JVBERi0xLjUK..."
}
]
}响应参数
Response.Data
Files选填array<object>
上传结果列表，顺序与请求中 Files 一致
FileName选填string
对应请求中的文件名
FileId选填string
文件资源 ID，有效期 24 小时，用于 CreateEnvelope 请求中引用
响应示例
{
"Response": {
"RequestId": "req-abc123",
"Error": null,
"Data": {
"Files": [
{
"FileName": "contract.pdf",
"FileId": "SGf1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6"
},
{
"FileName": "appendix.pdf",
"FileId": "SGf7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2"
}
]
}
}
}错误码
| 错误码 | 说明 |
|---|---|
OPENAPI.UPLOAD_FILES_REQUIRED | Files 列表为空 |
OPENAPI.UPLOAD_FILES_COUNT_EXCEEDS | Files 数量超过上限 20 |
OPENAPI.UPLOAD_FILE_NAME_REQUIRED | 某个文件的 FileName 为空 |
OPENAPI.UPLOAD_FILE_BODY_REQUIRED | 某个文件的 FileBody 为空 |
OPENAPI.UPLOAD_FILE_EXT_UNSUPPORTED | 不支持的文件扩展名（仅支持 pdf/doc/docx/xls/xlsx/html/jpg/jpeg/png/bmp/txt） |
OPENAPI.UPLOAD_FILE_BASE64_INVALID | FileBody 不是合法的 Base64 编码 |
FILE.TOO_LARGE | 文件超过大小限制（图片 ≤ 10MB，其他文档 ≤ 60MB） |
INTERNAL_ERROR | 服务内部错误（文件存储失败等） |