# 001 - 汇元企业入网申请 API

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

---

## 调用地址

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

> 注意：进件网关地址与支付网关不同，对应 `config.yaml` 中的 `channels.heepay.merchant_url`。

---

## 接口说明

企业商户入网申请。所有 `*_img` 字段均需先调用**文件上传接口**（接口 002）获取 `file_id` 后传入。

---

## 请求业务参数（biz_content）

### 顶层字段

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `base_info` | 基础信息 | 是 | Object | 见下方 |
| `settlement_info` | 结算信息 | 是 | Object | 见下方 |
| `addition_info` | 补充信息 | 否 | Object | 见下方 |
| `subject_info` | 主体信息 | 是 | Object | 见下方 |
| `identity_info` | 法人信息 | 是 | Object | 见下方 |
| `contact_info` | 业务联系人信息 | 是 | Object | 见下方 |
| `ubo_infos` | 受益所有人信息 | 条件必填 | Object[] | 受益人非法人时必传 |
| `business_info` | 业务信息 | 是 | Object | 见下方 |

---

### base_info 基础信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `request_no` | 商户入网申请流水号 | 是 | String(64) | 商户自定义，全局唯一 |
| `alias_name` | 商户简称 | 是 | String(20) | 支付宝/微信支付页显示该名称 |
| `mcc` | 经营类目编码 | 是 | String(4) | 参照【经营类目编码】列表 |
| `service_phone` | 客服电话 | 是 | String | 客服电话 |
| `email` | 商户邮箱 | 是 | String(128) | 首次入网默认作为登录账号和联系人邮箱 |
| `notify_url` | 通知地址 | 否 | String(256) | 汇元主动通知的 http/https 回调地址 |

---

### settlement_info 结算信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `settle_type` | 结算类型 | 是 | String | `ACCOUNT`=结算到汇付宝账户，`BANK_CARD`=结算到银行卡 |
| `account_type` | 账户类型 | 是 | String | `PUBLIC`=对公，`PRIVATE`=对私；公司只支持对公，小微只支持对私 |
| `account_no` | 银行卡号 | 是 | String(35) | 银行卡号 |
| `account_name` | 开户名称 | 是 | String(32) | 开户名称 |
| `account_branch_no` | 开户支行联行号 | 是 | String(64) | 开户支行联行号 |
| `open_account_img` | 银行开户许可照 | 条件必填 | String(64) | 对公账号必传，传 `file_id` |
| `bank_name` | 银行名称 | 是 | String | 参照【银行列表】 |
| `region_code` | 银行卡省市区县编码 | 是 | String(6) | 参照省市编码列表 |

---

### addition_info 补充信息（选填）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `open_merch_video` | 开户意愿视频 | 否 | String | 传 `file_id` |
| `sharing_protocol_img` | 分账协议 | 否 | String | 传 `file_id` |
| `business_developer` | 业务开发者（拓展商户的业务员） | 否 | String(20) | 业务员姓名 |

---

### subject_info 主体信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `name` | 商户名称 | 是 | String(50) | 须与营业执照名称一致 |
| `cert_no` | 营业执照号 | 是 | String(32) | 营业执照号 |
| `region_code` | 营业执照区划编码 | 是 | String(32) | 传区县编码（通过行政区划查询接口获取） |
| `address` | 营业执照注册地址 | 是 | String(250) | 营业执照注册地址 |
| `cert_img` | 营业执照图片 | 是 | String | 传 `file_id` |
| `cert_expire` | 营业执照有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |

---

### identity_info 法人信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `name` | 姓名 | 是 | String(18) | 法人姓名 |
| `mobile` | 手机号 | 是 | String(11) | 法人手机号 |
| `cert_type` | 证件类型 | 是 | String | `ID_CARD`=大陆身份证，`HK_CARD`=港通行证，`MC_CARD`=澳通行证，`TW_CARD`=台通行证，`PASSPORT`=外籍护照 |
| `cert_no` | 证件号 | 是 | String(32) | 证件号码 |
| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
| `cert_front_img` | 证件正面照（人像面） | 是 | String | 传 `file_id` |
| `cert_back_img` | 证件反面照（非人像面） | 是 | String | 传 `file_id` |
| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
| `belong_ubo` | 受益人是否是法人 | 是 | Bool | `true`=是，`false`=否；为 false 时 `ubo_infos` 必传 |

---

### contact_info 业务联系人信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `name` | 姓名 | 是 | String(32) | 业务联系人姓名 |
| `mobile` | 手机号 | 是 | String(11) | 业务联系人手机号 |
| `cert_type` | 证件类型 | 是 | String | 同 `identity_info.cert_type` 枚举值 |
| `cert_no` | 证件号 | 是 | String(18) | 证件号码 |
| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
| `cert_front_img` | 证件正面照（人像面） | 是 | String(255) | 传 `file_id` |
| `cert_back_img` | 证件反面照（非人像面） | 是 | String(255) | 传 `file_id` |

---

### ubo_infos 受益所有人信息（受益人非法人时必传，数组）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `name` | 证件姓名 | 是 | String(64) | 受益所有人证件姓名 |
| `cert_type` | 证件类型 | 是 | String | 同 `identity_info.cert_type` 枚举值 |
| `cert_no` | 证件号码 | 是 | String(32) | 证件号码 |
| `nation` | 国籍类型 | 是 | Int | 参照【国家编码】列表 |
| `cert_expire` | 证件有效期 | 是 | String | 格式：`yyyy-MM-dd/yyyy-MM-dd`，长期有效传 `yyyy-MM-dd/forever` |
| `cert_address` | 证件地址 | 是 | String(255) | 受益所有人证件地址 |
| `rate` | 持股比例 | 是 | String | 以 % 为单位，传 1-100 的数字，如 `10` 表示占股 10% |

---

### business_info 业务信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `business_open_info` | 业务开通详情 | 是 | Object | 见下方 |

#### business_open_info

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `business_platform` | 业务平台 | 是 | String | `HEEPAY`=汇付宝，`HEELIFE`=汇生活 |
| `heepay_info` | 汇付宝信息 | 条件必填 | Object | `business_platform=HEEPAY` 时传入 |
| `heelife_info` | 汇生活信息 | 条件必填 | Object | `business_platform=HEELIFE` 时传入 |

#### heepay_info 汇付宝信息

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `operate_type` | 操作类型 | 是 | String | `OPEN_ORDINARY_MERCH`=开通普通户收单账户，`OPEN_BALANCE`=开通子户余额账户，`OPEN_MERCH`=开通子户收单账户，`APPEND_OPEN_PRODUCT`=补充开通产品；小微商户不支持 `OPEN_ORDINARY_MERCH` |
| `scene_info` | 场景信息 | 条件必填 | Object | 收单账户必传 |
| `heepay_ordinary` | 普通商户必须信息 | 条件必填 | Object | `operate_type=OPEN_ORDINARY_MERCH` 时必传 |
| `product_info` | 产品费率信息 | 条件必填 | Object | `operate_type=OPEN_MERCH` 或 `APPEND_OPEN_PRODUCT` 时必传 |
| `wechat_config` | 微信配置 | 否 | Object | 见下方 |
| `wechat_enter` | 微信进件参数 | 否 | Object | 需要指定微信进件参数时传入 |
| `alipay_enter` | 支付宝进件参数 | 否 | Object | 需要指定支付宝进件参数时传入 |

#### scene_info 场景信息（收单账户必传）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `shop_brand_img` | 商户品牌标识图片 | 是 | String | 企业传公司大楼照，个体/小微传门头照，传 `file_id` |
| `customer_service_img` | 客户服务照 | 是 | String | 企业传公司前台照，个体/小微传收银台照，传 `file_id` |
| `work_env_img` | 商户经营照 | 是 | String | 企业传内部办公场所照，个体/小微传店铺经营照，传 `file_id` |

#### heepay_ordinary 普通商户必须信息（operate_type=OPEN_ORDINARY_MERCH 时必传）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `app_type` | 应用类型 | 是 | String | `PC`，`APP`，`WAP`，`WECHAT_MINI`=微信小程序，`ALIPAY_MINI`=支付宝小程序，`WECHAT_PUBLIC_PLATFORM`=微信公众号，`QUICK_PASS`=云闪付，`OTHER`=其他线上场景 |
| `app_name` | 应用名称 | 是 | String | 应用名称 |
| `app_url` | 应用网址 | 条件必填 | String | `app_type` 为 PC/APP/WAP/WECHAT_MINI 时必填 |
| `app_download_url` | 应用下载地址 | 条件必填 | String | `app_type` 为 PC/APP/WAP/WECHAT_MINI 时必填 |
| `mini_app_id` | 小程序 APPID | 条件必填 | String | `app_type` 为 WECHAT_MINI/ALIPAY_MINI 时必填 |
| `app_status` | 应用状态 | 是 | String | `OFFLINE`=未上线，`ONLINE`=已上线公开，`ONLINE_SPECIAL`=已上线特定IP/用户开放 |
| `icp_url` | ICP 备案网址 | 条件必填 | String | `app_type` 为 PC/WAP 时必填 |
| `business_types` | 业务种类 | 是 | Object[] | 支持多个，见下方 `business_types` 结构 |
| `business_note` | 业务场景说明 | 是 | String | 业务场景说明 |

`business_types` 单条结构：

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `business_type` | 业务种类 | 是 | String | 见下方枚举值 |

`business_type` 枚举值：

| 枚举值 | 说明 |
|--------|------|
| `PURCHASE_VIRTUAL_GOODS` | 虚拟商品购买 |
| `PREPAID_ACCOUNT_CHARGE` | 预付费类账户充值 |
| `MATERIAL_CONSUMPTION` | 实物消费 |
| `AVIATION_BUSINESS_TRAVEL_EXPENSES` | 航空商旅消费 |
| `L_C_CONSUMPTION` | 生活及商业消费服务 |
| `OTHER_MERCH_CONSUMPTION` | 其他商户消费 |
| `PAYMENT_PUBLIC_UTILITIES` | 公共事业缴费 |
| `E_MEDICAL_PAYMENT` | 教育医疗缴费 |
| `GOVERNMENT_PAYMENT` | 政府服务缴费 |
| `PUBLIC_WELFARE_DONATION` | 公益捐款 |
| `OTHER_PUBLIC_SERVICES` | 其他公共服务 |
| `OTHER_FINANCIAL_PAYMENTS` | 其他金融付款 |
| `FUND_PURCHASE` | 基金购买 |
| `INSURANCE_PURCHASE` | 保险选购 |
| `WEALTH_MANAGE` | 投资理财 |
| `CREDIT_REPAYMENT` | 信贷偿还 |
| `CREDIT_CARD_REPAYMENTS` | 信用卡还款转出 |
| `RECHARGE_PAYMENT_ACCOUNT` | 支付账户充值 |
| `BANK_ACCOUNT_TRANSFER_OUT` | 银行账户转账转出 |
| `OTHER_ACCOUNT_CHARGE` | 其他账户充值 |
| `SERVICE_TYPE` | 服务类 |
| `SYSTEM_TYPE` | 系统类 |
| `MANAGE_TYPE` | 管理类 |
| `BID_BOND_PAYMENT` | 招投标保证金支付 |
| `OVERSEAS_SHOPPING` | 境外商品购买 |
| `business_img` | 经营服务图片 | 条件必填 | String | `app_type` 为 APP/WECHAT_MINI 时必填，传 `file_id` |
| `ext_a_img` ~ `ext_e_img` | 附件 1-5 | 否 | String | 传 `file_id` |

#### product_info 产品费率信息（operate_type=OPEN_MERCH 或 APPEND_OPEN_PRODUCT 时必传）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `reference_merch_id` | 标杆商户编码 | 条件必填 | Long | 与 `rate_infos` 二选一 |
| `rate_infos` | 费率列表 | 条件必填 | Object[] | 与 `reference_merch_id` 二选一 |

`rate_infos` 单条结构：

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `rate_code` | 支付场景编码 | 是 | String | 参照【支付场景】列表 |
| `rate_type` | 费率类型 | 是 | String(32) | `SINGLE_PERCENT`=单笔百分比，`SINGLE_FIXED`=单笔固定值 |
| `rate` | 费率值 | 是 | String(5) | 费率值 |

#### wechat_config 微信配置（选填）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `app_ids` | appId 列表 | 否 | Object[] | appId 列表 |
| `pay_urls` | 支付授权目录列表 | 否 | Object[] | 支付授权目录列表 |

#### wechat_enter 微信进件参数（选填）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `channel_code` | 进件渠道号 | 是 | String | 进件渠道号 |

#### alipay_enter 支付宝进件参数（选填）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `channel_code` | 进件渠道号 | 是 | String | 进件渠道号 |

#### heelife_info 汇生活信息（business_platform=HEELIFE 时传入）

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `operate_type` | 操作类型 | 是 | String | 指明业务类型（具体枚举值待补充） |

---

## 响应业务参数

| 字段 | 名称 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| `request_no` | 商户申请流水号 | 是 | String | 后续查询（接口 003）和修改（接口 004）时使用 |

---

## 业务错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|---------|
| `invalid_parameter_email_existed` | 汇元已存在此邮箱 | 更换邮箱 |
| `invalid_parameter_email_except` | 邮箱校验异常 | 检查参数 |
| `invalid_parameter_enterprise_type_ex` | 企业用户只支持对公账户 | 检查 `account_type` |
| `invalid_parameter_micro_type_ex` | 小微用户只支持对私账户 | 检查 `account_type` |
| `invalid_parameter_ubo_must_not_empty` | 受益人不能为空 | 传入 `ubo_infos` |
| `invalid_parameter_rate_must_not_empty` | 开通收单账户费率信息不能为空 | 检查 `product_info` |
| `invalid_parameter_common_must_not_empty` | 开通普通户必须信息不能为空 | 检查 `heepay_ordinary` |
| `invalid_parameter_mark_merch_not_existed` | 标杆商户未配置 | 联系汇元配置 |
| `business_fail_customer_has_passed` | 商户已入驻完毕 | 确认 `request_no` 是否已用过 |
| `business_fail_customer_waiting` | 入驻申请处理中 | 等待审核结果 |
| `business_fail_save_his_work_record_fail` | 迁移创建历史入驻工单失败 | 重试 |
| `business_fail_delete_his_work_record_fail` | 迁移删除历史入驻工单失败 | 重试 |
| `business_fail_save_work_record_fail` | 保存入驻记录失败 | 重试 |
| `unknown_exception` | 系统未知问题 | 参考返回描述 |
| `unknown_error_gateway` | 网关系统不可用 | 稍后重试 |
| `invalid_auth` | 授权权限不足 | 检查签名/权限 |
| `missing_parameter` | 缺少参数 | 补充必填参数 |
| `invalid_parameter` | 无效参数 | 检查参数格式 |
| `invalid_request` | 无效请求 | 参考返回详细信息 |
| `biz_failure` | 业务错误 | 参照具体错误提示 |
| `service_not_exists` | 服务不存在 | 确认服务是否开通 |
| `service_time_out` | 系统繁忙 | 稍后重试 |
| `channel_error` | 通道系统异常 | 用相同参数重新调用 |

---

## 实现要点

1. **网关地址**：使用 `channels.heepay.merchant_url`（进件网关），而非支付网关
2. **图片先传后用**：所有 `*_img` 字段均为 `file_id`，依赖接口 002（文件上传）
3. **受益人条件必填**：`identity_info.belong_ubo=false` 时，`ubo_infos` 数组必传
4. **operate_type 决定必填子结构**：
   - `OPEN_MERCH` / `APPEND_OPEN_PRODUCT` → `product_info` 必传
   - `OPEN_ORDINARY_MERCH` → `heepay_ordinary` 必传
   - 收单账户 → `scene_info` 必传
5. **费率二选一**：`product_info` 中 `reference_merch_id` 和 `rate_infos` 二选一
6. **返回 request_no**：作为查询（接口 003）和修改（接口 004）的入参，需持久化存储

---

## 待补充

- [ ] `heelife_info.operate_type` 枚举值（暂不支持汇生活，低优先级）
- [ ] `wechat_config.app_ids` 和 `pay_urls` 单条结构字段
- [ ] 省市区县编码（建议用行政区划查询接口在线获取，无需维护静态列表）

## 附录文档

- MCC 经营类目编码 → `appendix-mcc-codes.md`
- 银行列表 → `appendix-bank-codes.md`
- 国家编码 → `appendix-nation-codes.md`
- 支付场景编码 → `appendix-payment-scene-codes.md`