<a name="table-of-contents"></a>
## Table of contents
- [Get Started](#Get-Started)
- BACKEND API
- [Get Station List](#Get-Station-List)
- [Get Station Charge Point List](#Get-Station-Charge-Point-List)
- [Setup Vehicle Charging Info Callback](#Setup-Vehicle-Charging-Info-Callback)
- [Setup Payment Result Callback](#Setup-Payment-Result-Callback)
- [Get Vehicle Profile](#Get-Vehicle-Profile)
- [Set Payment Link](#Set-Payment-Link)
- [Remote Stop Charging](#Remote-Stop-Charging)
- [Get Charge Transaction History](#Get-Charge-Transaction-History)
- [Report Charge Point Error](#Report-Charge-Point-Error)
- Flow
- [Initilize Process](#Initilize-Process)
- [Cron Process](#Cron-Process)
- [Charge transaction Process](#Charge-Transaction-Process)
- Appendix
- [Vehicle Charging Info](#Vehicle-Charging-Info)
- [Payment Info](#Payment-Info)
- [Transaction Info](#Transaction-Info)
- [Vehicle Charging Info Callback Response](#Vehicle-Charging-Info-Callback-Response)
- [Payment Result Callback Response](#Payment-Result-Callback-Response)
<a name="get-started"></a>
# Get Started
- Refer to integrate TRay Charging Process for mobile application.
# BACKEND API
- 請勿使用 app 呼叫上述 api 會有資訊安全問題，請藉由 api server 來進行對接，header 需要帶上以下資訊
| Field | Type | Description |
| :--- | :--- | :--- |
| X-TRAY-APIKEY | string | api key (由 tray 提供的) |
| X-TRAY-NONCE | string | 將 request 的 url 進行 base64 編碼 |
| X-TRAY-SIGNATURE| string | 使用 SHA256-HMAC 以 api secret (由 tray 提供的) 簽名 X-TRAY-NONCE 產生出來的簽章，POST method 需要多簽名 base64 編碼的 body |
<a name="get-station-list"></a>
## Get Station List
Retrieve all station information ordered by Station ID, with pagination, which will be updated every 5 minutes, while adhering to a rate limit of 10 requests per minute.
*Please storage response in your own data storage and update latest information every 5 minutes.*
**`GET`** /v1/station/info?limit=`LIMIT`&offset=`OFFSET`
##### Request Format
An example of the request:
###### API with query string
```
/v1/station/info?limit=50&offset=1
```
The request includes the following parameters:
###### Query string
| Field | Type | Description |
| :--- | :--- | :--- |
| limit | int | Data size of the search, max=50 |
| offset | int | The starting index of the search |
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| id | int | charging station unqiue id |
| name | string | charging station name |
| operating_hours | string | charging station business hours |
| support_connector_types | array of string | support charging connector types for EV charging (eg. CCS2) |
| available_connector_count | int | number of available charging connector |
| unavailable_connector_count | int | number of unavailable charging connector |
| latitude | float | charging station latitude |
| longitude | float | charging station longitude |
An example of a successful response:
```json
{
"stations": [
{
"id": 3244563,
"name": "特斯拉中和環球購物中心",
"operating_hours": "11:00~22:00",
"support_connector_types" : ["Telsa TPC", "CCS2"],
"available_connector_count" : 16,
"unavailable_connector_count": 0,
"latitude": 24.971233707456822,
"longitude": 121.53587873345099
},
{
"id": 3224564,
"name": "桃園新明國小停車場",
"operating_hours": "11:00~22:00",
"support_connector_types" : ["CCS2"],
"available_connector_count" : 10,
"unavailable_connector_count": 0,
"latitude": 24.971233707456823,
"longitude": 121.53587873345098
},
]
}
```
<a name="get-station-charge-point-list"></a>
## Get Station Charge Point List
Retrieve charge point list by station id.
**`GET`** /v1/cp/list?station_id=`STATION_ID`
##### Request Format
An example of the request:
###### API with query string
```
/v1/cp/list?station_id=3224564
```
The request includes the following parameters:
###### Query string
| Field | Type | Description |
| :--- | :--- | :--- |
| station_id | int | station unqiue id |
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| id | int | charging point unqiue id |
| serial_number | string | charge point serail number |
| support_connector_types | array of string | support charging connector types for EV charging (eg. CCS2) |
| connector_id_list | array of int | charge point connector id list |
An example of a successful response:
```json
{
"charge-points": [
{
"id": 3244563,
"serial_number": "112405963",
"support_connector_types": ["CCS2"],
"connector": [11111, 11112]
},
{
"id": 3244323,
"serial_number": "112405964",
"support_connector_types": ["Tesla TPC"],
"connector": [11113, 111114]
},
]
}
```
<a name="setup-vehicle-charging-info-callback"></a>
## Setup Vehicle Charging Info Callback
Setup Vehicle Charging Info once. Charging information for multiple vehicles every 5 seconds will be sent back to this callback URL.
Reponse can reference to [Vehicle Charging Info Callback Response](#vehicle-charging-info-callback-response)
*Can only set once a day if need to.*
**`POST`** /v1/vehicle/setup-charge-info-callback
##### Request Format
An example of the request:
###### Post body
```json
{
"callback_url": "https://domain.com:8080/charge-status/callback",
}
```
The request includes the following parameters:
###### Post body
| Field | Type | Description |
| :--- | :--- | :--- |
| callback_url | string | the url callback when charge event be triggered. |
##### Response Format
An example of a successful response:
```json
{
"success": true
}
```
The response includes the following parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| success | bool | SUCCESS: true, FAIL: false |
<a name="setup-payment-result-callback"></a>
## Setup Payment Result Callback
Setup Payment Result Callback. Payment information every 5 seconds will be sent back to this callback URL.
Reponse can reference to [Payment Result Callback Response](#payment-result-callback-response)
*Can only edit once a day if need to.*
**`POST`** /v1/payment/setup-payment-result-callback
##### Request Format
An example of the request:
###### Post body
```json
{
"callback_url": "https://domain.com:8080/payment/callback",
}
```
The request includes the following parameters:
###### Post body
| Field | Type | Description |
| :--- | :--- | :--- |
| callback_url | string | the url callback for payment result. |
##### Response Format
An example of a successful response:
```json
{
"success": true
}
```
The response includes the following parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| success | bool | SUCCESS: true, FAIL: false |
<a name="get-vehicle-profile"></a>
## Get Vehicle Profile
Get Vehicle Profile By Charge Point ID and Connector ID.
**`GET`** /v1/vehicle/profile?cp_id=`CP_ID`&ctr_id=`CONNECTOR_ID`
##### Request Format
An example of the request:
```
/v1/vehicle/profile?cp_id=1&ctr_id=1
```
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| vehicle_id | string | vehicle unqiue id |
| status | int | 0 no vehicle 1 normal 2 forbidden |
An example of a successful response:
```json
{
"vehicle_id": "000A020B030C",
"status": 1,
}
```
<a name="Set-Payment-Link"></a>
## Set Payment Link
Set Payment Link for Intella.
**`POST`** /v1/payment/link`
##### Request Format
An example of the request:
###### Post body
```json
{
"tx_id": "Fekj7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVb",
"price": 100
}
```
The request includes the following parameters:
###### Post body
| Field | Type | Description |
| :--- | :--- | :--- |
| transaction_id | string | ID of charging transaction |
| price | int | charging price |
##### Response Format
An example of a successful response:
```json
{
"payment_url": "https://a.intella.co/378d4827bb2",
}
```
The response includes the following parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| payment_url | string | intella payment url |
<a name="Remote-stop-charging"></a>
## Remote Stop Charging
Remote Stop Charging.
**`POST`** /v1/vehicle/stop-charging`
##### Request Format
An example of the request:
###### Post body
```json
{
"transaction_id": "Fekj7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVb"
}
```
The request includes the following parameters:
###### Post body
| Field | Type | Description |
| :--- | :--- | :--- |
| transaction_id | string | ID of charging transaction |
##### Response Format
An example of a successful response:
```json
{
"success": true,
}
```
The response includes the following parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| success | bool | stop charging success or not |
<a name="get-charge-transaction-history"></a>
## Get Charge Transaction History
Get charge transaction history list.
**`GET`** /v1/vehicle/tx/list?vehicle_id=`VEHICLE_ID`
##### Request Format
An example of the request:
```
/v1/vehicle/tx/list?vehicle_id=000A020B030C
```
The request includes the following parameters:
###### Query string
| Field | Type | Description |
| :--- | :--- | :--- |
| vehicle_id | string | vehicle id |
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| history | array of [Transaction Info](#transaction-info) | vehicle transaction histroy |
An example of a successful response:
```json
{
"history":
[
{
"transaction_id":"Fekj7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVb",
"station_name": "水源市場",
"connector_type": ["CCS1"],
"payment_method": "街口支付",
"start_timestamp": 1680182889,
"end_timestamp": 16801830000,
"price": 100
},
{
"transaction_id":"Abdc7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVa",
"station_name": "中正國中",
"connector_type": ["CCS1"],
"start_timestamp": 1680282889,
"end_timestamp": 16802830000,
"price": 200
},
]
}
```
<a name="report-charge-point-error"></a>
## Report Charge Point Error
Report faulty charging point's connector.
**`POST`** /v1/report-cp-error
##### Request Format
An example of the request:
###### Post body
```json
{
"cp_id": 1,
"connector_id": 1,
"category": 0,
"other_contet": "",
"img_url": ""
}
```
The request includes the following parameters:
###### Post body
| Field | Type | Description |
| :--- | :--- | :--- |
| cp_id | int | charge point id|
| connector_id | int | charge point id|
| category | int | report category 0: 充電樁無法正常通電, 1:充電樁被油車佔用 |
##### Response Format
An example of a successful response:
```json
{
"success": true,
}
```
The response includes the following parameters:
| Field | Type | Description |
| :--- | :--- | :--- |
| success | bool | SUCCESS: true, FAIL: false |
# Flow
<a name="initilize-process"></a>
## Initilize Process
[](https://mermaid.live/edit#pako:eNqd0EFLAkEUAOC_MszJyP7AHoSyS5eQjE57ec0-dWl31saZQERQSRJWyEtRakaXijAvUURWv8bZ1VN_oVnKfkBzecPj8d73Xo2ywEFq0QoeKuQMN10oCvBtTszLgZAcBdkAdoDcIXkURyjWMpnVXQFVsp7b-k1ZJkpVJntYcpmHJFsCUUSyHUi34DKQbsBJan7_qCf9-OxlcR7qu1C324vBdN45iZ970dV1dNli4Hn7ZhSJ-8dECW_ln4ocVH3kkuxgRXmSZJdtk8qUPn1YDBvz26Zu9mevjWh88_XenX0M49bbbHoRjT_1pBt1enow0q2nOGxE7TABjoYJ6k9odORnH4Okaeqj8MF1zCFrCdqmsoQ-2tQyXwcLYBw2tXndlIKSQb7KGbWkUJimquyAXN6dWgXwKlj_Bur2sAw)
<a name="cron-process"></a>
## Cron Process
[](https://mermaid.live/edit#pako:eNo1jjEKwkAQRa-yTGu8wBaCIohgEYjlNMPuRBezE53MCiHk7m4Kf_WKz-MtEMbI4GHiT2EJfE70UMoorq4lNWF1JwovluiO7XV_OOzuSvPGrmP9snp3YXOdkaVR3C1NhoICDWTWTClW-7L5EOzJmRF8xcg9lcEQUNZ6pWJjN0sAb1q4gfKOZP8Y8D0NE68_rUI6rQ)
- 請將抓到的 station list 存在自己的資料庫中，每 5 分鐘再抓新資料更新
<a name="charge-transaction-process"></a>
## Charge Transaction Process
[](https://mermaid.live/edit#pako:eNqVkt9LG0EQx_-VYZ8iXP-BexD8AUUQCVr7dFDWu4lZcrene3tCEOFaCaJpmjxYKkT8gT6q0YiQGslfk73c_RfdeN5LkxbcfZhhduazs7PfXWL7DhKTBLgdIrdxkdFNQT2LWxz0KlIhOQqYp3YFuQNzxSX4MDv7SdDqq7-GYgeFCR9RwmcsM9tFKAq_xLQtbFTB3vrCHANsKbSdyZh_FY950-4xYdToqsEv2Mm4r6BAUhkGUOC-8KgL8WFDDaJhr5483f-bPhWed7tQpmITYcWXrMRsKpnPYYG67oZOhkJyfRD_7KlaLW33R0-t-Ox02Ls1QDU7WXPxeQvWA81-S6lHca1uQNI_UrctHUgPmullZ3T9bMCofacOG8nRQ9Ltq_3f8cXLzPtnXKRVD7mEZcYr-XyWuETXpTDsn8Q3gzS60o3-l5xXmJBGzfTrj6mENOoml9_j444OZrQ8a0yYaC4rzUak2mfq2-P7viN_2CoGoSsnfmAS_za8sVCzTQzioVYFc7Scd8enFpFl9NAipnYdLFFNtojF93QqDaW_VuU2MaUI0SDhlkNlrn5ilqgb4N4f62hNQw)
- 預計充電樁、槍上會有 QR code 可以使 app 獲得 cp_id, ctr_id 回傳給 Partner 自己的 api 再打過來 TrayAPI Server
- Get Vehicle Profile status 為 forbidden 即表示為非法車載
- 綁定信用卡目前合作方還未回覆相關資訊
##### [Back to top](#table-of-contents)
# Appendix
<a name="vehicle-charging-info"></a>
## Vehicle Charging Info
<table>
<tr>
<td>Field</td>
<td>Type</td>
<td>Description</td>
</tr>
<tr>
<td>vehicle_id</td>
<td> string </td>
<td>ID of vehicle</td>
</tr>
<tr>
<td>transaction_id</td>
<td> string </td>
<td> charging transaction id</td>
</tr>
<tr>
<td>battery_status</td>
<td> float64 </td>
<td>vehicle overall battery percentage</td>
</tr>
<tr>
<td>charging_accum_price</td>
<td> int </td>
<td>current charing price </td>
</tr>
<tr>
<td>idle_start_timestamp</td>
<td> int </td>
<td>idle start timestamp, 0 means no idle </td>
</tr>
<tr>
<td>idle_end_timestamp</td>
<td> int </td>
<td>idle end timestamp, 0 means no idle, 1 means still idle </td>
</tr>
<tr>
<td>idle_accum_price</td>
<td> int </td>
<td>accumulated price caused by not pulling out the charging gun from the car(idle), 0 means no idle </td>
</tr>
<tr>
<td>charging_status</td>
<td>int</td>
<td rowspan="2">
<b>0</b> - CHARGING<br>
<b>1</b> - END<br>
</td>
</tr>
<tr/><tr/>
</table>
<a name="payment-info"></a>
## Payment Info
<table>
<tr>
<td>Field</td>
<td>Type</td>
<td>Description</td>
</tr>
<tr>
<td>transaction_id</td>
<td> string </td>
<td>ID of charging transaction</td>
</tr>
<tr>
<td>vehicle_id</td>
<td> string </td>
<td>ID of vehicle</td>
</tr>
<tr>
<td>order_id</td>
<td> string </td>
<td>ID of payment order</td>
</tr>
<tr>
<td>result</td>
<td>int</td>
<td rowspan="4">
<b>0</b> - UNPAID<br>
<b>1</b> - PAID<br>
<b>2</b> - FAILED<br>
<b>3</b> - UNKNOWN ERROR<br>
</td>
</tr>
<tr/><tr/>
</table>
<a name="transaction-info"></a>
## Transaction Info
<table>
<tr>
<td>Field</td>
<td>Type</td>
<td>Description</td>
</tr>
<tr>
<td>transaction_id</td>
<td> string </td>
<td>ID of charge transaction</td>
</tr>
<tr>
<td>station_name</td>
<td> string </td>
<td>charge station name</td>
</tr>
</tr>
<tr>
<td>connector_type</td>
<td> string </td>
<td>support charge point connector type (eg. CCS1)</td>
</tr>
</tr>
<tr>
<td>payment_method</td>
<td> string </td>
<td>payment method (eg. 街口支付、VISA)</td>
</tr>
</tr>
<tr>
<td>start_timestamp</td>
<td> int </td>
<td>charge start timestamp</td>
</tr>
</tr>
<tr>
<td>end_timestamp</td>
<td> int </td>
<td>charge end timestamp</td>
</tr>
</tr>
<tr>
<td>price</td>
<td> int </td>
<td>total price of this transaction</td>
</tr>
<tr/><tr/>
</table>
<a name="vehicle-charging-info-callback-response"></a>
## Vehicle Charging Info Callback Response
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| vehicles | array of | [Vehicle Charging Info](#Vehicle-Charging-Info) list |
An example of a successful response:
```json
{
"vehicles": [
{
"vehicle_id": "000A020B030C",
"transaction_id": "Abdc7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVa",
"battery_status": 60.00,
"charging_accum_price": 0,
"idle_accum_price": 0,
"idle_start_time": 0,
"idle_end_time": 0,
"charging_status": 0
},
{
"vehicle_id": "000B030B040A",
"transaction_id": "Decc7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVa",
"battery_status": 100.00,
"charging_accum_price": 100,
"idle_accum_price": 20,
"idle_start_time": 1683461972,
"idle_end_time": 1683462072,
"charging_status": 1
},
]
}
```
<a name="payment-result-callback-response"></a>
## Payment Result Callback Response
##### Response Format
| Field | Type | Description |
| :--- | :--- | :--- |
| payments | array of | [Payment Info](#payment-info) list |
An example of a successful response:
```json
{
"payments": [
{
"transaction_id": "Fekj7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oUDVb",
"order_id": "ORDERID1",
"vehicle_id": "000A020B030C",
"result": 1
},
{
"transaction_id": "EfGj7FFHaKZ1M2M7NT2tK9ziT3UT7q3pHzY7i27oABCD",
"order_id": "ORDERID2",
"vehicle_id": "000D020B030D",
"result": 1
},
]
}
```
Sign in with Wallet
Connect another wallet