> ## Documentation Index
> Fetch the complete documentation index at: https://opendocs.xft.xin/llms.txt
> Use this file to discover all available pages before exploring further.

# 图片上传

## 功能说明

进件所需证件图片（营业执照、法人身份证、门店照片等）通过本接口上传，平台返回对象存储 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`                                               |

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

## 图片类型编码表

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

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

## 示例

**请求**

```bash theme={null}
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=营业执照'
```

**响应**

```json theme={null}
{
  "key": "f_20260815A1B2C3",
  "file_name": "license.jpg",
  "file_size": 1048576,
  "file_type": "jpg"
}
```

**失败示例（参数错误）**

```json theme={null}
{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[category]",
  "metadata": {}
}
```

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