环保中台集成文档

更新时间：2023/06/08 访问次数：6516

1、名词解释
2、业务须知
3、准备工作
4、整体流程
5、接口列表
6、联调环境
7、各场景方案介绍
8、上线前准备
9、上线后遇到困难

1、名词解释

名词	解释
蚂蚁森林	蚂蚁森林是支付宝客户端为首期"碳账户"设计的一款公益行动：用户通过步行、地铁出行、在线缴纳水电煤气费、网上缴交通罚单、网络挂号、网络购票、二手回收等行为，就会减少相应的碳排放量，可以用来在支付宝里养一棵虚拟的树。这棵树长大后，公益组织、环保企业等蚂蚁生态伙伴们，可以“认领”用户在蚂蚁森林里种植的虚拟“树”，而在现实某个地域种下一棵实体的树。
环保中台	支付宝环保中台，为合作伙伴提供环保回收场景定向能力
ISV	(Independency Software Vendor)独立软件供应商

2、业务须知

文档范围：本文档阅读对象为有技术开发能力的ISV或商户，本文档API接口范围仅涉及蚂蚁森林能量发放，用户信息获取、小程序相关接口请参考开放平台官方文档，在此并不赘述。

业务整体介绍：各角色和场景可参考下图，商户、服务商等合作伙伴可基于环保中台获得蚂蚁森林绿色能量发放能力，能量所需费用以捐赠的形式，通过环保中台代扣至公益基金会，目前公益基金会仅支持中华环境保护基金会。

3、准备工作

签约准备：合作伙伴首先与公益基金会线下签约，获得蚂蚁森林绿色能量捐赠权利。然后同支付宝进行环保中台协议签约和代扣授权，即授权环保中台代为公益基金会为合作伙伴进行蚂蚁森林绿色能量的代捐赠，同时合作伙伴获得调用绿色能量发放和查询的接口权限。

系统准备：该集成方案无特殊软硬件系统要求，仅需系统能访问公网，通过https调用支付宝api接口。

各方职责：技术合作伙伴负责按照接入前准备工作，完成账号注册、签约合作工作，并对接支付宝环保中台api接口，完成业务上线；支付宝可免费提供线上技术支持，协助合作伙伴快速落地业务。

4、整体流程

合作伙伴在线上或线下场景，基于环保中台已公开的蚂蚁森林能量兑换规则，进行对应能量发放，及根据用户的不同环保行为，直接调用蚂蚁森林绿色能量发放接口（alipay.eco.activity.recycle.send）即可，调用接口成功后，用户即可在支付宝APP蚂蚁森林内看到待领取的绿色能量，用户可于24小时之后领取能量，如果用户希望马上领取，可以通过时光加速器等背包工具进行快速获取。

合作伙伴也可通过蚂蚁森林绿色能量查询接口（alipay.eco.activity.recycle.query）进行该次能量发放记录的相关查询。

主要业务流程

能量发放规则

用户低碳行为对应的能量规则由第三方机构出具的碳减排方法学报告确定；
能量发放对应的公益捐赠金，279元/1吨
如需新增绿色低碳场景，可联系对应bd进行评估，但最终需以第三方机构受理并出具的碳减排方法学报告为准，相关SOP如下所示。

代扣资金流程（环保中台系统自动运作，仅供了解）

环保中台每日基于T日应收能量计算金额，并自动进行代扣作业，因此合作伙伴务必保证代扣账户足额，以免扣款失败造成能量无法继续发放的问题。

环保中台作为公益基金会的技术提供方执行代扣，环保中台不参与资金结算，保证捐赠通道公开透明。

5、接口列表

接口名称	接口API	使用场景
森林能量发放	alipay.eco.activity.recycle.send	根据用户的回收清单进行蚂蚁森林绿色能量的发放
森林能量查询	alipay.eco.activity.recycle.query	根据蚂蚁森林绿色能量发放申请单查询绿色能量发放记录

如何判定能量发放成功

场景1：通过能量发放接口

调用能量发放接口后，如code等于10000，full_energy存在且大于0，则表示能量发放成功，成功示例如下：

{"alipay_eco_activity_recycle_send_response":{"msg":"Success","code":"10000","full_energy":1377},……

其他情况说明能量发放失败，失败示例之一如下：

{"alipay_eco_activity_recycle_send_response":{"code":"40004","msg":"Business Failed","sub_code":"ENERGY_GRANT_AUTH_CLOSE","sub_msg":"用户关闭授权"},……

场景2：通过能量查询接口

当因网络异常或系统异常导致能量发放接口无法获得应答信息，此时可通过能量查询接口查询能量发放记录。

调用能量查询接口后，如code等于10000，energy_list存在，且result字段为true、full_energy大于0，则表示该查询订单能量发放成功，成功示例如下：

{"alipay_eco_activity_recycle_query_response":{"msg":"Success","code":"10000","energy_list":[{"result":true,"item_name":"旧鞋回收","full_energy":"1377","items":[{"ext_key":"ITEM_TYPE","ext_value":"jiuxie"}]}]},"sign":"……

其他情况说明该笔订单的能量发放失败，失败示例之一如下：

{"alipay_eco_activity_recycle_query_response":{"msg":"Success","code":"10000","energy_list":[{"result":false,"failed_msg" :"用户授权关闭","item_name":"旧鞋回收","full_energy":"1377","items":[{"ext_key":"ITEM_TYPE","ext_value":"jiuxie"}]}]},"sign":"……

6、联调环境

SDK下载：下载地址

如希望在线上环境进行联调测试，可以直接使用已签约的线上账号进行联调测试，如尚未签约线上账号可以优先进行账号申请的工作推进。同时支付宝提供了线下测试环境供合作伙伴进行开发联调测试，具体环境信息如下，注意线下测试环境与线上生产环境不同。

线下测试环境及测试账号

1、线下测试环境openapi网关地址（注意生产环境网关地址不同）
“http ://openapi.stable.dl.alipaydev.com/gateway.do”

2、线下测试可指定开发机器调用，如：在request里加个参数
String wsServiceUrl = "minipcodemarket-0.gz00b.stable.alipay.net:12200";
request.putOtherTextParam("ws_service_url", wsServiceUrl);

3、测试商户数据及代码示例参考各场景方案介绍。下面以旧鞋回收为例，回收一双旧鞋

public void sendEnergy() throws AlipayApiException  {
    AlipayEcoActivityRecycleSendModel model = new AlipayEcoActivityRecycleSendModel();
    model.setOutBizNo("green" + System.currentTimeMillis());
    model.setOutBizType("RECYCLING");       // 场景类型，决定不同场景的能量发放规则
    model.setBuyerId("2088302915220493");   // 获得能量的用户uid
    model.setSellerId("2088302088119497");  // 发放能量的商户pid

    EnergyExtRequest ext = new EnergyExtRequest();
    ext.setExtKey("ITEM_TYPE");
    ext.setExtValue("jiuxie");        // 子场景码，定义具体能量发放的场景

    EnergyGoodRequest item = new EnergyGoodRequest();
    item.setItemName("旧鞋回收");
    item.setQuantity("1");
    item.setItems(Lists.newArrayList(ext));
    model.setItemList(Lists.newArrayList(item));

    AlipayEcoActivityRecycleSendRequest request = new AlipayEcoActivityRecycleSendRequest();
    request.setBizModel(model);
    AlipayEcoActivityRecycleSendResponse response = client.execute(request);

    System.out.println(response.getBody());
    LogUtils.dumpResponse(response);
    System.out.println(model.getOutBizNo());
}