简体中文
CRM文件上传
约 1286 字大约 4 分钟
2026-06-16
接口概述
文件上传能力包括2步:
- 生成文件上传凭证,用于后续文件上传操作。
- 使用文件上传凭证,进行文件上传。
请求说明
请求方式:POST + application/json
请求路径:https://${填入所在云的域名}/cgi/crm/v2/generatorFileUploadCredential?thirdTraceId=${随机字符串}
请求头填写:参考公共参数填写
请求参数
| 参数 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| tenantId | integer | 是 | 企业ID |
| expireTime | integer | 是 | 凭证从当前时间起有效时间,单位秒。最小为 60 秒,最大为 604800 秒(7 天) |
| resourceType | string | 是 | 文件资源类型。N:企业正式文件,默认长期保存,无过期时间;TN:企业临时文件,默认 3 天过期(保存到业务数据中时会自动触发临时转正式) |
| isStreamUpload | boolean | 是 | 是否为流式上传。true:流式上传;false:非流式上传(表单上传) |
| filename | string | 是 | 完整文件名,需携带扩展名。注:会自动对文件名进行 URL 编码;filename 为空时默认为 YYYY-MM-DD-HH + 扩展名;文件名中包含不支持 URL 编码的字符时同样使用默认文件名 |
| extension | string | 是 | 文件扩展名,不需要带点号。extension 为空时默认为 bin;当文件名本身扩展名与 extension 不一致时,以 extension 为准 |
| fileSize | integer | 是 | 文件大小,单位 byte。取值范围 [1, 104857600] |
请求示例
{
"tenantId": 71554,
"expireTime": 3600,
"resourceType": "N",
"isStreamUpload": false,
"filename": "阅读理解.docx",
"extension": "docx",
"fileSize": 73072455
}返回说明
返回参数
| 参数 | 类型 | 说明 |
|---|---|---|
| success | boolean | 请求是否成功 |
| code | integer | 状态码 |
| message | string | 状态信息 |
| data | object | 返回数据,具体字段见下表 |
data 字段说明:
| 参数 | 类型 | 说明 |
|---|---|---|
| method | string | 上传请求方式 |
| url | string | 上传地址 |
| acid | string | 上传认证头参数 |
| resource | string | 资源类型 |
| ak | string | 上传认证头参数 |
| sign | string | 上传签名 |
| expiry | integer | 签名过期时间戳(毫秒) |
| filename | string | URL 编码后的文件名 |
| size | integer | 文件大小(byte) |
| digest | string | 文件摘要 |
| contentType | string | 上传时的 Content-Type |
返回示例
成功响应:
{
"success": true,
"code": 200,
"message": "success",
"data": {
"method": "POST",
"url": "https://img.ceshi112.com/FilesOne/",
"acid": "71554.-10000",
"resource": "N",
"ak": "n2Fy3DIBhPDsAyykctKWkDh8",
"sign": "iCU_DOJv02r3ZW7HCtJjhpJ81iY=",
"expiry": 1761835831788,
"filename": "%E9%98%85%E8%AF%BB%E7%90%86%E8%A7%A3.docx",
"size": 73072455,
"digest": "QsB5kG2np97wHDHAc_H8lg==",
"contentType": "multipart/form-data"
}
}文件上传凭证使用说明
注意:
- 一个上传文件对应一个签名,不可重复使用。
- 要上传的文件大小、类型必须严格与生成签名的信息匹配。
- 下发的全部签名信息作为上传时的 header 参数,不可修改。
除 method 和 url 外,其余字段均为请求头参数。contentType 需要特殊处理,header key 应为 Content-Type。
表单上传
curl --request POST 'https://img.ceshi112.com/FilesOne/?traceId=E-E.71554.1000-10882367' \
--header 'acid: 71554.-10000' \
--header 'resource: TC' \
--header 'ak: 8ko2UvJ2ScCiPm57W1lvGuGu' \
--header 'sign: iq1kQ2aP36NfDJVn9MLV11XIUxY=' \
--header 'expiry: 1712074007625' \
--header 'filename: %E7%BA%B7%E4%BA%AB%E5%B0%8F%E8%9C%9C%E8%9C%82.webp' \
--header 'size: 45047' \
--header 'digest: hh_8bCLjBdA67SYwmW0HIA==' \
--header 'Content-Type: multipart/form-data' \
--form 'facishareFile=@/your-file-path/your-file-name.webp'流式上传(推荐)
curl --request POST 'https://img.ceshi112.com/FilesOne/?traceId=E-E.71554.1000-10882367' \
--header 'acid: 71554.-10000' \
--header 'resource: TC' \
--header 'ak: 8ko2UvJ2ScCiPm57W1lvGuGu' \
--header 'sign: iq1kQ2aP36NfDJVn9MLV11XIUxY=' \
--header 'expiry: 1712074007625' \
--header 'filename: %E7%BA%B7%E4%BA%AB%E5%B0%8F%E8%9C%9C%E8%9C%82.webp' \
--header 'size: 45047' \
--header 'digest: hh_8bCLjBdA67SYwmW0HIA==' \
--header 'Content-Type: application/octet-stream' \
--data-binary '@/your-file-path/your-file-name.webp'网页上传示例
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>File Upload Example</title>
</head>
<body>
<h1>File Upload Example</h1>
<form id="uploadForm">
<input type="file" id="fileInput" name="file">
<button type="submit">Upload</button>
</form>
<script>
document.getElementById('uploadForm').addEventListener('submit', function(event) {
event.preventDefault();
var fileInput = document.getElementById('fileInput');
if (fileInput.files.length === 0) {
alert('Please select a file.');
return;
}
var myHeaders = new Headers();
myHeaders.append("acid", "71554.-10000");
myHeaders.append("resource", "TC");
myHeaders.append("ak", "8ko2UvJ2ScCiPm57W1lvGuGu");
myHeaders.append("sign", "kEbEH7yDjkgxEqz1jTOfMwifjNs=");
myHeaders.append("expiry", "1715937477938");
myHeaders.append("filename", "%E7%BA%B7%E4%BA%AB%E5%B0%8F%E8%9C%9C%E8%9C%82.webp");
myHeaders.append("size", "45047");
myHeaders.append("digest", "kXwWIm49Bk8xreU8n_yW-g==");
var formdata = new FormData();
formdata.append("facishareFile", fileInput.files[0], "纷享小蜜蜂.webp");
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: formdata,
redirect: 'follow'
};
fetch("https://img.ceshi112.com/FilesOne/", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
});
</script>
</body>
</html>微信小程序上传
wx.uploadFile({
url: 'https://img.ceshi112.com/FilesOne/?traceId=E-E.71554.1000-10882367',
filePath: tempFilePaths[0],
name: "facishareFile",
header: {
"acid": "71554.-10000",
"resource": "TC",
"ak": "8ko2UvJ2ScCiPm57W1lvGuGu",
"sign": "iq1kQ2aP36NfDJVn9MLV11XIUxY=",
"expiry": "1712074007625",
"filename": "%E7%BA%B7%E4%BA%AB%E5%B0%8F%E8%9C%9C%E8%9C%82.webp",
"size": "45047",
"digest": "hh_8bCLjBdA67SYwmW0HIA==",
},
success(res) {
const data = res.data
this.setData({
"userInfo.avatarUrl": data.url,
})
}
})上传响应
上传成功
{
"success": true,
"code": 200,
"message": "success",
"data": "TN_7c1fabc747264f4a9e0ae7301430df18"
}{
"success": true,
"code": 200,
"message": "success",
"data": "N_202508_12_1f77e9c19dbf466h866d4b14ce68a30d"
}上传失败
{
"success": false,
"code": 400,
"message": "签名已过期",
"data": null
}注意事项
- 上传地址 URL 路径后的
/不可去除,请求为严格匹配模式 - 可以在 URL 后添加
traceId参数便于排查和追踪问题,如?traceId=E-E.71554.1000-10882367 - 文件需以表单形式上传,表单项属性名必须为
facishareFile - 一次仅接收一个文件(其他表单项均不会处理)
- 表单上传浏览器或 API 一般会默认指定
Content-Type为multipart/form-data,建议手动传递防止行为变更影响业务(微信小程序除外) - 流式上传时必须显式指定
Content-Type为application/octet-stream,文件需以二进制流的形式上传 - 微信小程序上传不可显式指定
Content-Type,仅传递示例中的 Header 头即可,显式指定会导致 boundary 丢失
