平台商户管理

平台企业通过 OpenAPI 管理子商户，并为子商户管理员生成一次性登录地址。

本页用于平台企业管理其下的子商户：创建、查询、修改、启用或停用子商户，以及修改子商户超级管理员密码和生成管理员的一次性登录地址。

所有接口均为 POST，请求根路径为：

https://qiyukf.com/platform/api/openapi/merchant

只有平台主企业的 appKey 可以调用本页接口；子商户的 appKey 不具备调用权限。

请求签名

所有接口在 query 中传入以下字段；请求体为 application/json;charset=utf-8。

参数	类型	必填	说明
`appKey`	String	是	平台主企业的 AppKey。
`time`	Long	是	当前秒级 Unix 时间戳；服务端与该时间的偏差不能超过 10 分钟。
`checksum`	String	是	对 `appSecret + md5(body) + time` 计算摘要后的十六进制小写字符串。
`checksumAlgorithm`	Integer	否	`0` 或不传为 SHA-1；传 `1` 时使用 SHA-256。

其中 md5(body) 为请求体原文的 MD5 值（小写）。签名的完整规则与示例见通用说明。

所有响应均使用以下信封结构：

{
  "code": 200,
  "result": {},
  "message": "success",
  "total": 0
}

result 的类型由接口决定；仅列表接口的 total 有业务含义。

子商户标识

字段	说明
`id`	平台商户记录 ID；由创建接口返回，也可从商户列表获得。
`shopCode`	子商户标识，即子商户企业 code 中平台 code 后的部分。
`code`	子商户完整企业 code。创建时服务端按 `{平台 code}-{shopCode}` 生成。

对于支持 id 和 shopCode 的查询、启停和密码接口，同时传入时以 id 为准。

第三方登录

为某个子商户中的管理员账号生成一次性登录地址。

POST /account/login?appKey={appKey}&time={time}&checksum={checksum}

请求体

字段	类型	必填	说明
`userName`	String	是	目标子商户中的账号。
`code`	String	条件必填	子商户完整企业 code。与 `shopCode` 至少传一个；两者同时传入时优先使用 `code`。
`shopCode`	String	条件必填	子商户标识。

{
  "userName": "merchant-admin@example.com",
  "shopCode": "merchant-a"
}

响应

result.redirectUrl 为一次性登录地址。例如：

{
  "code": 200,
  "result": {
    "redirectUrl": "https://platform-merchant-a.qiyukf.com/login?thirdToken=..."
  },
  "message": "success",
  "total": 0
}

该地址仅可使用一次；生成后应立即让浏览器跳转，避免记录、转发或长期保存该地址。

创建商户

POST /create?appKey={appKey}&time={time}&checksum={checksum}

请求体

字段	类型	必填	说明
`domain`	String	是	商户标识。服务端最终生成的完整 code 长度必须在 1 至 50 个字符之间；不带平台前缀时会自动拼接 `{平台 code}-`。
`name`	String	是	商户名称，最多 50 个字符。
`seatNumber`	Long	是	分配给商户的在线坐席数，范围为 `0` 至 `2147483647`；可分配数量受平台剩余坐席限制。
`account`	String	是	商户超级管理员账号，必须为邮箱格式。
`contact`	String	否	联系方式，最多 50 个字符；不传时保存为空字符串。
`password`	String	是	商户超级管理员密码的 32 位小写 MD5 值。
`portrait`	String	否	当前实现会接收该字段，但创建流程不会保存头像；请勿依赖此字段。

{
  "domain": "merchant-a",
  "name": "商户 A",
  "seatNumber": 10,
  "account": "merchant-admin@example.com",
  "contact": "13800000000",
  "password": "e10adc3949ba59abbe56e057f20f883e"
}

成功时 result 为新建商户的 id：

{
  "code": 200,
  "result": 102143,
  "message": "success",
  "total": 0
}

修改商户

POST /update?appKey={appKey}&time={time}&checksum={checksum}

字段	类型	必填	说明
`id`	Long	是	要修改的商户 ID。虽然接口入参中保留了 `shopCode`，但当前实现实际仅按 `id` 更新。
`seatNumber`	Long	是	调整后的在线坐席数，范围为 `0` 至 `2147483647`。当前实现会直接使用该值，不能省略。
`name`	String	否	商户名称；传入时长度为 1 至 50 个字符。
`account`	String	否	超级管理员账号；传入时必须为邮箱格式。
`contact`	String	否	联系方式；传入非空值时最多 50 个字符。
`shopCode`	String	否	DTO 中保留的字段；当前更新实现不会用它定位商户。
`portrait`	String	否	DTO 中保留的字段；当前更新实现不会保存头像。

{
  "id": 102143,
  "name": "商户 A（更新后）",
  "seatNumber": 12,
  "account": "new-admin@example.com",
  "contact": "13900000000"
}

成功时：

{
  "code": 200,
  "result": "success",
  "message": "success",
  "total": 0
}

启用商户

POST /enable?appKey={appKey}&time={time}&checksum={checksum}

{
  "id": 102143
}

请求体至少提供 id 或 shopCode 之一。商户被启用后，status 变为 1。

停用商户

POST /disable?appKey={appKey}&time={time}&checksum={checksum}

{
  "shopCode": "merchant-a"
}

请求体至少提供 id 或 shopCode 之一。商户被停用后，status 变为 0。启用与停用接口成功时均返回：

{
  "code": 200,
  "result": "success",
  "message": "success",
  "total": 0
}

修改商户密码

POST /changePassword?appKey={appKey}&time={time}&checksum={checksum}

字段	类型	必填	说明
`id`	Long	条件必填	商户 ID。与 `shopCode` 至少传一个。
`shopCode`	String	条件必填	子商户标识。
`password`	String	是	新密码的 32 位小写 MD5 值。

{
  "id": 102143,
  "password": "e10adc3949ba59abbe56e057f20f883e"
}

成功时 result 为 "success"。

获取商户列表

POST /list?appKey={appKey}&time={time}&checksum={checksum}

字段	类型	必填	说明
`offset`	Long	是	列表偏移量，不是页码。
`limit`	Long	是	单次获取数量。

{
  "offset": 0,
  "limit": 20
}

result 是商户数组，total 为该平台下的商户总数。列表项字段如下：

字段	类型	说明
`id`	Long	商户记录 ID。
`corpId`	Long	对应子企业 ID。
`domain`	String	子商户完整企业 code。
`name`	String	商户名称。
`seatNumber`	Integer	已配置的坐席数。
`account`	String	超级管理员账号。
`contact`	String	联系方式。
`status`	Integer	`1` 为启用，`0` 为停用，`2` 为已删除。

获取商户信息

POST /query?appKey={appKey}&time={time}&checksum={checksum}

请求体至少提供 id 或非空的 shopCode 之一：

{
  "shopCode": "merchant-a"
}

result 包含列表项的字段，以及以下字段：

字段	类型	说明
`portrait`	String	商户头像地址。
`appkey`	String	子商户 AppKey。
`appsecret`	String	子商户 AppSecret。仅应在服务端安全保存和使用，禁止下发到客户端。

查询接口返回的 seatNumber 会按子商户当前有效在线坐席服务包重新汇总，可能与列表接口中的已配置值不同。

平台商户管理

目录