接口概述

文件上传能力包括2步（请求2次接口）：

1. 生成文件上传凭证，用于后续文件上传操作。
2. 使用文件上传凭证，进行文件上传（请求的URL和参数是第1步的返回值）。

1. 生成文件上传凭证

请求说明

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

请求参数

参数	类型	是否必填	说明
data	Map	是	数据MAP
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]

请求示例

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

返回说明

返回参数

参数	类型	说明
traceId	string	唯一请求ID
errorCode	integer	状态码
errorMessage	string	错误信息
data	object	返回数据，具体字段见下表
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

返回示例

成功响应：

{
  "traceId": "E-O.fk.1002-20260714162904-ecceb5",
  "data": {
      "method": "POST",
      "url": "https://img.fxiaoke.com/FilesOne/",
      "acid": "776128.-10000",
      "resource": "N",
      "ak": "cHnCW2XXxxxxxxx",
      "sign": "iBkCxxxxxxlhc1og6VCiY=",
      "expiry": 1784017864276,
      "filename": "text.txt",
      "size": 100,
      "digest": "D-Zxxxxxx0IA==",
      "contentType": "multipart/form-data"
  },
  "errorDescription": "success",
  "errorMessage": "OK",
  "errorCode": 0
}

2. 上传文件

请求方式：POST + multipart/form-data（或者流式上传时为application/octet-stream）
请求路径：第1步中返回的data中的url + ?traceId=[随机字符串]&linkId=[第一步返回的traceId]请求头：

参数	类型	是否必填	说明
acid	string	是	第1步中返回的data中的acid
resource	string	是	第1步中返回的data中的resource
ak	string	是	第1步中返回的data中的ak
sign	string	是	第1步中返回的data中的sign
expiry	string	是	第1步中返回的data中的expiry
filename	string	是	第1步中返回的data中的filename
size	string	是	第1步中返回的data中的size
digest	string	是	第1步中返回的data中的digest
Content-Type	string	是	multipart/form-data（或者流式上传时为application/octet-stream）

请求参数

参数	类型	是否必填	说明
facishareFile	文件	是	要上传的文件

特别注意：

1. 一个上传文件对应一个签名，不可重复使用。
2. 要上传的文件大小、类型必须严格与生成签名的信息匹配。
3. 第1步返回的数据作为上传时的 header 参数，不可修改。

除 method 和 url 外，其余字段均为请求头参数。contentType 需要特殊处理，header key 应为 Content-Type。

示例

表单上传

curl --request POST '{url}?traceId=xxxxxx&linkId=E-O.fk.1002-20260714162904-ecceb5' \
  --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 '{url}' \
  --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'

上传响应

上传成功

{
    "success": true,
    "code": 200,
    "message": "success",
    "data": "TN_7c1fabc747264f4a9e0ae7301430df18"
}

上传失败

{
    "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，文件需以二进制流的形式上传