系统交互

芝麻 GO 开通成功通知

轻研 API 商家需要监听 zhima.credit.pe.zmgo.sign.notify（芝麻GO业务签约变更商户通知）消息。

**注意：**该消息回调告诉商户签约成功,需要落相应的芝麻 GO 的协议号 agreement_id+alipay_user_id+biz_type，其中 agreement_status 代表签约成功还是失败，后续交互已协议号为准。

交互逻辑

芝麻 GO 轻研版新链路，签约成功之后会根据在开放平台配置的 appId 中的应用网关进行通知。

商家收到通知，记录关键信息 agreement_id、alipay_user_id、biz_type 以及 agreement_status。后续会用到 agreement_id 来进行优惠累计查询以及优惠累计回传。

任务数据回传&查询

商家调用 zhima.merchant.zmgo.cumulate.sync（商家芝麻GO累计数据回传接口）进行任务数据回传。

接口调用说明

商户将数据回传至芝麻侧，为用户C端展示既得优惠权益，同时在商家结算阶段，对结算金额校验，保证资金安全。

数据回传类型说明

是否累计任务进度	一级数据类型	二级数据类型	可组合数据类型
是	进度数据	任务金额类型	任务金额(必传)+优惠数据(可选)
任务次数类型	任务次数(必传)+任务金额(可选)+优惠数据(可选)
否	优惠数据	无	优惠数据(必传)

数据回传动作类型

**POSITIVE：**正向，代表一条累加的数据（类似于交易中的一笔支付）。

**REVERSE：**逆向，代表针对之前累加的数据的一条回退数据（类似于交易中的一笔退款）。

数据回传动作子类型

**ADD：**新增，代表一条全新新增的记录，out_biz_no 为新。

**UPDATE：**更新，代表针对一条已回传记录进行数据更新，out_biz_no 对应历史上已经存在的一条记录。

回传参数示例

如果商家要回传的数据需要累计进度，且任务类型（模版配置的）是金额型：

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-必传

接口使用案例

案例一：任务+次数类型

以某平台打车为例，芝麻 GO 模版配置了承诺次数任务类型：7 天内使用 2 次打车服务。接口调用示例如下：

正向新增

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("调用失败");
}

逆向新增

逆向回传是对一笔已经存在的正向记录的全部或者部分回退（类似于支付和退款的概念）。参数里需要额外设置ReferOutBizNo=对应的正向单据号、BizAction=REVERSE。

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("调用失败");
}

正向更新

设置 SubBizAction=UPDATE 代表是一次更新操作，同时 OutBizNo=已经存在的更新目标单据流水号。目前更新操作仅支持更新金额数值。

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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("POSITIVE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("TASK");  // 代表本次是任务型数据
// 使用任务金额类型数据模型
TimesTypeSyncData timesTypeSyncData = new TimesTypeSyncData();
timesTypeSyncData.setTaskAmount("13.88");       // 【可选】更新金额
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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setReferOutBizNo("P2020081211223006150094012926289"); // 和待更新单据值相同
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("REVERSE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("TASK");  // 代表本次是任务型数据
// 使用任务金额类型数据模型
TimesTypeSyncData timesTypeSyncData = new TimesTypeSyncData();
timesTypeSyncData.setTaskAmount("13.88");       // 【可选】更新金额
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("调用失败");
}

案例二：任务+金额类型

承诺金额类型或付费卡类型模版配置参考此案例。以某购物平台活动任务为例，模版配置了承诺金额任务类型：活动周期内电商消费金额满 10000 元。接口调用示例如下：

正向新增

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("调用失败");
}

正向更新

设置 SubBizAction=UPDATE 代表是一次更新操作，同时 OutBizNo=已经存在的更新目标单据流水号。目前更新操作仅支持更新金额数值。

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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("POSITIVE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("TASK");  // 代表本次是任务型数据
// 使用任务金额类型数据模型
AmountTypeSyncData amountTypeSyncData = new AmountTypeSyncData();
amountTypeSyncData.setTaskAmount("373.88");      // 【可选】更新金额
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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setReferOutBizNo("P2020081211223006150094012926289"); // 和待更新单据值相同
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("REVERSE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("TASK");  // 代表本次是任务型数据
// 使用任务金额类型数据模型
AmountTypeSyncData amountTypeSyncData = new AmountTypeSyncData();
amountTypeSyncData.setTaskAmount("373.88");      // 【可选】更新金额
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("调用失败");
}

案例三：单独优惠类型

当商家只需要回传用户已经享受的优惠数据，且这部分数据和用户进度累计无关时，可单独使用此模式。例如，用户的任务是一周签到7次，享受的优惠是 2 张购物优惠券，这种时候用户核销优惠券的行为和任务进度本身无关，数据回传后主要用于展示和作为后续扣款依据。接口调用示例如下：

正向新增

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("DISCOUNT");  // 代表本次是优惠型数据
// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountDesc("200元无门槛优惠券"); // 【必填】用户享受的优惠信息描述
discountTypeSyncData.setDiscountAmount("200.00");       // 【必填】用户享受的优惠金额
model.setDiscountTypeSyncData(discountTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
    System.out.println("调用成功");
} else {
    System.out.println("调用失败");
}

逆向新增

逆向回传是对一笔已经存在的正向记录的全部或者部分回退（类似于支付和退款的概念）。参数里需要额外设置 ReferOutBizNo=对应的正向单据号、BizAction=REVERSE。

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("DISCOUNT");  // 代表本次是优惠型数据
// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountDesc("200元无门槛优惠券"); // 【必填】回退的优惠信息描述
discountTypeSyncData.setDiscountAmount("200.00");       // 【必填】回退的优惠金额
model.setDiscountTypeSyncData(discountTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
    System.out.println("调用成功");
} else {
    System.out.println("调用失败");
}

正向更新

设置 SubBizAction=UPDATE 代表是一次更新操作，同时 OutBizNo=已经存在的更新目标单据流水号。目前更新操作仅支持更新金额数值。

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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("POSITIVE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("DISCOUNT");  // 代表本次是优惠型数据
// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountAmount("200.00");       // 【必填】更新优惠金额
model.setDiscountTypeSyncData(discountTypeSyncData);
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("P2020081211223006150094012926289"); // 需要更新的目标单据号
model.setReferOutBizNo("P2020081211223006150094012926289"); // 和待更新单据值相同
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 和待更新单据值相同
model.setBizAction("REVERSE"); // 代表一笔正向累计数据，在概念上是"累加"
model.setSubBizAction("UPDATE"); // 代表本次操作为更新一条记录类型
model.setDataType("DISCOUNT");  // 代表本次是优惠型数据
// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountAmount("200.00");       // 【必填】更新优惠金额
model.setDiscountTypeSyncData(discountTypeSyncData);
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizModel(model);
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
    System.out.println("调用成功");
} else {
    System.out.println("调用失败");
}

数据回传接口

具体请求参数、响应参数、错误码，可查看 zhima.merchant.zmgo.cumulate.sync（商家芝麻GO累计数据回传接口）文档。

请求示例

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do", "app_id", "your private_key", "json", "GBK", "alipay_public_key", "RSA2");
ZhimaMerchantZmgoCumulateSyncRequest request = new ZhimaMerchantZmgoCumulateSyncRequest();
request.setBizContent("{" +
    "\"agreement_id\":\"ZMGO_AGR2021030510020604520000006001\"," +
    "\"user_id\":\"2088602002015001\"," +
    "\"provider_pid\":\"2088621805983504\"," +
    "\"out_biz_no\":\"2020081211223006150094012926289\"," +
    "\"refer_out_biz_no\":\"2020081211223006150094012926289\"," +
    "\"biz_time\":\"2019-03-08 19:51:35\"," +
    "\"biz_action\":\"POSITIVE\"," +
    "\"sub_biz_action\":\"ADD\"," +
    "\"data_type\":\"TASK\"," +
    "\"amount_type_sync_data\":{" +
    "\"task_desc\":\"完成一次任务001\"," +
    "\"task_amount\":3.57," +
    "\"trade_no\":\"2020081722001435461000061785\"," +
    "\"has_alipay_trade\":false," +
    "\"discount_desc\":\"消费满减优惠001\"," +
    "\"discount_amount\":8.75" +
    "    }," +
    "\"times_type_sync_data\":{" +
    "\"task_desc\":\"完成一次任务001\"," +
    "\"task_times\":1," +
    "\"task_amount\":3.57," +
    "\"discount_desc\":\"消费满减优惠001\"," +
    "\"discount_amount\":8.75" +
    "    }," +
    "\"discount_type_sync_data\":{" +
    "\"discount_desc\":\"消费满减优惠001\"," +
    "\"discount_amount\":8.75" +
    "    }" +
    "  }");
ZhimaMerchantZmgoCumulateSyncResponse response = alipayClient.execute(request);
if (response.isSuccess()) {
    System.out.println("调用成功");
} else {
    System.out.println("调用失败");
}

响应示例

{
    "zhima_merchant_zmgo_cumulate_sync_response": {
        "code": "10000",
        "msg": "Success",
        "agreement_id": "20195108518085620000",
        "out_biz_no": "2020081211223006150094012926289",
        "fail_reason": "协议已经失效"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "zhima_merchant_zmgo_cumulate_sync_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

数据查询接口

具体请求参数、响应参数、错误码，可查看 zhima.merchant.zmgo.cumulate.query（商家芝麻GO累计数据查询接口）文档。

请求示例

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("调用失败");
}

响应示例

{
    "zhima_merchant_zmgo_cumulate_query_response": {
        "code": "10000",
        "msg": "Success",
        "agreement_id": "20195108518085620000",
        "aggr_amount": 99.99,
        "aggr_times": 4,
        "aggr_discount_amount": 83.88,
        "page_no": 1,
        "page_size": 20,
        "detail_list": [
            {
                "out_biz_no": "2020081211223006150094012926289",
                "refer_out_biz_no": "2020081211223006150094012926289",
                "biz_time": "2019-03-08 19:51:35",
                "action_type": "POSITIVE",
                "data_type": "TASK",
                "sub_data_type": "AMOUNT",
                "task_desc": "完成一次任务001",
                "task_amount": 17.88,
                "task_times": 1,
                "discount_desc": "消费满减优惠001",
                "discount_amount": 7.08
            }
        ],
        "fail_reason": "协议已经失效"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

异常示例

{
    "zhima_merchant_zmgo_cumulate_query_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "系统繁忙"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

协议变更消息通知说明

如系统交互流程图中 3.1.3、4.1.3，对于不同场景下（变更类型下），zhima.credit.pe.zmgo.agreement.changed（芝麻GO业务协议变更商户通知接口）的格式不同，且收到此消息后需要做不同的事情。

消息结构说明

可查看 zhima.credit.pe.zmgo.agreement.changed（芝麻GO业务协议变更商户通知接口）文档。

使用说明

此接口所有使用，请完成非空判断后，先进行 change_type 字段判断，根据判断结果进行对应变更类型的业务逻辑处理。任何不判断 change_type 字段的，都可能导致未来此消息格式改变时带来风险或开发成本。

changed_type = QUIT 时，保持原有逻辑（对于已经接入在线上运行的商户，changed_type 不存在时也保持原有逻辑，需要兼容线上已经发的消息）

changed_type = EXPIRE_DEFERRAL 时为延期失效消息，需要走延期失效逻辑。

对于 3.1.3、4.1.3 两个节点的消息，分别为协议退出与延期特权使用变更，针对这两个类型的参考处理流程如下：

芝麻GO结算成功通知

具体通知参数可查看 zhima.credit.pe.zmgo.settle.notify（芝麻GO业务结算变更商户通知接口）文档。

消息示例

ISV_GATEWAY_URL?charset=GBK&biz_content=
{
"withhold_plan_no":"ZMGO_WHD2021010910020603000000006002","trade_no":"20201212203423423420210110014004","agreement_id":"ZMGO_AGR2021012910020604010000000001","agreement_status":"Y","out_request_no":"63c0efbf3c62cf03ede783257ed66de8","rest_freeze_amount":"100.00","pay_amount":"100.00","alipay_user_id":"2088101117955611","partner_id":"2088101117955612","biz_time":"2021-01-29 11:35:59","pay_aisle_data":"API","trans_status":"Y","biz_type":"EASY_MEMBER","product_version":"zhimGoV2"
}
&msg_method=zhima.credit.pe.zmgo.settle.notify&utc_timestamp=1516797622752&version=1.1&sign_type=RSA2&notify_id=d275fec564e62af6bedbcee73f3f05fi5x&app_id=2013121700999429&sign=I+Y/lvqYUEEc10EPdpntRhFIQ==

**注意：**当接受到该结算成功消息的时候，先判断 agreement_status 为 N 且 trans_status=Y 代表芝麻 GO 协议为终态，此时商户的本地记录应该同步为终态，防止用户再次开通完成任务在累计回传的时候累计上一个协议。

响应值

响应值	描述	是否重试
fail	消息获取失败	重试
success	消息获取成功	不重试

商家需要提供

商家应用网关地址

商家 PID

商家 APPID

任务地址

轻研 API 接入

系统交互#

芝麻 GO 开通成功通知#

交互逻辑#

任务数据回传&查询#

接口调用说明#

数据回传类型说明#

数据回传动作类型#

数据回传动作子类型#

回传参数示例#

接口使用案例#

案例一：任务+次数类型#

正向新增#

逆向新增#

正向更新#

逆向更新#

案例二：任务+金额类型#

正向新增#

逆向新增#

正向更新#

逆向更新#

案例三：单独优惠类型#

正向新增#

逆向新增#

正向更新#

逆向更新#

数据回传接口#

请求示例#

响应示例#

异常示例#

数据查询接口#

请求示例#

响应示例#

异常示例#

协议变更消息通知说明#

消息结构说明#

使用说明#

芝麻GO结算成功通知#

消息示例#

响应值#

商家需要提供#

系统交互

芝麻 GO 开通成功通知

交互逻辑

任务数据回传&查询

接口调用说明

数据回传类型说明

数据回传动作类型

数据回传动作子类型

回传参数示例

接口使用案例

案例一：任务+次数类型

正向新增

逆向新增

正向更新

逆向更新

案例二：任务+金额类型

正向新增

逆向新增

正向更新

逆向更新

案例三：单独优惠类型

正向新增

逆向新增

正向更新

逆向更新

数据回传接口

请求示例

响应示例

异常示例

数据查询接口

请求示例

响应示例

异常示例

协议变更消息通知说明

消息结构说明

使用说明

芝麻GO结算成功通知

消息示例

响应值

商家需要提供