路邊停車狀態通知 API介接規則 - v1.6 2023.11.30

--- title: '路邊停車狀態通知 API介接規則 - v1. 2023.11.30' --- # 路邊停車狀態通知 API介接規則 v1.5 (2023.11.30) ## 版本說明 | 日期 | 版本 | 說明 | 修改者 | -------- | -------- |-------- | -------- | | 2023/10/17 | v1.0 | 初版 | | | 2023/10/17 | v1.1 | 新增繳費統計、新增開單統計 | | | 2023/10/24 | v1.2 | 入位通知和離位通知的"SpaceNumber"型態改成string | | | 2023/10/25 | v1.3 | 修改API | 天茶 | | 2023/11/07 | v1.4 | 新增開單、結單API 修改全部API| | | 2023/11/14 | v1.5 | 修改繳費通知API欄位 | 2023/11/30 | v1.6 | 新增多臺繳費機狀態通知API 新增多臺攝影機繳費通知API | 2024/02/29 | v1.7 | 開單通知API新增ImageFile欄位 | 2024/03/13 | v1.8 | 新增開單修改API ## API呼叫流程 *1.停車平台後端程式(MqttSender)監聽API傳送過來的資料* *2.解析後轉發到平台的Mqtt，可以串接警報的點位* ## API端點 http://220.135.33.221:3031 *API端點的Port由MqttSender程式指定 * ## API授權 *目前測試無驗證* ## 入位通知API ### 請求 :::warning ### POST **/api/YLPKInfo/CarIn** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "Road": "265-E", "SpaceNumber": "265-E001", "CarNumber": "AGH6730", "CarIn_UTC": "20231018092830" } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | Road|字串 | 路段 (不會是中文名稱，而是代碼)| | ✔ | SpaceNumber|字串 | 車位 | | | CarNumber|字串 | 車號 | | ✔ | CarIn_UTC|字串 | 入位時間(UTC)，yyyyMMddHHmmss | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 離位通知API ### 請求 :::warning ### POST **/api/YLPKInfo/CarOut** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "Road": "260-T", "SpaceNumber": "260-T001", "CarOut_UTC": "20231018092830" } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | Road|字串 | 路段 (不會是中文名稱，而是代碼)| | ✔ | SpaceNumber|字串 | 車位 | | ✔ | CarOut_UTC|字串 | 離位時間(UTC)，yyyyMMddHHmmss | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 開單通知API ### 請求 :::warning ### POST **/api/YLPKInfo/PaperOpen** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "Road": "260-T", "SpaceNumber": "260-T001", "CarNumber": "HMB-5555", "Open_UTC": "20231018092830", "PaperNumber": "ADVSDED12359", "Rate": 30, "ImageBase64": "Base64" } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | Road|字串 | 路段 (不會是中文名稱，而是代碼)| | ✔ | SpaceNumber|字串 | 車位 | | ✔ | CarNumber|字串 | 車號 | | ✔ | Open_UTC|字串 | 開單時間(UTC)，yyyyMMddHHmmss | | ✔ | PaperNumber|字串 | 開單單號 | | ✔ | Rate|數字 | 費率(小時為單位)(可否加這欄) (可以) | | ✔ | ImageBase64|字串 | 停車圖片(Base64) | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 開單修改API :::info 開單修改會在開單通知後的任意時間通知，有可能是隔天 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/PaperModify** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "PaperNumber": "ADVSDED12359", "CarNumber": "HMB-5555" } ``` ::: ### Json內容 | 必要 | 欄位 | 型別 | 說明 | | - | - | - | - | | ✔ | PaperNumber|字串 | 開單單號 | | ✔ | CarNumber |字串 | 車號 | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 結單通知API ### 請求 :::warning ### POST **/api/YLPKInfo/PaperClose** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "Road": "D", "SpaceNumber": "260-T001", "CarNumber": "AGH6730", "Close_UTC": "20231018092830", "PaperNumber": "string", "Cost": 150 } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | Road|字串 | 路段 (不會是中文名稱，而是代碼)| | ✔ | SpaceNumber|字串 | 車位 | | ✔ | CarNumber|字串 | 車號 | | ✔ | Close_UTC|字串 | 結單時間(UTC)，yyyyMMddHHmmss | | ✔ | PaperNumber|字串 | 開單單號 | | ✔ | Cost|數字 | 停車總費用(可否加這欄) (可以) | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 繳費通知API :::danger 這裡幫我寫一下，我先定義我想要的需求 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/Payfees** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "Road": "D", "SpaceNumber": "260-T001", "CarNumber": "AGH6730", "PaperNumber": "string", "Pay": 150, "Pay_UTC": "20231018092830", "PaymentType":"PaymentMachine", "PaymentMachineCode":"260T031024" } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | Road|字串 | 路段 (不會是中文名稱，而是代碼)| | ✔ | SpaceNumber|字串 | 車位 | | ✔ | CarNumber|字串 | 車號 | | ✔ | PaperNumber|字串 | 開單單號 | | ✔ | Pay|數字 | 繳費金額 | | ✔ | Pay_UTC|字串 | 繳費時間(UTC)，yyyyMMddHHmmss | | ✔ | PaymentType|字串 | 繳費管道⏬ "PaymentMachine"：現場繳費機 "LINE_Pay"：LINE Pay "NCCC"：聯合信用卡 "NCCC_GooglePay"：聯合信用卡 Google Pay "NCCC_ApplePay"：聯合信用卡 Apple Pay "JKOPAY"：街口支付 "EasyWallet"：悠遊付 "PlusPay"：全盈支付| | | PaymentMachineCode|字串 | 繳費機代號 (繳費管道是現場繳費機才有)(可否加這欄) | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 繳費機狀態通知API :::danger #### ~~繳費機如何判斷離線?~~ #### ~~多久發一次狀態?~~ ::: :::info 每五分鐘輪詢一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/Aps** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "ApsId": "260T031024", "Battery": 85.4, "IsDisconnected": true, "CardReaderStatus": 1, "CardReaderEventType": 2, "CardReaderErrorCode":0, "ScannerStatus":1, "ScannerEventType":0, "ScannerErrorCode":0 } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | ApsId|字串 | 繳費機編號 | | ✔ | Battery|數值 | 電池電量(%) | | ✔ | IsDisconnected|布林 | 是否斷線 | | ✔ | CardReaderStatus|數值 | 刷卡機狀態⏬ 0：未知、1：已就緒、2：錯誤、3：警告、4：無法使用 | | ✔ | CardReaderEventType|數值 | 刷卡機事件⏬ 0：觸發、1：已處理、2：紀錄 | | ✔ | CardReaderErrorCode|數值 | 刷卡機錯誤代碼⏬ 0：無錯誤、1：設備啟動、2：COM未啟用、3：COM無信號 | | ✔ | ScannerStatus|數值 | 掃描器狀態⏬ 0：未知、1：已就緒、2：錯誤、3：警告、4：無法使用 | | ✔ | ScannerEventType|數值 | 掃描器事件⏬ 0：觸發、1：已處理、2：紀錄 | | ✔ | ScannerErrorCode|數值 | 掃描器錯誤代碼⏬ 0：無錯誤、1：設備啟動、2：COM未啟用、3：COM無信號 | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 多臺繳費機狀態通知API :::info 每五分鐘輪詢一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/ApsList** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= [ { "ApsId": "260T031024", "Battery": 85.4, "IsDisconnected": true, "CardReaderStatus": 1, "CardReaderEventType": 2, "CardReaderErrorCode":0, "ScannerStatus":1, "ScannerEventType":0, "ScannerErrorCode":0 } ] ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | ApsId|字串 | 繳費機編號 | | ✔ | Battery|數值 | 電池電量(%) | | ✔ | IsDisconnected|布林 | 是否斷線 | | ✔ | CardReaderStatus|數值 | 刷卡機狀態⏬ 0：未知、1：已就緒、2：錯誤、3：警告、4：無法使用 | | ✔ | CardReaderEventType|數值 | 刷卡機事件⏬ 0：觸發、1：已處理、2：紀錄 | | ✔ | CardReaderErrorCode|數值 | 刷卡機錯誤代碼⏬ 0：無錯誤、1：設備啟動、2：COM未啟用、3：COM無信號 | | ✔ | ScannerStatus|數值 | 掃描器狀態⏬ 0：未知、1：已就緒、2：錯誤、3：警告、4：無法使用 | | ✔ | ScannerEventType|數值 | 掃描器事件⏬ 0：觸發、1：已處理、2：紀錄 | | ✔ | ScannerErrorCode|數值 | 掃描器錯誤代碼⏬ 0：無錯誤、1：設備啟動、2：COM未啟用、3：COM無信號 | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 攝影機狀態通知API :::info 每五分鐘輪詢一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/Camera** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "CameraId": "260T002CRO20116", "Battery": 85.23, "IsDisconnected": true, } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | CameraId|字串 | 攝影機編號 是否等同立柱編號？ (對) | | ✔ | Battery|字串 | 電池電量(%) | | ✔ | IsDisconnected|布林 | 是否斷線 | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 多臺攝影機狀態通知API :::info 每五分鐘輪詢一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/CameraList** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= [ { "CameraId": "260T002CRO20116", "Battery": 85.23, "IsDisconnected": true, } ] ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | CameraId|字串 | 攝影機編號 是否等同立柱編號？ (對) | | ✔ | Battery|字串 | 電池電量(%) | | ✔ | IsDisconnected|布林 | 是否斷線 | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 繳費統計API :::danger ~~此API是統計所有路段的收費金額嗎？因為API沒有明確寫路段或是某台繳費機如果是，那是何時發送過來，還是我們要自動去取得？ (是所有；每晚11點半發送。)~~ #### ~~可能每小時或幾小時發一次嗎?一小時~~ ::: :::info 改成每小時一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/Payment** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "PaidAmount": 100, "TotalAmount": 6543, "SummaryDateTime": "20231025110000", } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | PaidAmount|數值 | 繳費張數 | | ✔ | TotalAmount|數值 | 繳費金額 | | ✔ | SummaryDateTime|字串 | 統計時間(TW)，yyyyMMddHHmmss | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` ::: ## 開單統計API :::danger ~~此API是統計所有路段的收費金額嗎？因為API沒有明確寫路段如果是，那是何時發送過來，還是我們要自動去取得？ (是所有；每晚11點半發送。)~~ ::: :::danger ~~開單統計跟繳費機統計可否合併同一個API?否~~ ::: :::info 改成每小時一次 ::: ### 請求 :::warning ### POST **/api/YLPKInfo/Paper** #### 檔頭 `Content-Type` : `application/json` #### 內容 ```json= { "PaperAmount": 100, "TotalAmount": 6543, "SummaryDateTime": "20231025110000", } ``` ::: ### Json內容 | 必要 | 欄位 |型別| 說明| | -------- | --|------ | -------- | | ✔ | PaidAmount|數值 | 開單張數 | | ✔ | TotalAmount|數值 | 停車費總共金額 | | ✔ | SummaryDateTime|字串 | 統計時間(TW)，yyyyMMddHHmmss | :::success #### 回應結果：成功 (200) ```json= { "result": "ok", } ``` ::: :::danger #### 回應結果：失敗 (400) ```json= { "error": "錯誤訊息", } ``` :::