---
# System prepended metadata

title: Get Started

---

<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.ink/img/pako:eNqd0EFLAkEUAOC_MszJyP7AHoSyS5eQjE57ec0-dWl31saZQERQSRJWyEtRakaXijAvUURWv8bZ1VN_oVnKfkBzecPj8d73Xo2ywEFq0QoeKuQMN10oCvBtTszLgZAcBdkAdoDcIXkURyjWMpnVXQFVsp7b-k1ZJkpVJntYcpmHJFsCUUSyHUi34DKQbsBJan7_qCf9-OxlcR7qu1C324vBdN45iZ970dV1dNli4Hn7ZhSJ-8dECW_ln4ocVH3kkuxgRXmSZJdtk8qUPn1YDBvz26Zu9mevjWh88_XenX0M49bbbHoRjT_1pBt1enow0q2nOGxE7TABjoYJ6k9odORnH4Okaeqj8MF1zCFrCdqmsoQ-2tQyXwcLYBw2tXndlIKSQb7KGbWkUJimquyAXN6dWgXwKlj_Bur2sAw?type=png)](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.ink/img/pako:eNo1jjEKwkAQRa-yTGu8wBaCIohgEYjlNMPuRBezE53MCiHk7m4Kf_WKz-MtEMbI4GHiT2EJfE70UMoorq4lNWF1JwovluiO7XV_OOzuSvPGrmP9snp3YXOdkaVR3C1NhoICDWTWTClW-7L5EOzJmRF8xcg9lcEQUNZ6pWJjN0sAb1q4gfKOZP8Y8D0NE68_rUI6rQ?type=png)](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.ink/img/pako:eNqVkt9LG0EQx_-VYZ8iXP-BexD8AUUQCVr7dFDWu4lZcrene3tCEOFaCaJpmjxYKkT8gT6q0YiQGslfk73c_RfdeN5LkxbcfZhhduazs7PfXWL7DhKTBLgdIrdxkdFNQT2LWxz0KlIhOQqYp3YFuQNzxSX4MDv7SdDqq7-GYgeFCR9RwmcsM9tFKAq_xLQtbFTB3vrCHANsKbSdyZh_FY950-4xYdToqsEv2Mm4r6BAUhkGUOC-8KgL8WFDDaJhr5483f-bPhWed7tQpmITYcWXrMRsKpnPYYG67oZOhkJyfRD_7KlaLW33R0-t-Ox02Ls1QDU7WXPxeQvWA81-S6lHca1uQNI_UrctHUgPmullZ3T9bMCofacOG8nRQ9Ltq_3f8cXLzPtnXKRVD7mEZcYr-XyWuETXpTDsn8Q3gzS60o3-l5xXmJBGzfTrj6mENOoml9_j444OZrQ8a0yYaC4rzUak2mfq2-P7viN_2CoGoSsnfmAS_za8sVCzTQzioVYFc7Scd8enFpFl9NAipnYdLFFNtojF93QqDaW_VuU2MaUI0SDhlkNlrn5ilqgb4N4f62hNQw?type=png)](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
    },
  ]
}
```