5.2 KiB
5.2 KiB
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 |
通道系统异常 | 用相同参数重新调用 |
实现要点
file_content编码方式：ByteData 类型，实现时需将文件二进制内容 Base64 编码后放入biz_contentJSON 字符串中file_sign计算：对原始文件二进制内容计算 MD5，得到 32 位小写十六进制字符串- 文件名带扩展名：请求中需要携带文件名（含扩展名），具体字段名待联调确认
- 调用顺序：文件上传 → 获取
file_id→ 入网申请（001），file_id需持久化存储备用 - 复用性：同一文件可上传一次，
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（营业执照）01settlement_info.open_account_img（开户许可证）02scene_info.shop_brand_img（门头照/公司大楼照）03或10scene_info.customer_service_img（收银台照/公司前台照）05或11scene_info.work_env_img（店内场景照）04identity_info.cert_front_img（法人证件正面）06identity_info.cert_back_img（法人证件反面）07contact_info.cert_front_img（联系人证件正面）08contact_info.cert_back_img（联系人证件反面）09addition_info.open_merch_video（开户意愿视频）50addition_info.sharing_protocol_img（分账协议）52
待补充
- 文件大小限制（图片/视频各自上限）
- 文件名字段名称确认（
file_name？）