> ## 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`

## 请求参数

`Content-Type: multipart/form-data`

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

## 响应参数

| 字段 | 是否必填 | 类型 | 字段说明 |
| - | - | - | - |
| `key` | 是 | String | 对象存储 Key，**7 天有效**，进件提交时与 `category` 搭配引用（如 `14f3a7e4-3a4a-46ac-8276-d78e075a16fb`） |
| `file_name` | 是 | String | 文件名（含扩展名），原样返回 |
| `file_size` | 是 | int64 | 文件大小（字节） |
| `file_type` | 是 | String | 文件类型（扩展名），如 `jpg` |

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

## 图片类型编码表

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

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

## 示例

**请求**

```bash theme={"system"}
curl -X POST 'https://gw.xft.xin/openapi/v1/merchant/file/upload' \
  -H 'Client-Id: your_app_key' \
  -H 'Signature-Type: HmacSHA256' \
  -H 'Timestamp: 1755234000' \
  -H 'Nonce-Str: 9f8e7d6c5b4a39281706f5e4d3c2b1a0' \
  -H 'Signature: <签名字符串>' \
  -F 'file=@/path/to/license.jpg' \
  -F 'category=1' \
  -F 'remark=营业执照'
```

**响应**

```json theme={"system"}
{
  "key": "14f3a7e4-3a4a-46ac-8276-d78e075a16fb",
  "file_name": "license.jpg",
  "file_size": 1048576,
  "file_type": "jpg"
}
```

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.