投诉处理 API

投诉查询、商户在线回复、商户完结投诉。代码出处：jeepay-payment/pay/ctrl/complaint/ComplaintApiController.java。

两种鉴权方式：

接口	鉴权方式	密钥
投诉单分页查询	请求头 X-Api-Key	服务商投诉 API 密钥（t_isv_info.complaint_api_key），仅返回该服务商名下投诉
商户回复 / 完结	appSecret MD5 签名（规则同通用签名）	商户应用密钥

接口一览

接口	方式	路径
投诉单分页查询	GET	/api/complaints/list
商户在线回复	POST	/api/complaints/reply
商户完结投诉	POST	/api/complaints/finish

1. 投诉单分页查询

GET /api/complaints/list（请求头携带 X-Api-Key）

请求参数（Query String）

参数	类型	必填	说明
pageNumber	Integer	否	页码，默认 1
pageSize	Integer	否	页大小，默认 10，传 -1 查询全部
complaintNo	String	否	投诉单号，精确匹配
mchNo	String	否	商户号，精确匹配
replyState	Byte	否	回复状态：0-待处理，1-已回复，2-处理中，3-已完结

结果按 isv_no 维度过滤：仅返回 X-Api-Key 对应服务商名下的投诉记录。

响应参数（data，分页结构）

参数	类型	说明
total	Long	总条数
current / size	Long	当前页码 / 页大小
records	Array	投诉单列表（ComplaintRecord 实体字段）
records[].complaintNo	String	投诉单号
records[].isvNo	String	所属服务商号
records[].mchNo	String	商户号
records[].replyState	Byte	回复状态：0-待回复，1-已回复
records[].createdAt	Long	投诉时间

返回为投诉记录实体全量字段，以上为常用字段。

2. 商户在线回复投诉

POST /api/complaints/reply（Content-Type: application/json）

请求参数

参数	类型	必填	说明
mchNo	String(64)	是	商户号
appId	String(64)	是	商户应用 ID
complaintNo	String	是	投诉单号
content	String	是	回复内容
sign	String	是	签名：剔除 sign 后非空参数 k=v& 按 key 不区分大小写升序拼接 + key=appSecret，MD5 大写

校验规则

1. mchNo / appId / complaintNo / content / sign 任一为空报"参数有误"；
2. 商户应用验签（appSecret 参与签名，同 JeepayKit.getSign）；
3. 投诉记录归属校验：投诉单 mchNo 必须与请求商户一致；
4. 已完结（replyState = 3）的投诉不可回复，返回"该投诉已完结，无法回复"。

响应

{ "code": 0, "msg": "SUCCESS" }

3. 商户完结投诉

POST /api/complaints/finish（Content-Type: application/json）

请求参数

参数	类型	必填	说明
mchNo	String(64)	是	商户号
appId	String(64)	是	商户应用 ID
complaintNo	String	是	投诉单号
sign	String	是	签名，规则同上（无 content）

同样执行投诉归属校验；完结后状态置为已完结（replyState = 3），不可再回复。

响应

{ "code": 0, "msg": "SUCCESS" }

Java 示例（SDK）

JeepayClient client = new JeepayClient("http://<服务器IP>:9216", appSecret);

// 1. 分页查询（X-Api-Key，密钥为服务商投诉 API 密钥）
JeepayResponse list = client.complaintList(
        "服务商投诉API密钥",
        new ComplaintQueryRequest().pageNumber(1).pageSize(10)
                .replyState((byte) 0).toParams());

// 2. 商户在线回复（appSecret 签名）
client.complaintReply(appSecret, "M1690858842671", "appId-demo",
        "202601050001", "已与用户协商退款处理完毕");

// 3. 商户完结投诉（appSecret 签名）
client.complaintFinish(appSecret, "M1690858842671", "appId-demo", "202601050001");

curl 示例

# 1. 分页查询（X-Api-Key）
curl 'http://<服务器IP>:9216/api/complaints/list?pageNumber=1&pageSize=10&replyState=0' \
  -H 'X-Api-Key: your-complaint-api-key'

# 2. 商户在线回复（appSecret 签名，sign 为按上述算法计算的真实签名占位）
curl -X POST http://<服务器IP>:9216/api/complaints/reply \
  -H 'Content-Type: application/json' \
  -d '{"mchNo":"M1690858842671","appId":"appId-demo","complaintNo":"202601050001","content":"已与用户协商退款处理完毕","sign":"<按签名算法计算>"}'

# 3. 商户完结投诉
curl -X POST http://<服务器IP>:9216/api/complaints/finish \
  -H 'Content-Type: application/json' \
  -d '{"mchNo":"M1690858842671","appId":"appId-demo","complaintNo":"202601050001","sign":"<按签名算法计算>"}'