图片上传 - 星富通科技有限公司

功能说明

进件所需证件图片（营业执照、法人身份证、门店照片等）通过本接口上传，平台返回对象存储 Key（key），进件提交时以 category + key 引用即可。

请求体为 multipart/form-data，文件字段 file，单张 ≤ 5MB；
仅支持图片扩展名：.jpg .jpeg .png；
key 7 天内有效，过期需重新上传；
上传时指定 category（附件类别编码），平台据此定位图片用途并校验必传图片的完整性。

请求方式：POST 请求路径：/openapi/v1/merchant/file/upload 请求域名：https://gw.xft.xin/openapi

请求参数

Content-Type: multipart/form-data

字段	是否必选	类型	字段说明
`file`	是	File	图片文件（`.jpg`/`.jpeg`/`.png`），单张 ≤ 5MB，扩展名见上方白名单
`category`	是	String	附件类别编码，见下方图片类型编码表
`remark`	否	String	备注

响应参数

字段	是否必选	类型	字段说明
`key`	是	String	对象存储 Key，7 天有效，进件提交时与 `category` 搭配引用（如 `f_20260815A1B2C3`）
`file_name`	是	String	文件名（含扩展名），原样返回
`file_size`	是	int64	文件大小（字节）
`file_type`	是	String	文件类型（扩展名），如 `jpg`

图片仅保存 7 天，进件提交务必在有效期内完成，否则需重新上传。

图片类型编码表

category 取值为平台附件类别编码；上传时指定 category，进件提交时以 category + key 引用（见商户进件提交）。不同商户主体 / 结算主体必传的图片不同：

category	图片说明	必传场景
`1`	营业执照	企业/个体工商户必传
`2`	法人身份证正面	必传
`3`	法人身份证反面	必传
`4`	联系人身份证正面	联系人不复用法人时必传
`5`	联系人身份证反面	联系人不复用法人时必传
`6`	门店内景照	必传
`7`	门头照	必传
`8`	银行卡正面照	对私结算必传
`9`	工作人员与商户负责人合影	选填
`10`	商户协议	选填（线下签约时）
`11`	开户许可证	对公结算必传
`12`	其他补充资料	选填
`13`	非法人结算授权书	企业非法人结算必传
`14`	结算人身份证正面	选填
`15`	结算人身份证反面	选填
`16`	证书照片	选填
`17`	单位证明函	事业单位/政府必传
`22`	统一社会信用代码证书	事业单位/政府/小微/其他必传
`99`	其他	选填

示例

请求

curl -X POST 'https://gw.xft.xin/openapi/v1/merchant/file/upload' \
  -H 'Client-Id: your_app_key' \
  -H 'Signature-Type: HMAC-SHA256' \
  -H 'Timestamp: 1755234000' \
  -H 'Nonce-Str: abc123' \
  -H 'Signature: <签名字符串>' \
  -F 'file=@/path/to/license.jpg' \
  -F 'category=1' \
  -F 'remark=营业执照'

响应

{
  "key": "f_20260815A1B2C3",
  "file_name": "license.jpg",
  "file_size": 1048576,
  "file_type": "jpg"
}

失败示例（参数错误）

{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[category]",
  "metadata": {}
}

签名规则与其他接口一致：Body 为 multipart/form-data 原始请求报文（签名时使用完整请求体，不进行任何解析），见签名验签说明。文件超过 5MB 或扩展名不在白名单内，返回 400 INVALID_UPLOAD_FILE_TYPE / INVALID_UPLOAD_FILE_NAME。

​功能说明

​请求参数

​响应参数

​图片类型编码表

​示例

功能说明

请求参数

响应参数

图片类型编码表

示例