任务数据回传

商家可调用 zhima.merchant.zmgo.cumulate.sync（商家芝麻GO累计数据回传接口）将数据回传至芝麻侧，为用户 C 端展示既得优惠权益，同时在商家结算阶段，对结算金额校验，保证资金安全。

基础说明

数据回传类型说明

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

数据回传动作类型

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

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

数据回传动作子类型

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

回传参数示例

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

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

接口使用案例

案例一：任务+次数类型

运营商合作场景中，以下两个节点需要回传任务进度行为数据：

用户按时履约，在履约当月需回传任务行为更新任务进度，行为名称为：xx 月正常在网。

用户未完约定履约，但是商户调用芝麻 GO 扣除当月相关款项成功时，需回传任务行为更新任务进度，行为名称：5 月话费欠费，扣款xx元成功。

正向新增

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("5月正常在网"); // 【必填】本次任务记录的描述
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("P2020081211223006150094012926291"); // 商家侧本次请求流水号，对应唯一一笔回传数据
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 回传处理时间，代表导致回传的用户事件发生时间（如购买/核销等）
model.setBizAction("REVERSE"); // 代表一笔逆向累计数据，在概念上是"累加"
model.setReferOutBizNo("P2020081211223006150094012926289");//对应的这笔履约的正向单号
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("TASK");  // 代表本次是任务型数据

// 使用任务次数类型数据模型
TimesTypeSyncData timesTypeSyncData = new TimesTypeSyncData();
timesTypeSyncData.setTaskTimes(1L);             // 【必填】任务次数，必须设置，目前固定值只能为1
timesTypeSyncData.setTaskDesc("5月正常在网"); // 【必填】本次任务记录的描述
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("DISCOUNT");  // 代表本次是优惠型数据

// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountDesc("500元购机直降权益"); // 【必填】用户享受的优惠信息描述
discountTypeSyncData.setDiscountAmount("500.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"); // 回传数据对应的芝麻GO协议号
model.setUserId("2088602002015001"); // 用户在支付宝的用户ID
model.setProviderPid("2088621805983504"); // 商家PID
model.setOutBizNo("P2020081211223006150094012926290"); // 商家侧本次请求流水号，对应唯一一笔回传数据
model.setBizTime(DateFormat.parse("2019-03-08 19:51:35")); // 回传处理时间，代表导致回传的用户事件发生时间（如购买/核销等）
model.setBizAction("REVERSE"); // 代表一笔逆向累计数据，在概念上是"累加"
model.setReferOutBizNo("P2020081211223006150094012926289");//对应的这笔履约的正向单号
model.setSubBizAction("ADD"); // 代表本次操作为新增一条记录类型
model.setDataType("DISCOUNT");  // 代表本次是优惠型数据

// 优惠类型数据模型
DiscountTypeSyncData discountTypeSyncData = new DiscountTypeSyncData();
discountTypeSyncData.setDiscountDesc("500元购机直降权益"); // 【必填】用户享受的优惠信息描述
discountTypeSyncData.setDiscountAmount("500.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累计数据查询接口）查询对应芝麻 GO 协议汇总和明细信息。

接口调用

具体请求参数、响应参数、错误码，可查看 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"
}

优惠任务数据回传&查询

任务数据回传#

基础说明#

数据回传类型说明#

数据回传动作类型#

数据回传动作子类型#

回传参数示例#

接口使用案例#

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

正向新增#

逆向新增#

案例二：单独优惠类型#

正向新增#

逆向新增#

接口调用#

请求示例#

响应示例#

异常示例#

数据查询#

接口调用#

请求示例#

响应示例#

异常示例#

任务数据回传

基础说明

数据回传类型说明

数据回传动作类型

数据回传动作子类型

回传参数示例

接口使用案例

案例一：任务+次数类型

正向新增

逆向新增

案例二：单独优惠类型

正向新增

逆向新增

接口调用

请求示例

响应示例

异常示例

数据查询

接口调用

请求示例

响应示例

异常示例