API Overview

The file upload capability involves 2 steps (2 API requests):

1. Generate a file upload credential for subsequent file upload operations.
2. Use the file upload credential to upload the file (the requested URL and parameters are the return values from step 1).

1. Generate File Upload Credential

Request Description

Request Method: POST + application/json Request Path: https://${Enter your cloud domain name}/cgi/crm/v2/generatorFileUploadCredential?thirdTraceId=${random string}Request Headers: Refer to Common Parameters

Request Parameters

Parameter	Type	Required	Description
data	Map	Yes	Data MAP
expireTime	integer	Yes	Validity period of the credential from the current time, in seconds. Minimum 60 seconds, maximum 604800 seconds (7 days)
resourceType	string	Yes	File resource type. N: Enterprise formal file, stored long-term by default, no expiration; TN: Enterprise temporary file, expires in 3 days by default (automatically converted from temporary to formal when saved to business data)
isStreamUpload	boolean	Yes	Whether it is streaming upload. true: streaming upload; false: non-streaming upload (form upload)
filename	string	Yes	Full file name, must include the extension. Note: The file name will be automatically URL-encoded; when filename is empty, defaults to YYYY-MM-DD-HH + extension; when the file name contains characters not supported by URL encoding, the default file name is used
extension	string	Yes	File extension, without a dot. When extension is empty, defaults to bin; when the file name's own extension is inconsistent with extension, extension takes precedence
fileSize	integer	Yes	File size in bytes. Value range [1, 104857600]

Request Example

{
  "data": {
    "expireTime": 3600,
    "resourceType": "N",
    "isStreamUpload": false,
    "filename": "reading-comprehension.docx",
    "extension": "docx",
    "fileSize": 73072455
  }
}

Response Description

Response Parameters

Parameter	Type	Description
traceId	string	Unique request ID
errorCode	integer	Status code
errorMessage	string	Error message
data	object	Response data, see the table below for specific fields
method	string	Upload request method
url	string	Upload URL
acid	string	Upload authentication header parameter
resource	string	Resource type
ak	string	Upload authentication header parameter
sign	string	Upload signature
expiry	integer	Signature expiration timestamp (milliseconds)
filename	string	URL-encoded file name
size	integer	File size (bytes)
digest	string	File digest
contentType	string	Content-Type during upload

Response Example

Success Response:

{
  "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. Upload File

Request Method: POST + multipart/form-data (or application/octet-stream for streaming upload) Request Path: The url in the data returned from step 1 + ?traceId=[random string]&linkId=[traceId returned from step 1]Request Headers:

Parameter	Type	Required	Description
acid	string	Yes	The acid from the data returned in step 1
resource	string	Yes	The resource from the data returned in step 1
ak	string	Yes	The ak from the data returned in step 1
sign	string	Yes	The sign from the data returned in step 1
expiry	string	Yes	The expiry from the data returned in step 1
filename	string	Yes	The filename from the data returned in step 1
size	string	Yes	The size from the data returned in step 1
digest	string	Yes	The digest from the data returned in step 1
Content-Type	string	Yes	multipart/form-data (or application/octet-stream for streaming upload)

Request Parameters

Parameter	Type	Required	Description
facishareFile	file	Yes	The file to upload

Important Notes:

1. One upload file corresponds to one signature, which cannot be reused.
2. The size and type of the file to be uploaded must strictly match the information used to generate the signature.
3. The data returned in step 1 serves as header parameters for the upload and must not be modified.

Except for method and url, all other fields are request header parameters. contentType requires special handling — the header key should be Content-Type.

Examples

Form Upload

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'

Streaming Upload (Recommended)

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'

Upload Response

Upload Success

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

Upload Failure

{
    "success": false,
    "code": 400,
    "message": "Signature has expired",
    "data": null
}

Notes

• The trailing / in the upload URL path must not be removed; the request uses strict matching mode
• You can add the traceId parameter after the URL for troubleshooting and tracking, e.g. ?traceId=E-E.71554.1000-10882367
• Files must be uploaded via form, and the form field name must be facishareFile
• Only one file is accepted per request (other form fields will be ignored)
• For form upload, browsers or APIs generally default Content-Type to multipart/form-data; it is recommended to pass it manually to prevent behavior changes from affecting the business (except for WeChat Mini Programs)
• For streaming upload, Content-Type must be explicitly set to application/octet-stream, and the file must be uploaded as a binary stream