# 002 - 汇元商户文件上传 API

**接口名称：** `customer.file.upload`
**更新时间：** 2025-11-28
**状态：** 已实现

---

## 调用地址

| 环境 | 地址 |
|------|------|
| 生产 | `https://openapi.heepay.com/v1/customer/gateway` |
| 沙箱 | `http://openapi.heepaydev.com/v1/customer/gateway` |

与入网接口共用同一进件网关（`channels.heepay.merchant_url`）。

---

## 接口说明

上传图片/视频/文件，返回 `file_id`，供入网接口（001）中所有 `*_img` 字段使用。**必须先上传文件获取 `file_id`，再调用入网接口。**

---

## 请求业务参数（biz_content）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `file_content` | 文件内容 | 是 | ByteData | 文件二进制内容（Base64 编码后传入） |
| `file_sign` | 文件内容签名 | 是 | String | 文件内容的 MD5 值，用于校验文件完整性 |
| `file_media_type` | 文件类型 | 是 | String | 参照【文件类型编码】列表（待补充） |

---

## 响应业务参数

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `file_id` | 文件 ID | 否 | String | 上传成功后返回，传入入网接口的 `*_img` 字段 |

---

## 支持的文件格式

| 类型 | 格式 |
|------|------|
| 图片 | `png` / `bmp` / `gif` / `jpg` / `jpeg` |
| 视频 | `mp4` / `flv` / `avi` / `rm` / `rmvb` / `wav` |
| 文件 | `zip` / `rar` / `pdf` |

---

## 业务错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|---------|
| `invalid_parameter_file_type_not_correct` | 文件类型不正确 | 检查格式是否在支持列表内 |
| `invalid_parameter_file_size_too_big` | 文件过大 | 压缩后重新上传 |
| `invalid_parameter_file_sign_can_not_null` | 文件签名不能为空 | 传入 `file_sign`（MD5） |
| `invalid_parameter_file_sign_err` | 文件签名异常 | 确认文件是否损坏，重新计算 MD5 |
| `invalid_parameter_file_has_err` | file 有误，疑似被修改 | 检查文件完整性 |
| `invalid_parameter_file_need_ext` | 文件名需带扩展名 | 上传时文件名需包含扩展名 |
| `unknown_exception` | 系统未知问题 | 参考返回描述 |
| `unknown_error_gateway` | 网关系统不可用 | 稍后重试 |
| `invalid_auth` | 授权权限不足 | 检查签名/权限 |
| `missing_parameter` | 缺少参数 | 补充必填参数 |
| `invalid_parameter` | 无效参数 | 检查参数格式 |
| `invalid_request` | 无效请求 | 参考返回详细信息 |
| `biz_failure` | 业务错误 | 参照具体错误提示 |
| `service_not_exists` | 服务不存在 | 确认服务是否开通 |
| `service_time_out` | 系统繁忙 | 稍后重试 |
| `channel_error` | 通道系统异常 | 用相同参数重新调用 |

---

## 实现要点

1. **`file_content` 编码方式**：ByteData 类型，实现时需将文件二进制内容 Base64 编码后放入 `biz_content` JSON 字符串中
2. **`file_sign` 计算**：对原始文件二进制内容计算 MD5，得到 32 位小写十六进制字符串
3. **文件名带扩展名**：请求中需要携带文件名（含扩展名），具体字段名待联调确认
4. **调用顺序**：文件上传 → 获取 `file_id` → 入网申请（001），`file_id` 需持久化存储备用
5. **复用性**：同一文件可上传一次，`file_id` 在多个字段中复用（如法人正反面同一人时）

---

## 文件类型编码（file_media_type）

| 文件名称 | 类型值 |
|---------|--------|
| 营业执照 | `01` |
| 开户许可证/开户证明照 | `02` |
| 门头照 | `03` |
| 店内场景照 | `04` |
| 收银台照 | `05` |
| 法人身份证正面照 | `06` |
| 法人身份证反面照 | `07` |
| 联系人身份证正面照 | `08` |
| 联系人身份证反面照 | `09` |
| 公司大楼照 | `10` |
| 公司前台照 | `11` |
| 结算银行卡正面照 | `12` |
| 结算银行卡反面照 | `13` |
| 结算人手持银行卡正面照 | `14` |
| 经营者身份证正面照 | `15` |
| 经营者身份证反面照 | `16` |
| 经营者手持身份证正面照 | `17` |
| 经营者手持银行卡正面照 | `18` |
| 其它图片1 | `19` |
| 其它图片2 | `20` |
| 开户意愿视频 | `50` |
| 分账协议 | `52` |

> 对照入网接口（001）字段与文件类型的映射关系：
>
> | 入网字段 | file_media_type |
> |---------|----------------|
> | `subject_info.cert_img`（营业执照） | `01` |
> | `settlement_info.open_account_img`（开户许可证） | `02` |
> | `scene_info.shop_brand_img`（门头照/公司大楼照） | `03` 或 `10` |
> | `scene_info.customer_service_img`（收银台照/公司前台照） | `05` 或 `11` |
> | `scene_info.work_env_img`（店内场景照） | `04` |
> | `identity_info.cert_front_img`（法人证件正面） | `06` |
> | `identity_info.cert_back_img`（法人证件反面） | `07` |
> | `contact_info.cert_front_img`（联系人证件正面） | `08` |
> | `contact_info.cert_back_img`（联系人证件反面） | `09` |
> | `addition_info.open_merch_video`（开户意愿视频） | `50` |
> | `addition_info.sharing_protocol_img`（分账协议） | `52` |

---

## 待补充

- [ ] 文件大小限制（图片/视频各自上限）
- [ ] 文件名字段名称确认（`file_name`？）