136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# 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`？）
|