文件上传接口

接口

HttpPost：api/FrontEnd/UploadFile

上传单个附件或图片文件，供外部表单调用。接口受系统 AuthorizationInterceptor 保护，必须使用有效登录令牌；上传成功后返回文件信息，可将该信息转换为附件或图片控件的字段值，再调用 api/FrontEnd/AddData 保存表单。

请求参数

请求使用 multipart/form-data，不能使用 JSON 请求体。

参数名	参数位置	类型	是否必填	说明
`Authorization`	Header	string	是	调用者身份凭据，传入已获取的 token。
`TnCode`	Header	string	是	租户编码。
`file`	FormData	file	是	要上传的单个文件。
`addWaterMark`	FormData	boolean	否	是否为可转换的文档添加水印，默认 `false`。
`formCode`	FormData	string	否	表单编码。与 `fieldCode` 一起传入时，接口会按附件控件的文件大小配置进行校验。
`fieldCode`	FormData	string	否	附件控件字段编码。仅对 `FileComponent` 生效。

请求示例

curl -X POST "https://<host>/api/FrontEnd/UploadFile" \
  -H "Authorization: Bearer <access-token>" \
  -H "TnCode: <tenant-code>" \
  -F "file=@/path/to/采购报价单.pdf" \
  -F "addWaterMark=false" \
  -F "formCode=46b97a76f61338bd" \
  -F "fieldCode=ContractFiles"

一次只上传一个文件。需要上传多个附件或多张图片时，请逐个调用该接口，然后将所有返回的文件信息组成数组写入表单字段。

返回结果

上传成功时返回 HTTP 200 和 FileInfo：

参数名	类型	说明
`FileId`	string	文件唯一标识。保存附件或图片时必须使用该值。
`FileName`	string	原始文件名。
`Md5`	string	文件摘要。
`Length`	long	文件大小，单位为字节。
`UploadDateTime`	datetime	上传时间。
`PdfId`	string	文档转换后的 PDF 文件 ID；未转换时为空。
`Type`	int	文件类型标识。
`Url`	string	文件访问地址；可能为空。
`CompressFileId`	string	压缩文件 ID；可能为空。

返回示例（成功）

{
  "FileName": "采购报价单.pdf",
  "FileId": "file-3d731bf0",
  "Md5": "d41d8cd98f00b204e9800998ecf8427e",
  "Length": 184320,
  "UploadDateTime": "2026-08-16T14:30:00",
  "PdfId": null,
  "Type": 1,
  "Url": null,
  "CompressFileId": null
}

写入 `AddData` 附件或图片字段

AddData.data 的字段值类型是 string。因此需将上传结果映射为小写的文件描述字段，并将数组 JSON 序列化为字符串：

{
  "ContractFiles": "[{\"fileId\":\"file-3d731bf0\",\"fileName\":\"采购报价单.pdf\",\"md5\":\"d41d8cd98f00b204e9800998ecf8427e\",\"size\":184320}]",
  "SiteImages": "[{\"fileId\":\"file-image-1\",\"fileName\":\"现场照片.jpg\",\"md5\":\"abc\",\"size\":204800}]"
}

其中 size 对应上传返回的 Length。附件和图片控件均使用这一文件描述数组格式。

返回示例（失败）

{
  "Code": 500,
  "Message": "上传文件超过控件限制20M",
  "ExceptionSeqNo": null,
  "Result": null,
  "Status": 3,
  "MessageShowType": null
}

调用说明

没有有效登录令牌时，认证拦截器返回 401 Unauthorized；接口不会接受匿名上传。
file 为空时返回：上传文件为空。
文件超过系统许可限制时返回：上传文件超过系统限制。
同时传入 formCode 和 fieldCode，且目标字段为附件控件时，会按该控件配置的最大文件大小限制校验；超过限制时返回：上传文件超过控件限制{n}M。
该接口只负责上传文件，不会自动将文件关联到表单数据。上传后仍需调用 api/FrontEnd/AddData、UpdateData 等接口写入附件或图片字段。

接口​

请求参数​

请求示例​

返回结果​

返回示例（成功）​

写入 AddData 附件或图片字段​

返回示例（失败）​

调用说明​

接口