纷享销客开发者手册

简体中文

English

CRM文件上传

约 1286 字大约 4 分钟

2026-06-16

接口概述

文件上传能力包括2步：

  1. 生成文件上传凭证，用于后续文件上传操作。
  2. 使用文件上传凭证，进行文件上传。

请求说明

请求方式：POST + application/json
请求路径：https://${填入所在云的域名}/cgi/crm/v2/generatorFileUploadCredential?thirdTraceId=${随机字符串}
请求头填写：参考公共参数填写

请求参数

参数类型是否必填说明
tenantIdinteger是企业ID
expireTimeinteger是凭证从当前时间起有效时间，单位秒。最小为 60 秒，最大为 604800 秒（7 天）
resourceTypestring是文件资源类型。N：企业正式文件，默认长期保存，无过期时间；TN：企业临时文件，默认 3 天过期（保存到业务数据中时会自动触发临时转正式）
isStreamUploadboolean是是否为流式上传。true：流式上传；false：非流式上传（表单上传）
filenamestring是完整文件名，需携带扩展名。注：会自动对文件名进行 URL 编码；filename 为空时默认为 YYYY-MM-DD-HH + 扩展名；文件名中包含不支持 URL 编码的字符时同样使用默认文件名
extensionstring是文件扩展名，不需要带点号。extension 为空时默认为 bin；当文件名本身扩展名与 extension 不一致时，以 extension 为准
fileSizeinteger是文件大小，单位 byte。取值范围 [1, 104857600]

请求示例

{
  "tenantId": 71554,
  "expireTime": 3600,
  "resourceType": "N",
  "isStreamUpload": false,
  "filename": "阅读理解.docx",
  "extension": "docx",
  "fileSize": 73072455
}

返回说明

返回参数

参数类型说明
successboolean请求是否成功
codeinteger状态码
messagestring状态信息
dataobject返回数据，具体字段见下表

data 字段说明：

参数类型说明
methodstring上传请求方式
urlstring上传地址
acidstring上传认证头参数
resourcestring资源类型
akstring上传认证头参数
signstring上传签名
expiryinteger签名过期时间戳（毫秒）
filenamestringURL 编码后的文件名
sizeinteger文件大小（byte）
digeststring文件摘要
contentTypestring上传时的 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"
  }
}

文件上传凭证使用说明

注意：

  1. 一个上传文件对应一个签名，不可重复使用。
  2. 要上传的文件大小、类型必须严格与生成签名的信息匹配。
  3. 下发的全部签名信息作为上传时的 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 丢失