1.概述

本文档的目标用户为支付宝充电桩业务接入端应用开发者。
本文档旨在说明支付宝IOT云端提供的充电桩交易日志接入方法以及第三方授权使用方法。

2.接入前准备

• 熟悉支付宝开放平台接入使用方法，申请并配置小程序。
• 下载SDK完整版(需支付宝内同学提供)，版本3.4.77.ALL及以上;当前SDK支持Java、.net、Python、PHP,若使用其他语言可以通过http请求访问。
• 确认安装包中存在类: com.alipay.api.request.AlipayCommerceIotMdeviceprodDevicelogUploadRequest
• 若使用第三方授权方式接入，请参考《第三方应用授权》。
  请务必在订单完结的时候，实时地回传数据，以保证数据的时效性。

3.接入日志格式

3.1 充电桩数据回流

用于上传运营商充电桩基础信息。
充电桩数据回流模板名称(template_name):chargePile。

TIPS:桩状态有变化是应重新回流充电桩数据。

3.2 充电订单数据回流

用户充电行为的数据回流（不包含用户充值行为）
充电订单数据回流模板名称(template_name):chargeOrder。

TIPS:若trade_no无法获取，可将trade_no设置为ORDERNO,并在扩展字段填写统一收单外部订单号，格式为ext_info:{“out_trade_no”:“外部订单号xxxx”}

3.3 换电订单回流

用户换电行为的数据回流,本模式用于商家自持电池的共享换电模式或用户自备电池租赁充电柜换电模式。
换电订单数据回流模板名称(template_name):exchangeOrder。

3.4 账户流水数据回流

针对用户账户发生支付的账户流水数据回流，主要包括以下场景：
- 单次充电时支付
- 余额充值时支付
- 包量购买时支付（月卡、次卡等）

账户流水数据回流模板名称(template_name):accountFlow。

4.接入代码示例

4.1 充电桩数据回流示例

public void addChargePipe(){
    AlipayClient alipayClient = new DefaultAlipayClient(URL, APPID, AppPrivateKey, "json", "GBK", AlipayPublicKey, "RSA");
    AlipayCommerceIotMdeviceprodDevicelogUploadRequest request = new AlipayCommerceIotMdeviceprodDevicelogUploadRequest();
    request.setBizContent("{\n" +
            "        \"template_name\": \"chargePile\",\n" +
            "        \"body\": {\n" +
            "            \"pile_id\":\"1738247\",\n" +
            "            \"type\":\"EV\",\n" +
            "            \"pile_type\":\"CP\",\n" +
            "            \"socket_num\":8,\n" +
            "            \"site_id\":\"s123134\",\n" +
            "            \"site_name\":\"xxx站点\",\n" +
            "            \"site_type\":\"GROUND\",\n" +
            "            \"province_code\":\"330000\",\n" +
            "            \"city_code\":\"330100\",\n" +
            "            \"area_code\":\"330106\",\n" +
            "            \"address\":\"xxx路xxx街xx号\",\n" +
            "            \"channel_biz_name\":\"xx渠道商\",\n" +
            "            \"property_name\":\"xx物业\",\n" +
            "            \"site_longitude\":120.15,\n" +
            "            \"site_latitude\":30.28\n" +
            "        }\n" +
            "    }");
    try {
        AlipayCommerceIotMdeviceprodDevicelogUploadResponse response = alipayClient.execute(request);
        if(response.isSuccess()) {
            System.out.println("success");
        }else{
            System.out.println(response.toString());
        }
    } catch (AlipayApiException e) {
        e.printStackTrace();
    }
}

4.2 充电订单回流接口示例

public void addChargeOrderLog(){
    AlipayClient alipayClient = new DefaultAlipayClient(URL, APPID, AppPrivateKey, "json", "GBK", AlipayPublicKey, "RSA");
    AlipayCommerceIotMdeviceprodDevicelogUploadRequest request = new AlipayCommerceIotMdeviceprodDevicelogUploadRequest();
    request.setBizContent("{" +
            "        \"template_name\": \"chargeOrder\"," +
            "        \"body\": {" +
            "            \"doc_type\":\"Charge\"," +
            "            \"order_no\":\"OD2018110283948294948\"," +
            "            \"charge_time\":\"2018-12-01 10:10:10\"," +
            "            \"pile_no\":\"2891839\"," +
            "            \"socket_no\":\"8\"," +
            "            \"user_select_duration\":55," +
            "            \"actual_duration\":53," +
            "            \"charge_amount\":17.4," +
            "            \"charging_mode\":\"ThirdPay\"," +
            "            \"pay_channel\":\"Alipay\"," +
            "            \"client\":\"Alipay\"," +
            "            \"uid\":\"20889384894823\"," +
            "            \"isv_uid\":\"823942847293\"," +
            "            \"trade_no\":\"20181201101010857239749753823\"" +
            "        }" +
            "    }");
    try {
        AlipayCommerceIotMdeviceprodDevicelogUploadResponse response = alipayClient.execute(request);
        if(response.isSuccess()) {
            System.out.println("success");
        }else{
            System.out.println(response.toString());
        }
    } catch (AlipayApiException e) {
        e.printStackTrace();
    }
}

4.3 换电订单回流接口示例

public void addChargeOrderLog(){
    AlipayClient alipayClient = new DefaultAlipayClient(URL, APPID, AppPrivateKey, "json", "GBK", AlipayPublicKey, "RSA");
    AlipayCommerceIotMdeviceprodDevicelogUploadRequest request = new AlipayCommerceIotMdeviceprodDevicelogUploadRequest();
    request.setBizContent("{" +
            "        \"template_name\": \"exchangeOrder\"," +
            "        \"body\": {" +
            "            \"doc_type\":\"Share\"," + 
            "            \"order_no\":\"OD2018110283948294948\"," +
            "            \"biz_time\":\"2018-12-01 10:10:10\"," +
            "            \"site_id\":\"2891839\"," +
            "            \"cabinet_no\":\"192848\"," +
            "            \"socket_no\":\"8\"," +
            "            \"actual_duration\":53," +
            "            \"actual_electricity\":10.3," +
            "            \"charge_amount\":17.4," +
            "            \"charging_mode\":\"ThirdPay\"," +
            "            \"pay_channel\":\"Alipay\"," +
            "            \"client\":\"Alipay\"," +
            "            \"uid\":\"20889384894823\"," +
            "            \"isv_uid\":\"823942847293\"," +
            "            \"trade_no\":\"20181201101010857239749753823\"" +
            "        }" +
            "    }");
    try {
        AlipayCommerceIotMdeviceprodDevicelogUploadResponse response = alipayClient.execute(request);
        if(response.isSuccess()) {
            System.out.println("success");
        }else{
            System.out.println(response.toString());
        }
    } catch (AlipayApiException e) {
        e.printStackTrace();
    }
}

4.4 账户流水数据回流示例

public void addAccountFlowLog(){
    AlipayClient alipayClient = new DefaultAlipayClient(URL, APPID, AppPrivateKey, "json", "GBK", AlipayPublicKey, "RSA");
    AlipayCommerceIotMdeviceprodDevicelogUploadRequest request = new AlipayCommerceIotMdeviceprodDevicelogUploadRequest();
    request.setBizContent("{" +
            "        \"template_name\": \"accountFlow\"," +
            "        \"body\": {" +
            "            \"order_no\":\"OD2018110283948294948\"," +
            "            \"trade_type\":\"Once\"," +
            "            \"amount\":50.5," +
            "            \"pay_channel\":\"Alipay\"," +
            "            \"trade_no\":\"20181201010110939847582374348\"" +
            "        }" +
            "    }");
    try {
        AlipayCommerceIotMdeviceprodDevicelogUploadResponse response = alipayClient.execute(request);
        if(response.isSuccess()) {
            System.out.println("success");
        }else{
            System.out.println(response.toString());
        }
    } catch (AlipayApiException e) {
        e.printStackTrace();
    }
}

5.第三方应用接入

第三方商户向开发者授权后,可以使用开发者提供的充电桩数据回流能力，具体第三方授权开发请参考《第三方应用授权》。

6.接入流程

(1) 开放平台申请小程序或使用已有小程序。
(2) 开发
(3) 测试环境调试
测试环境用于测试上传日志链路联通性，解决使用过程中程序问题。
测试环境接入网关：//openapi.sit.dl.alipaydev.com/gateway.do
(4) 预发环境验证
预发环境用于验证程序在生产环境中能否正常使用，该环境与生产环境相同，仅用于小批量数据验证。预发环境需联系支付宝对接同学临时授权。
预发环境接入网关：https://openapipre.alipay.com/gateway.do
(5) 上线
生产环境接入网关：https://openapi.alipay.com/gateway.do
生产环境需要支付宝进行挂包，可联系对接同学。

7.Q&A

(1) appid如何申请？
appid是小程序id,可以在开放平台申请https://openhome.alipay.com/platform/home.htm
(2) 接口请求提示权限问题。
本接口为定向开放接口，需要单独授权。在预发环境中可通知支付宝同学临时授权，可以有5天的访问时间进行程序功能验证。预发环境验证成功之后，通知支付宝同学挂包，长期授权使用。

FAQ