智充开发接口

关于智充X-Cloud开放接口

智充X-Cloud（又称为智充云）是连接和管控物理充电设备的云端平台系统，旨在实现各项核心充电业务和管理流程，在其上可以构建面向充电用户、面向充电运营商、面向合作伙伴的应用系统。本开放接口是为那些使用智充充电设备及智充X-Cloud整体解决方案，同时又希望自行设计和开发互动充电流程的客户（也称为接入方）而准备的。通过该接口，客户可以定制出完全融合自身业务特点和功能需求的充电App，在为充电用户提供更加贴心的使用体验的同时，也能实现自身独特的运营模式和商业模式。本接口暂不包含对充电设备、充电数据的完备操作功能，客户仍可使用智充提供的运营后台系统来管理自身的充电业务。

接口访问方式

本接口的访问地址为https://api.xcharger.net/{method_url} ，“method_url”是各接口方法的相对网址。

接入方需要从智充获取接入许可，以及:

App ID：接入方的应用标识。
App Secret：密钥。
Notification URL：由接入方提供给智充的事件通知网址（notifyBase）。

为了确保安全，一些重要的接口方法需要提供签名：signature=SHA1(body+timestamp+nonce+appSecret)，其中：

“body”是字符串形式的HTTP POST请求体。如果是HTTP GET请求，则“body”为空。
“timestamp”是时间戳，为十进制长整数。计算时间戳的起始时间是1970-01-01 08:00:00（北京时间），精确到毫秒。
“nonce”是随机字符串。每次签名的nonce应该都不一样。
“appSecret”是密钥。
“+”是字符串连接操作。

在使用各接口方法之前，需要先调用“获取Token”方法来获取合法的令牌（即Token），以后每次调用时，都需要传入合法的Token，否则智充X-Cloud会返回认证失败的错误（AUTH_FAILED）。该Token需要定期更新。

请求参数的位置：

query：如果参数的位置是“query”，表示该参数需要出现在接口网址的queryString部分，例如：https://api.xcharger.net/site/v1.0?lng=106.8756&lat=30.7629 中的参数“lng”和“lat”。
path：如果参数的位置是“path”，表示该参数需要出现在接口网址中，例如：https://api.xcharger.net/site/{id}/v1.0 中的参数“id”。
body：如果参数的位置是“body”，表示该参数需要出现在JSON格式的HTTP POST请求体中，例如：如下的参数“deviceId”、“port”、“userId”。

POST https://api.xcharger.net/charge/start/v1.0
Content-Type: application/json; charset=UTF-8
{
    "deviceId": "C2011601CNBRWIKL",
    "port": 1,
    "userId": 610012
}

X-Cloud响应的内容：

处理成功（无返回信息）：

Content-Type: application/json; charset=UTF-8
{
}

处理成功（有返回信息）：
```
Content-Type: application/json; charset=UTF-8
{
    "result": Any
}
```
其中“result”的具体内容参见各个接口方法的描述。

处理失败：

Content-Type: application/json; charset=UTF-8
{
    "error": {
        "code": String,
        "msg": String,
        "data": Any
    }
}

以上三种情况，X-Cloud响应的HTTP Status Code均为200。

如果智充X-Cloud需要主动向接入方发送通知消息，称为事件（Event），将用HTTP POST的方式调用接入方提供的事件通知网址。接入方需要准备好这些回调方法。

基本概念

充电设备（Device），简称设备，俗称充电桩，是连接到智充X-Cloud的物理充电设施。所有设备须事先通过运营后台添加到智充X-Cloud，才能被本开放接口访问到。充电设备分为交流慢充（Slow Charger）、直流快充（Fast Charger）。一台充电设备可能有多个充电口（Port）。充电设备可以属于某个个人，称为桩主（Owner），桩主本身也是充电用户（User）。
充电站点（Site），简称站点，是部署有若干充电设备的物理场所。站点可以是共享的（Shared），即允许公众用户前来充电，并按公示的资费标准向其收取充电费用。
充电费用（Fee）包括：
- 电费（Power Fee）：实际消耗的电力的费用，按充电电量（度）计费；
- 服务费（Service Fee）：运营平台收取的服务费，按充电电量（度）计费；
- 延误费（Delay Fee）：充电结束后，如果用户没有及时拔枪并挪车，系统将计延误费用，按延误时长（分钟）计费。
充电费用在各个时段的收费费率由资费标准（Fee Policy）定义。资费标准需要下发到各个充电设备，以便其在充电过程中准确计算资费。一旦下发，资费标准的内容就不应该再被变更，除非生成新的标准再次下发给设备。
一个充电过程大致包括以下步骤:

发起充电请求（Initiate Charge Request）。用户可以通过接入方的App发起充电请求，也可以通过其它途径（例如在充电设备上刷卡）自行发起充电请求。如果是后者，X-Cloud将通知接入方。无论是哪种情况，都需要由接入方对用户的请求进行鉴权。
启动充电（Request Starting Charge）。接入方调用“启动充电”方法告知X-Cloud充电请求鉴权成功，可以通知设备启动充电过程。如果鉴权失败，接入方应调用“拒绝充电”方法告知X-Cloud，以便把提示信息展示到充电设备上。
开始充电（Charge Started）。设备接收到启动充电的指令后，开始进行自检，并提示（或检查）用户插枪，如果一切就绪，设备正式开始充电；否则，设备将上报充电已取消（Charge Cancelled）。
充电中（Charging）。在充电过程中，设备会定时（例如每1分钟）上报当前的充电状态（Charge Status），包括：当前功率、已充电量、累积费用等等。每个充电过程有一个充电号（Charge ID），可以通过该ID来查询当前的充电状态。
充电结束（Charge Stopped）。接入方可以主动结束充电，设备也可能根据预设的条件自动结束充电。充电结束后，用户应尽快拔枪挪车，否则有可能被收取延误费。
充电完成（Charge）。用户拔枪后，充电过程完成。设备上报完整的充电账单（Charge Bill），接入方负责通知用户支付该账单，并将支付结果告知智充X-Cloud。

智充X-Cloud开放接口 v1.0

关于智充X-Cloud开放接口

接口访问方式

请求参数的位置：

X-Cloud响应的内容：

基本概念