合作伙伴管理接口文档

一、模块概述

合作伙伴管理模块（基础管理），三端共用：

电商端菜单名"货代管理"

货代端/报关端菜单名"合作伙伴"

核心功能：通过企业配置码建立合作关系，管理合作生命周期（申请/接受/拒绝/暂停/恢复/终止/删除），支持线下伙伴手动添加。

所有接口请求头需携带 Authorization: Bearer {token}，token 为登录接口返回的 data。

二、接口列表

合作伙伴关系 `/bs/partner`

接口名称	请求方式	URL	格式
列表分页	POST	`/bs/partner/page`	FORMDATA
详情	GET	`/bs/partner/{id}`	-
申请合作-预览	POST	`/bs/partner/apply-preview`	FORMDATA
申请合作-提交	POST	`/bs/partner/apply`	JSON
添加线下伙伴	POST	`/bs/partner/offline`	JSON
接受合作	POST	`/bs/partner/accept`	FORMDATA
拒绝合作	POST	`/bs/partner/reject`	FORMDATA
暂停合作	POST	`/bs/partner/suspend`	FORMDATA
恢复合作	POST	`/bs/partner/resume`	FORMDATA
终止合作	POST	`/bs/partner/terminate`	FORMDATA
删除合作伙伴	POST	`/bs/partner/delete`	FORMDATA
保存备注	POST	`/bs/partner/save-remark`	JSON

企业配置码 `/bs/partner/config-code`

接口名称	请求方式	URL	说明
获取配置码	GET	`/bs/partner/config-code`	不存在自动生成
刷新配置码	POST	`/bs/partner/config-code/refresh`	旧码失效
保存配置码信息	POST	`/bs/partner/config-code/save`	JSON

三、接口详情

3.1 列表分页

URL：POST /bs/partner/page

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
partnerName	String	否	企业名称（模糊搜索）
partnerType	Integer	否	企业类型（1:电商 2:货代 3:报关；不传查全部）
status	Integer	否	合作状态（0:已申请 1:待确认 2:合作中 3:已暂停 4:已拒绝 5:已终止；不传查全部）
cooperateTimeBegin	String	否	合作日期-开始（yyyy-MM-dd HH:mm:ss）
cooperateTimeEnd	String	否	合作日期-结束（yyyy-MM-dd HH:mm:ss）
pageNum	Integer	否	页码（默认1）
pageSize	Integer	否	每页条数（默认20，最大200）

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "current": 1,
    "size": 20,
    "total": 5,
    "records": [
      {
        "id": 1,
        "partnerTenantId": 100,
        "partnerName": "深圳市XX货代有限公司",
        "partnerType": 2,
        "partnerTypeName": "货代",
        "isOffline": false,
        "status": 2,
        "statusName": "合作中",
        "contactName": "张三",
        "contactPhone": "13800138000",
        "cooperateTime": "2026-01-15 10:30:00",
        "remark": "长期合作伙伴"
      }
    ]
  }
}

响应字段说明：

字段名	类型	描述
id	Long	合作伙伴关系ID
partnerTenantId	Long	合作伙伴租户ID（线下伙伴为null）
partnerName	String	企业名称
partnerType	Integer	企业类型（1:电商 2:货代 3:报关）
partnerTypeName	String	企业类型名称
isOffline	Boolean	是否线下伙伴
status	Integer	合作状态
statusName	String	合作状态名称
contactName	String	联系人（来自对方配置码）
contactPhone	String	联系电话（来自对方配置码）
cooperateTime	String	合作日期（未建立为null，前端转"-"）
remark	String	备注

3.2 详情

URL：GET /bs/partner/{id}

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID（路径参数）

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "partnerName": "深圳市XX货代有限公司",
    "partnerType": 2,
    "partnerTypeName": "货代",
    "contactName": "张三",
    "contactPhone": "13800138000",
    "status": 2,
    "statusName": "合作中",
    "cooperateTime": "2026-01-15 10:30:00",
    "lastOrderTime": null,
    "docCount": null,
    "remark": "长期合作伙伴"
  }
}

响应字段说明：

字段名	类型	描述
id	Long	合作伙伴关系ID
partnerName	String	企业名称
partnerType	Integer	企业类型
partnerTypeName	String	企业类型名称
contactName	String	联系人（来自对方配置码）
contactPhone	String	联系电话（来自对方配置码）
status	Integer	合作状态
statusName	String	合作状态名称
cooperateTime	String	合作日期
lastOrderTime	String	最近下单日期（暂留空，后续完善）
docCount	Integer	历史单证数（暂留空，后续完善）
remark	String	备注

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作

3.3 申请合作-预览

URL：POST /bs/partner/apply-preview

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
configCode	String	是	对方企业配置码

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "tenantId": 100,
    "partnerName": "深圳市XX货代有限公司",
    "partnerType": 2,
    "partnerTypeName": "货代",
    "contactName": "张三",
    "contactPhone": "13800138000"
  }
}

响应字段说明：

字段名	类型	描述
tenantId	Long	对方企业租户ID
partnerName	String	企业名称
partnerType	Integer	企业类型
partnerTypeName	String	企业类型名称
contactName	String	联系人（来自配置码）
contactPhone	String	联系电话（来自配置码）

错误场景：

场景	msg
配置码为空	请输入配置码
配置码不存在/无效	此配置码未查询到企业，请核查
配置码已过期	该配置码已失效，请核查
企业类型不允许	当前端不支持添加该类型的合作伙伴

配置码过期时，后端会惰性标记该配置码 valid=0（独立事务），使存储状态与实际过期状态一致。

3.4 申请合作-提交

URL：POST /bs/partner/apply

请求方式：JSON

请求参数：

{
  "configCode": "HDAB12CD34EF"
}

字段名	类型	必填	描述
configCode	String	是	对方企业配置码

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
配置码为空	请输入配置码
配置码不存在/无效	此配置码未查询到企业，请核查
配置码已过期	该配置码已失效，请核查
与自己合作	不能与自己建立合作关系
企业类型不允许	当前端不支持添加该类型的合作伙伴
已存在关系	已存在与该企业的合作关系，请勿重复申请

业务说明：提交后双方各生成一行镜像记录：

本方行：状态=已申请，发起方

对方行：状态=待确认，接收方

3.5 添加线下伙伴

URL：POST /bs/partner/offline

请求方式：JSON

请求参数：

{
  "partnerName": "广州XX物流有限公司",
  "partnerType": 2,
  "remark": "线下合作"
}

字段名	类型	必填	描述
partnerName	String	是	企业名称（限50字符）
partnerType	Integer	是	企业类型（1:电商 2:货代 3:报关）
remark	String	否	备注（限200字符）

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
企业名称为空	请输入企业名称
企业类型为空	请选择企业类型
企业类型不允许	当前端不支持添加该类型的合作伙伴

业务说明：线下伙伴仅本方一行，直接"合作中"，写入合作日期，无 partnerTenantId，无镜像行。

3.6 接受合作

URL：POST /bs/partner/accept

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
非待确认状态	当前状态不允许接受
对方已撤回	对方已撤回合作申请

业务说明：仅"待确认"状态可操作。接受后双方行均变为"合作中"，写入合作日期。若对方镜像行已不存在（已撤回），删除本方行并提示。

3.7 拒绝合作

URL：POST /bs/partner/reject

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
非待确认状态	当前状态不允许拒绝
对方已撤回	对方已撤回合作申请

业务说明：仅"待确认"状态可操作。拒绝后双方行均变为"已拒绝"。若对方镜像行已不存在（已撤回），删除本方行并提示。

3.8 暂停合作

URL：POST /bs/partner/suspend

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
非合作中状态	仅合作中的合作伙伴可暂停

业务说明：仅"合作中"状态可操作。暂停后双方行同步变为"已暂停"。已暂停的伙伴不允许再被选中进行单证流转。

3.9 恢复合作

URL：POST /bs/partner/resume

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
非已暂停状态	仅已暂停的合作伙伴可恢复

业务说明：仅"已暂停"状态可操作。恢复后双方行同步变为"合作中"。

3.10 终止合作

URL：POST /bs/partner/terminate

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
非合作中/已暂停状态	仅合作中或已暂停的合作伙伴可终止

业务说明：仅"合作中"或"已暂停"状态可操作。终止后双方行同步变为"已终止"，不可恢复。

3.11 删除合作伙伴

URL：POST /bs/partner/delete

请求方式：FORMDATA

请求参数：

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作
状态不允许删除	当前状态不允许删除

业务说明：仅"已申请""待确认""已拒绝""已终止"状态可删除。仅删除本方行（物理删除），不影响对方行。

3.12 保存备注

URL：POST /bs/partner/save-remark

请求方式：JSON

请求参数：

{
  "id": 1,
  "remark": "长期合作伙伴"
}

字段名	类型	必填	描述
id	Long	是	合作伙伴关系ID
remark	String	否	备注（限200字符）

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": null
}

错误场景：

场景	msg
关系不存在或越权	合作伙伴不存在或无权操作

3.13 获取企业配置码

URL：GET /bs/partner/config-code

请求参数：无

响应示例：

{
  "code": 200,
  "msg": "success",
  "data": {
    "configCode": "DSAB12CD34EF",
    "expireTime": null,
    "companyName": "深圳市XX电商有限公司",
    "contactName": "李四",
    "contactPhone": "13900139000"
  }
}

响应字段说明：

字段名	类型	描述
configCode	String	配置码
expireTime	String	有效期至（null表示永久）
companyName	String	当前企业名称（只读）
contactName	String	联系人（可编辑）
contactPhone	String	联系电话（可编辑）

业务说明：首次访问自动生成永久有效配置码。配置码前缀：电商 DS / 货代 HD / 报关 BG。配置码过期后不自动失效/重建，用户可在界面看到有效期并手动刷新。

3.14 刷新配置码

URL：POST /bs/partner/config-code/refresh

请求参数：无

响应：同 3.13 格式，返回新配置码。

业务说明：旧配置码立即失效，新码沿用旧码的有效期/联系人/电话。

3.15 保存配置码信息

URL：POST /bs/partner/config-code/save

请求方式：JSON

请求参数：

{
  "expireType": 0,
  "contactName": "李四",
  "contactPhone": "13900139000"
}

字段名	类型	必填	描述
expireType	Integer	否	有效期类型（0:永久 1:1天 7:7天 30:30天 365:一年）
contactName	String	否	联系人（限20字符）
contactPhone	String	否	联系电话（限11位数字）

响应：同 3.13 格式。

业务说明：永久时 expireTime 返回 null，其余按当前时间 + 对应天数计算。配置码不存在时先自动生成再保存。

四、状态枚举

4.1 合作状态

值	名称	说明
0	已申请	本方发起申请，等待对方确认
1	待确认	对方发起申请，等待本方接受/拒绝
2	合作中	已建立合作关系
3	已暂停	合作关系被暂停（双方同步）
4	已拒绝	申请被拒绝（双方同步）
5	已终止	合作关系终止，不可恢复（双方同步）

4.2 企业类型

值	名称
1	电商企业
2	货代
3	报关行

4.3 配置码有效期类型

值	含义
0	永久
1	1天
7	7天
30	30天
365	一年

4.4 各端可添加的伙伴类型

本端	可添加类型
电商	货代
货代	电商、货代、报关
报关	货代、报关

五、状态可用操作

状态	可用操作
已申请	详情、删除
待确认	详情、接受、拒绝、删除
合作中	详情、暂停、终止
已暂停	详情、恢复、终止
已拒绝	详情、删除
已终止	详情、删除

六、数据库表

bs_partner（合作伙伴关系表）

字段	类型	说明
id	BIGINT	主键
tenant_id	BIGINT	归属方租户ID
partner_tenant_id	BIGINT	合作伙伴租户ID（线下为NULL）
partner_type	INT	企业类型
partner_name	VARCHAR(100)	企业名称（冗余快照）
is_offline	TINYINT(1)	是否线下伙伴
status	INT	合作状态
initiator	TINYINT(1)	本方是否发起方
cooperate_time	DATETIME	合作日期
remark	VARCHAR(200)	备注
create_by / create_time / update_by / update_time	-	审计字段

bs_partner_config_code（企业配置码表）

字段	类型	说明
id	BIGINT	主键
tenant_id	BIGINT	所属企业租户ID
config_code	VARCHAR(30)	配置码（全局唯一）
expire_time	DATETIME	有效期至（NULL永久）
contact_name	VARCHAR(20)	联系人
contact_phone	VARCHAR(11)	联系电话
valid	TINYINT(1)	是否当前有效
create_by / create_time / update_by / update_time	-	审计字段

七、镜像行设计说明

A↔B 合作存 2 行，各自管理自己视角：

操作	A 行变化	B 行变化
A 申请 B	新增，状态=已申请	新增，状态=待确认
B 接受	状态→合作中	状态→合作中
B 拒绝	状态→已拒绝	状态→已拒绝
任一方暂停	双方→已暂停	双方→已暂停
任一方恢复	双方→合作中	双方→合作中
任一方终止	双方→已终止	双方→已终止
任一方删除	删除本方行	对方行不变

接受/拒绝时若对方镜像行已不存在（已撤回），则删除本方行并提示"对方已撤回合作申请"。

八、统一响应体

字段	类型	说明
code	Integer	状态码（200:成功 500:异常 403:无权限）
msg	String	响应消息（成功"success"，失败为错误描述）
data	Object	响应数据（成功返回业务数据，失败为null）

合作伙伴

合作伙伴管理接口文档#

一、模块概述#

二、接口列表#

合作伙伴关系 /bs/partner#

企业配置码 /bs/partner/config-code#

三、接口详情#

3.1 列表分页#

3.2 详情#

3.3 申请合作-预览#

3.4 申请合作-提交#

3.5 添加线下伙伴#

3.6 接受合作#

3.7 拒绝合作#

3.8 暂停合作#

3.9 恢复合作#

3.10 终止合作#

3.11 删除合作伙伴#

3.12 保存备注#

3.13 获取企业配置码#

3.14 刷新配置码#

3.15 保存配置码信息#

四、状态枚举#

4.1 合作状态#

4.2 企业类型#

4.3 配置码有效期类型#

4.4 各端可添加的伙伴类型#

五、状态可用操作#

六、数据库表#

bs_partner（合作伙伴关系表）#

bs_partner_config_code（企业配置码表）#

七、镜像行设计说明#

八、统一响应体#

合作伙伴管理接口文档

一、模块概述

二、接口列表

合作伙伴关系 `/bs/partner`

企业配置码 `/bs/partner/config-code`

三、接口详情

3.1 列表分页

3.2 详情

3.3 申请合作-预览

3.4 申请合作-提交

3.5 添加线下伙伴

3.6 接受合作

3.7 拒绝合作

3.8 暂停合作

3.9 恢复合作

3.10 终止合作

3.11 删除合作伙伴

3.12 保存备注

3.13 获取企业配置码

3.14 刷新配置码

3.15 保存配置码信息

四、状态枚举

4.1 合作状态

4.2 企业类型

4.3 配置码有效期类型

4.4 各端可添加的伙伴类型

五、状态可用操作

六、数据库表

bs_partner（合作伙伴关系表）

bs_partner_config_code（企业配置码表）

七、镜像行设计说明

八、统一响应体