机构公共API文档

基础信息

基础路径: /api/institution

请求方式: 全部为 POST

Content-Type: application/json

鉴权方式: 签名验证（institution.verify 中间件）

公共请求参数

所有接口请求体均需包含以下公共参数：

参数名	类型	必填	说明
ins_no	string	是	机构编号
version	string	是	版本号，固定 `1.0`
nonce	string	是	随机字符串，最大32位
sign	string	是	签名，最大64位
data	object	是	业务参数对象

签名规则

将请求参数中 data 内的字段按 key 进行字典排序

将完整参数（不含 sign）转为 JSON 字符串（不转义斜杠和中文）

sign = strtoupper(md5(ins_secret + json_string))

公共响应格式

{
  "code": 200,
  "msg": "请求成功",
  "data": {}
}

1. 获取机构配置

路径: /api/institution/config/info

方法: POST

请求参数（data）

参数名	类型	必填	说明
ins_no	string	是	机构编号

响应示例(请做好兼容,不定期新增配置字段)

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "role": [
      { "name": "角色A", "levels": [{ "rate": "1", "level": 1, "roles": [3, 5] }], "role_id": 1, "role_type": 2 },
      { "name": "角色B", "levels": [{ "rate": "1", "level": 1, "roles": [4, 3, 2] }], "role_id": 2, "role_type": 1 }
    ],
    "agent": [
      { "name": "代理等级1", "rate": "0", "agent_id": 1, "area_code": [] },
      { "name": "代理等级2", "rate": "0", "agent_id": 2, "area_code": [] }
    ],
    "wallet": { "other": "0", "exchange_rate": "100", "exchange_time": "23:59" },
    "channel": [{ "key": 6, "name": "渠道名称", "remark": "渠道备注" }],
    "wx_app_id": "",
    "ali_app_id": "",
    "yun_switch": { "remark": "权益说明", "is_open": false, "channel_rate": "1", "community_rate": "1" },
    "channel_rate": "1",
    "service_rule": { "15": "20", "22": "27" },
    "is_yun_switch": false,
    "role_relation": [
      { "name": "角色名称", "value": 1, "ins_name": "机构角色名", "is_selected": true }
    ],
    "community_rate": "1",
    "withdraw_method": [
      { "name": "提现方式A", "value": 1 },
      { "name": "提现方式B", "value": 2 }
    ],
    "withdrawal_rule": {
      "rule": "<p>提现规则说明</p>",
      "type": "other",
      "other": 1,
      "day_min": 1,
      "day_top": 100000,
      "day_times": 5,
      "charge_from": 2,
      "service_charge": 10
    }
  }
}

2. 商家列表

路径: /api/institution/merchant/store_list

方法: POST

请求参数（data）

参数名	类型	必填	说明
lat	string	是	纬度
lng	string	是	经度
keyword	string	否	搜索关键词（商户名称模糊匹配）
categoryId	int	否	店铺分类ID
page	int	否	页码
limit	int	否	每页条数，默认15

响应示例

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "name": "商户名称",
        "cover": "https://xxx.com/cover.jpg",
        "lng": "120.123456",
        "lat": "30.123456",
        "navigation_address": "导航地址",
        "juli": 1234.56,
        "juli_format": "1.23km",
        "star_rank": 5
      }
    ],
    "total": 100
  }
}

3. 商家详情

路径: /api/institution/merchant/store_detail

方法: POST

请求参数（data）

参数名	类型	必填	说明
lat	string	是	纬度
lng	string	是	经度
mer_id	int	是	商户ID

响应示例

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "id": 1,
    "name": "商户名称",
    "cover": "https://xxx.com/cover.jpg",
    "lng": "120.123456",
    "lat": "30.123456",
    "navigation_address": "导航地址",
    "phone": "13800138000",
    "juli": "1.23km",
    "star_rank": 5
  }
}

4. 商家信息同步（重点）

路径: /api/institution/merchant/store_sync

方法: POST

说明: 同步商家信息到平台，支持新增和修改两种模式

请求参数（data）

参数名	类型	必填	说明
sync_type	int	是	同步类型：`1`=新增 `2`=修改
channel	int	是	通道类型，默认 `6`（汇付）。可选值：`0`=富友 `1`=拉卡拉 `2`/`5`=付呗 `6`=汇付
fy_mchnt_cd	string	sync_type=2时必填	商户编号（修改时用于定位商户）
merchant_info	object	是	商户基本信息，见下表
merchant_enter_info	object	是	商户入驻信息（channel=6时参考 `huifu_merchant_enter_infos` 表），见下表

merchant_info 字段说明

参数名	类型	必填	说明
phone	string	是	商户手机号（用于匹配机构用户关系）
name	string	是	商户名称
merchant_type	int	是	商户类型
type	int	是	商户类型（同 merchant_type）
address	string	否	商户地址
is_firm	int	否	是否企业：`0`=个人 `1`=企业
settle_cycle	string	否	结算周期
cover	string	否	商户封面图URL
lng	string	否	经度
lat	string	否	纬度
navigation_address	string	否	导航地址
product_type	int	否	产品类型
fy_mchnt_cd	string	否	第三方商户编号

merchant_enter_info 字段说明（channel=6 汇付）

参考 huifu_merchant_enter_infos 表结构：

参数名	类型	必填	说明
merchant_type	string	否	商户类型：`1`=小微 `2`=个体 `3`=企业
line_type	string	否	线上线下：`1`=线上 `2`=线下
reg_name	string	否	商户名/负责人姓名
short_name	string	否	商户简称
receipt_name	string	否	小票名称
ent_type	string	否	公司类型
mcc	string	否	所属行业MCC
district_id	string	否	经营区
detail_addr	string	否	经营详细地址
license_code	string	否	证照编号
license_pic	string	否	证照图片URL
license_validity_type	string	否	证照有效期类型
license_begin_date	string	否	证照有效期开始（格式：YYYY-MM-DD）
license_end_date	string	否	证照有效期截止
found_date	string	否	成立时间
reg_district_id	string	否	注册区
reg_detail	string	否	注册详细地址
legal_name	string	否	法人姓名
legal_cert_no	string	否	法人/负责人证件号码
legal_cert_type	string	否	法人/负责人证件类型，默认 `00`
legal_cert_validity_type	string	否	法人/负责人证件有效期类型
legal_cert_begin_date	string	否	法人/负责人证件有效期开始
legal_cert_end_date	string	否	法人/负责人证件有效期截止
legal_addr	string	否	法人/负责人身份证地址
legal_cert_front_pic	string	否	法人/负责人身份证人像面URL
legal_cert_back_pic	string	否	法人/负责人身份证国徽面URL
contact_mobile_no	string	否	联系人手机号
contact_email	string	否	联系人邮箱
card_type	string	否	结算账户类型：`0`=对公 `1`=对私
card_name	string	否	结算账户名
card_no	string	否	结算银行卡号
area_id	string	否	银行所在市
cert_no	string	否	持卡人证件号码
cert_type	string	否	持卡人证件类型，默认 `00`
cert_validity_type	string	否	持卡人证件有效期类型
cert_begin_date	string	否	持卡人证件有效期开始
cert_end_date	string	否	持卡人证件有效期截止
settle_card_front_pic	string	否	银行卡卡号面URL
store_header_pic	string	否	店铺门头照URL
store_indoor_pic	string	否	店铺内景照URL
store_cashier_desk_pic	string	否	店铺收银台照URL
navigation_address	string	否	导航地址
mchnt_cover_img	string	否	商户LOGO URL
lng	string	否	经度
lat	string	否	纬度
invite_code	string	否	邀请码/激活码

请求示例（新增商家，channel=6 汇付）

{
  "ins_no": "INS001",
  "version": "1.0",
  "nonce": "abc123",
  "sign": "XXXXXXXXXXXXXXXX",
  "data": {
    "sync_type": 1,
    "channel": 6,
    "merchant_info": {
      "phone": "13800138000",
      "name": "测试商户",
      "merchant_type": 1,
      "type": 1,
      "address": "XX省XX市XX区XX路XX号",
      "is_firm": 1,
      "cover": "https://xxx.com/cover.jpg",
      "lng": "120.123456",
      "lat": "30.123456",
      "navigation_address": "XX省XX市XX区XX路XX号",
      "product_type": 1,
      "fy_mchnt_cd": "HF0001"
    },
    "merchant_enter_info": {
      "merchant_type": "2",
      "line_type": "2",
      "reg_name": "张三",
      "short_name": "测试商户",
      "receipt_name": "测试商户",
      "mcc": "5812",
      "district_id": "330102",
      "detail_addr": "XX路XX号",
      "license_code": "91330100XXXXXXXXXX",
      "license_pic": "https://xxx.com/license.jpg",
      "legal_name": "张三",
      "legal_cert_no": "330100XXXXXXXXXXXX",
      "contact_mobile_no": "13800138000",
      "card_type": "1",
      "card_name": "张三",
      "card_no": "6222XXXXXXXXXXXX",
      "area_id": "330100",
      "store_header_pic": "https://xxx.com/header.jpg",
      "store_indoor_pic": "https://xxx.com/indoor.jpg",
      "store_cashier_desk_pic": "https://xxx.com/cashier.jpg"
    }
  }
}

响应示例

{
  "code": 200,
  "msg": "同步成功",
  "data": null
}

5. 钱包信息

路径: /api/institution/wallet/info

方法: POST

请求参数（data）

参数名	类型	必填	说明
phone	string	是	用户手机号，格式：`/^1[3-9]\d{9}$/`

响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "name": "余额钱包",
      "total": "100.00"
    }
  ]
}

6. 用户信息同步

路径: /api/institution/user/sync

方法: POST

说明: 将机构用户同步到平台，建立机构-平台用户关联关系

请求参数（data）

参数名	类型	必填	说明
phone	string	是	用户手机号，格式：`/^1[3-9]\d{9}$/`
user_code	string	是	机构用户编号
parent_phone	string	是	推荐人手机号，格式：`/^1[3-9]\d{9}$/`

响应示例

{
  "code": 200,
  "msg": "同步成功",
  "data": null
}

7. 平台下单

路径: /api/institution/order/place

方法: POST

说明: 机构向平台发起下单请求，平台生成订单并返回平台订单号

请求参数（data）

参数名	类型	必填	说明
req_no	string	是	请求号
ins_order_no	string	是	机构订单号
ins_user_code	string	是	机构用户编号
ins_mer_user_code	string	是	机构商家用户编号
tran_mer_code	string	是	交易商家编码
receipt_rule	int	是	收款规则（平台费率），可选值：`15` 或 `22`
amount	string	是	订单金额（元）
pay_type	int	是	支付类型：`1`=扫码 `2`=刷卡
pay_method	int	是	支付方式：`1`=微信 `2`=支付宝 `3`=银行卡

响应示例

{
  "code": 200,
  "msg": "下单成功",
  "data": {
    "plat_order_no": "YP20260101120000XXXXXX"
  }
}

8. 订单信息同步

路径: /api/institution/order/sync

方法: POST

说明: 机构支付完成后，将支付结果同步到平台，触发分润

请求参数（data）

参数名	类型	必填	说明
plat_order_no	string	是	平台订单号
status	int	是	订单状态：`0`=未支付 `1`=已支付
transaction_id	string	是	第三方交易号
pay_amount	string	是	实际支付金额（元）
order_data	object	是	订单扩展数据

响应示例

{
  "code": 200,
  "msg": "同步成功",
  "data": null
}

9. 订单批量同步

路径: /api/institution/order/batch_sync

方法: POST

说明: 一步完成下单+支付同步，适用于机构已完成支付的历史订单批量导入

请求参数（data）

参数名	类型	必填	说明
req_no	string	是	请求号
ins_order_no	string	是	机构订单号
ins_user_code	string	是	机构用户编号
ins_mer_user_code	string	是	机构商家用户编号
tran_mer_code	string	是	交易商家编码
receipt_rule	int	是	收款规则，可选值：`15` 或 `22`
amount	string	是	订单金额（元）
pay_type	int	是	支付类型：`1`=扫码 `2`=刷卡
pay_method	int	是	支付方式：`1`=微信 `2`=支付宝 `3`=银行卡
status	int	是	订单状态：`0`=未支付 `1`=已支付
pay_status	int	是	支付状态：`0`=未支付 `1`=已支付
transaction_id	string	否	第三方交易号
pay_amount	string	是	实际支付金额（元）
order_data	object	是	订单扩展数据

响应示例

{
  "code": 200,
  "msg": "同步成功",
  "data": {
    "plat_order_no": "YP20260101120000XXXXXX"
  }
}

10. 用户侧补充分润

路径: /api/institution/order/user_profit_sync

方法: POST

说明: 用户完善信息后，补充执行用户侧分润。仅当订单 profit_status=1（商家侧已分润）时可调用

请求参数（data）

参数名	类型	必填	说明
plat_order_no	string	是	平台订单号
ins_user_code	string	是	机构用户编号

响应示例

{
  "code": 200,
  "msg": "用户侧分润执行成功",
  "data": {
    "plat_order_no": "YP20260101120000XXXXXX",
    "profit_status": 3
  }
}

11. 更正订单数据

路径: /api/institution/order/order_data_sync

方法: POST

说明: 更正订单的 order_data 扩展数据

请求参数（data）

参数名	类型	必填	说明
plat_order_no	string	是	平台订单号
ins_no	string	是	机构编号
order_data	object	是	订单扩展数据

响应示例

{
  "code": 200,
  "msg": "订单数据同步成功",
  "data": {
    "plat_order_no": "YP20260101120000XXXXXX",
    "order_data": {}
  }
}

机构公共API文档说明

机构公共API文档#

基础信息#

公共请求参数#

签名规则#

公共响应格式#

1. 获取机构配置#

请求参数（data）#

响应示例(请做好兼容,不定期新增配置字段)#

2. 商家列表#

请求参数（data）#

响应示例#

3. 商家详情#

请求参数（data）#

响应示例#

4. 商家信息同步（重点）#

请求参数（data）#

merchant_info 字段说明#

merchant_enter_info 字段说明（channel=6 汇付）#

请求示例（新增商家，channel=6 汇付）#

响应示例#

5. 钱包信息#

请求参数（data）#

响应示例#

6. 用户信息同步#

请求参数（data）#

响应示例#

7. 平台下单#

请求参数（data）#

响应示例#

8. 订单信息同步#

请求参数（data）#

响应示例#

9. 订单批量同步#

请求参数（data）#

响应示例#

10. 用户侧补充分润#

请求参数（data）#

响应示例#

11. 更正订单数据#

请求参数（data）#

响应示例#

机构公共API文档

基础信息

公共请求参数

签名规则

公共响应格式

1. 获取机构配置

请求参数（data）

响应示例(请做好兼容,不定期新增配置字段)

2. 商家列表

请求参数（data）

响应示例

3. 商家详情

请求参数（data）

响应示例

4. 商家信息同步（重点）

请求参数（data）

merchant_info 字段说明

merchant_enter_info 字段说明（channel=6 汇付）

请求示例（新增商家，channel=6 汇付）

响应示例

5. 钱包信息

请求参数（data）

响应示例

6. 用户信息同步

请求参数（data）

响应示例

7. 平台下单

请求参数（data）

响应示例

8. 订单信息同步

请求参数（data）

响应示例

9. 订单批量同步

请求参数（data）

响应示例

10. 用户侧补充分润

请求参数（data）

响应示例

11. 更正订单数据

请求参数（data）

响应示例