任务数据回传&查询
任务数据回传
基础说明
芝麻 GO 玩法与数据回传案例
承诺模式
芝麻 GO 玩法为承诺模式且为任务次数型，商家发放给用户的权益可在任务中被核销，则任务和优惠数据可以合并回传。以某打车平台活动任务为例，用户开通时先获得 2 张 2 元打车优惠券，用户完成一次打车任务时，回传任务次数、优惠数据（包含订单名称，订单金额，订单享受优惠金额，订单交易时间）。
芝麻 GO 玩法为承诺模式且为金额类型，商家发放给用户的权益可在任务中被核销，则任务和优惠数据可以合并回传。以某购物软件的活动任务为例，用户开通时获得 200 元红包，活动周期内需完成电商消费金额满 10000 元，用户活动期间进行一次消费，回传任务金额、优惠数据（包含订单名称，订单金额，订单享受优惠金额，订单交易时间）。
芝麻 GO 玩法为承诺模式，且优惠权益与任务不关联，则任务数据和优惠数据独立回传。以某商家签到任务为例，用户开通时获得 2 张购物优惠券，活动周期内需完成一周 7 次签到。则任务数据和优惠数据分开回传。
数据回传类型说明
| 是否累计任务进度 | 一级数据类型 | 二级数据类型 | 可组合数据类型 |
|---|---|---|---|
| 是 | 进度数据 | 任务金额类型 | 任务金额（必传）+优惠数据（可选） |
| 任务次数类型 | 任务次数（必传）+任务金额（可选）+优惠数据（可选） | ||
| 否 | 优惠数据 | 无 | 优惠数据（必传） |
数据回传动作类型
数据回传动作子类型
回传参数示例（参数部分见接口入参说明）
如果商家要回传的数据需要累计进度，且任务类型（模版配置的）是金额型：
biz_action = POSITIVE
sub_biz_action = ADD
data_type = TASK
数据模型：
amount_type_sync_data
task_desc-------必传
task_amount-----必传
discount_desc---可选
discount_amount-可选如果商家要回传的数据需要累计进度，且任务类型（模版配置的）是次数型：
biz_action = POSITIVE
sub_biz_action = ADD
data_type = TASK
数据模型：
times_type_sync_data
task_desc-------必传
task_times------必传
task_amount-----可选
discount_desc---可选
discount_amount-可选如果商家要回传的数据不需要累计进度，仅仅只是给用户展示享受的优惠信息（和模版配置无关）：
biz_action = POSITIVE
sub_biz_action = ADD
data_type = DISCOUNT
数据模型：
discount_type_sync_data
discount_desc---必传
discount_amount-必传接口使用案例
案例一：承诺模式（任务为次数类型）
正向新增
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json",
"GBK", "alipay_public_key", "RSA2");
// 构建参数
ZhimaMerchantZmgoCumulateSyncModel model = new ZhimaMerchantZmgoCumulateSyncModel();
model.setAgreementId("ZMGO_AGR2021030510020604520000006001"); // 回传数据对应的芝麻GO协议号
model.setUserId("2088602002015001"); // 用户在支付宝的用户ID
model.setProviderPid("2088621805983504"); // 商家PID
model.setOutBizNo("P2020081211223006150094012926289"); // 商家侧本次请求流水号，对应唯一一笔回传数据
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 回传处理时间，代表导致回传的用户事件发生时间（如购买/核销等）
model.setBizAction("POSITIVE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("TASK"); // 代表本次是任务型数据
// 使用任务金额类型数据模型
TimesTypeSyncData timesTypeSyncData = new TimesTypeSyncData();
timesTypeSyncData.setTaskTimes(1L); // 【必填】任务次数，必须设置，目前固定值只能为1
timesTypeSyncData.setTaskDesc("完成一次打车任务"); // 【必填】本次任务记录的描述
timesTypeSyncData.setTaskAmount("13.88"); // 【可选】本次任务涉及的金额，比如本次打车花费了13.88元，用于展示
timesTypeSyncData.setDiscountDesc("2元打车红包"); // 【可选】本次任务用户享受的优惠信息描述，比如优惠券名称，用于展示
timesTypeSyncData.setDiscountAmount("2.00"); // 【可选】本次任务用户享受的优惠金额，比如红包金额，用于展示
model.setTimesTypeSyncData(timesTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}逆向新增
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json",
"GBK", "alipay_public_key", "RSA2");
// 构建参数
ZhimaMerchantZmgoCumulateSyncModel model = new ZhimaMerchantZmgoCumulateSyncModel();
model.setAgreementId("ZMGO_AGR2021030510020604520000006001"); // 和正向记录的参数相同
model.setUserId("2088602002015001"); // 和正向记录的参数相同
model.setProviderPid("2088621805983504"); // 和正向记录的参数相同
model.setOutBizNo("R2020081211223006150094012926289"); // 商家侧本次请求流水号，和正向的流水号不同
model.setReferOutBizNo("P2020081211223006150094012926289"); // 本次逆向回传所对应的正向记录流水单号
model.setBizTime(DateFormat.parse("2019-04-08 19:51:35")); // 回传处理时间，代表本次逆向事件发生时间（如退款/退货等）
model.setBizAction("REVERSE"); // 代表一笔逆向累计数据，在概念上是"减掉"
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("TASK"); // 代表本次是任务型数据
// 使用任务金额类型数据模型
TimesTypeSyncData timesTypeSyncData = new TimesTypeSyncData();
timesTypeSyncData.setTaskTimes(1L); // 【必填】本次回退任务次数，必须设置，目前固定值只能为1
timesTypeSyncData.setTaskDesc("用户退款"); // 【必填】本次回退的描述
timesTypeSyncData.setTaskAmount("13.88"); // 【可选】本次回退涉及的金额，用于展示
timesTypeSyncData.setDiscountDesc("2元打车红包"); // 【可选】本次回退用户享受的优惠信息描述，用于展示
timesTypeSyncData.setDiscountAmount("2.00"); // 【可选】本次回退用户享受的优惠金额，用于展示
model.setTimesTypeSyncData(timesTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}案例二：承诺模式（任务为金额类型）
正向新增
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json",
"GBK", "alipay_public_key", "RSA2");
// 构建参数
ZhimaMerchantZmgoCumulateSyncModel model = new ZhimaMerchantZmgoCumulateSyncModel();
model.setAgreementId("ZMGO_AGR2021030510020604520000006001"); // 回传数据对应的芝麻GO协议号
model.setUserId("2088602002015001"); // 用户在支付宝的用户ID
model.setProviderPid("2088621805983504"); // 商家PID
model.setOutBizNo("P2020081211223006150094012926289"); // 商家侧本次请求流水号，对应唯一一笔回传数据
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 回传处理时间，代表导致回传的用户事件发生时间（如购买/核销等）
model.setBizAction("POSITIVE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("TASK"); // 代表本次是任务型数据
// 使用任务金额类型数据模型
AmountTypeSyncData amountTypeSyncData = new AmountTypeSyncData();
amountTypeSyncData.setTaskDesc("购买XXX商品"); // 【必填】本次任务记录的描述
amountTypeSyncData.setTaskAmount("373.88"); // 【必填】本次任务累计的金额
amountTypeSyncData.setDiscountDesc("200元无门槛优惠券"); // 【必选】本次任务用户享受的优惠信息描述，比如优惠券名称，用于展示
amountTypeSyncData.setDiscountAmount("200.00"); // 【必选】本次任务用户享受的优惠金额，比如红包金额，用于展示
model.setAmountTypeSyncData(amountTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}逆向新增
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json",
"GBK", "alipay_public_key", "RSA2");
// 构建参数
ZhimaMerchantZmgoCumulateSyncModel model = new ZhimaMerchantZmgoCumulateSyncModel();
model.setAgreementId("ZMGO_AGR2021030510020604520000006001"); // 和正向记录的参数相同
model.setUserId("2088602002015001"); // 和正向记录的参数相同
model.setProviderPid("2088621805983504"); // 和正向记录的参数相同
model.setOutBizNo("R2020081211223006150094012926289"); // 商家侧本次请求流水号，和正向的流水号不同
model.setReferOutBizNo("P2020081211223006150094012926289"); // 本次逆向回传所对应的正向记录流水单号
model.setBizTime(DateFormat.parse("2019-04-08 19:51:35")); // 回传处理时间，代表本次逆向事件发生时间（如退款/退货等）
model.setBizAction("REVERSE"); // 代表一笔逆向累计数据，在概念上是"减掉"
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("TASK"); // 代表本次是任务型数据
// 使用任务金额类型数据模型
AmountTypeSyncData amountTypeSyncData = new AmountTypeSyncData();
amountTypeSyncData.setTaskDesc("购买XXX商品"); // 【必填】本次回退记录的描述
amountTypeSyncData.setTaskAmount("373.88"); // 【必填】本次回退金额
amountTypeSyncData.setDiscountDesc("200元无门槛优惠券"); // 【可选】本次回退优惠信息描述
amountTypeSyncData.setDiscountAmount("200.00"); // 【可选】本次回退优惠金额
model.setAmountTypeSyncData(amountTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}案例三：承诺任务（任务和优惠独立回传）
数据查询
接口调用
请求示例
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json", "GBK", "alipay_public_key", "RSA2");
ZhimaMerchantZmgoCumulateQueryRequest request = new ZhimaMerchantZmgoCumulateQueryRequest();
request.setBizContent("{" +
"\"agreement_id\":\"20195108518085620000\"," +
"\"user_id\":\"2088602002015001\"," +
"\"provider_pid\":\"2088621805983504\"," +
"\"need_detail\":false," +
"\"page_no\":1," +
"\"page_size\":20" +
" }");
ZhimaMerchantZmgoCumulateQueryResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}响应示例
AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json", "GBK", "alipay_public_key", "RSA2");
ZhimaMerchantZmgoCumulateQueryRequest request = new ZhimaMerchantZmgoCumulateQueryRequest();
request.setBizContent("{" +
"\"agreement_id\":\"20195108518085620000\"," +
"\"user_id\":\"2088602002015001\"," +
"\"provider_pid\":\"2088621805983504\"," +
"\"need_detail\":false," +
"\"page_no\":1," +
"\"page_size\":20" +
" }");
ZhimaMerchantZmgoCumulateQueryResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
System.out.println("调用成功");
} else {
System.out.println("调用失败");
}