智慧金流加值應用服務規範建議書™º慧寬頻應用城市計畫_智慧... ·...

智慧金流加值應用服務規範建議書

V 1.0

ii

計畫管理系統產出

中華民國 105 年 01 月 25 日

i

目錄

頁次

第 1 部分緣起 ......................................................... 1

第 2 部分行動支付服務之相關參考規範 .............. 2

壹、前言 ........................................ 2

貳、行動支付服務規範參考條例 .................... 3

一、交通票證 ....................................................................................... 3

二、信用卡 ........................................................................................... 4

三、金融卡暨行動儲值支付帳戶 ....................................................... 7

四、電子支付/第三方支付 ................................................................ 10

參、注意事項 ................................... 10

第 3 部分感測/定位技術之管理訊息規範 ........... 12

壹、前言 ....................................... 12

一、規範目的 ..................................................................................... 12

二、Beacon 服務簡介 ....................................................................... 13

貳、BEACON 管理資訊欄位格式說明 ................ 16

一、管理資訊欄位設定之通則 ......................................................... 16

二、整體管理資訊欄位說明 ............................................................. 18

三、各管理資訊欄位格式之細部說明 ............................................. 19

肆、BEACON 管理資訊資料庫程式存取介面(API) ..... 26

一、程式存取介面(API) 參考說明 ................................................. 27

二、程式存取介面(API) 使用說明 ................................................. 29

伍、小結 ....................................... 37

1

第 1 部分緣起

為加速國內 4G 寬頻網路布建及應用普及化，經濟部工業局執行

「4G智慧寬頻應用城市輔導推動計畫- 4G智慧寬頻應用城市輔導推動

計畫」，透過補助計畫協助業者運用 4G 的大頻寬特性與資通訊技術，

發展 4G 行動寬頻應用服務，並串接國內產業鏈，由地方支持發展特色

化可商轉應用服務。

有鑑於各業者擬推動之各類行動寬頻創新應用服務，可能做法新

穎，業者所研提的各種商業模式適法性需評估考量，且在業者建置服務

中，透過共通標準介面有助於強化服務普及與推動，遂規劃制定相關介

面規範促進 4G 行動寬頻應用服務之發展。

在智慧金流類別做法上為符合本計畫服務商轉化(POB)之需求，提

出「智慧金流加值應用服務規範建議書」，包括「行動支付服務之相關

參考規範」及「感測/定位技術之管理訊息規範」兩部分，其中將協助

業者蒐集與整理相關金融法規條例，作為發展行動支付相關服務商轉

之適法性參考，並透過建立 Beacon 管理資訊欄位規範及 Beacon 管理

資訊資料庫共通 API，掌握各補助計畫在感測/定位應用服務建置之時

程管控，以及藉由標準化的欄位與 API 促成 Beacon 設備及定位訊息的

再應用。

2

第 2 部分行動支付服務之相關參考規範

壹、前言

行動支付(Mobile Payment)係指以智慧手持裝置(如：智慧型手機、

平板電腦…等)作為支付工具的一種付款機制。行動支付從架構差異上

一般分為兩大類，包含近端支付(Proximity payment)與遠端支付(Remote

payment)。

所謂的近端支付為藉由近距離無線技術完成交易的方式，如：

NFC(Near Field Communication)、藍牙(Bluetooth)…等，在使用上以透

過點對點(P2P，Peer To Peer)傳輸的方式進行線下(Offline)交易，訴求快

速、即時的小額度付款(Micro Payment)，例如非接觸式信用卡、電子票

證…等；遠端支付則是利用行動裝置通訊功能搭配後台作業系統提供

線上(Online)付費的動作，訴求安全的大額度付款(Macro Payment)，使

用的技術像是網頁、QRCode…等，在使用上以讓使用者可以透過 SIM

卡、個人帳號密碼或是信用卡卡號搭配到期日及後三碼的認證方式，連

結遠端伺服器進行轉帳付款交易，常見的方式如：線上信用卡、網路金

融卡轉帳、電信帳單及第三方支付…等。

行動支付之相關應用服務所牽涉的多為具敏感性的資料，相關國

際組織在應用服務介面規範上是以資料在交易傳輸過程中的安全保護

3

為主，多數金流所產生與金融業務相關的交易資料並不適合進行資料

交換或分享，規範考量所涵蓋的層面從硬體設備、應用軟體、後端平台

及網路傳輸等，針對使用者新興的交易載具(智慧 IC 卡、手持裝置等)

亦訂定了對應的安全規範。

行動支付服務規範依業者建置服務類型有所不同的法源依據，以

下提供常見之條款簡介供參考，包括國內現行交通票證、信用卡、金融

卡法規、第三方支付法以及金管會與產業共識應遵循之規範，另相關法

規之細則內容或新增、修改及增補條文，請參考金融監督管理委員會網

站 http://www.fsc.gov.tw/ch/ 或全國法規資料庫網站

http://law.moj.gov.tw/。

貳、行動支付服務規範參考條例

一、交通票證

(一)「電子票證發行管理條例」

為因應電子科技之發展，便利民眾利用電子票證自動扣款之

方式，作為多用途支付使用，確保發行機構之適正經營，並保

護消費者之權益及維持電子票證之信用，特制定本條例。

(二)「電子票證發行機構業務管理規則」

http://www.fsc.gov.tw/ch/

http://law.moj.gov.tw/

http://law.moj.gov.tw/LawClass/LawContent.aspx?PCODE=G0380207

http://law.banking.gov.tw/Chi/FLAW/FLAWDAT01.asp?lsid=FL049791

4

發行機構之業務管理、作業方式、特約機構管理、營業據點、

內部控制與稽核、作業委外、投資限制、財務業務與營運事項

之核准與申報及其他應遵行事項之規則。

(三)「電子票證應用安全強度準則」

依本條例發行之電子票證，其應用安全強度等級、安全需求設

計、防護措施及相關事項之準則。

二、信用卡

(一)「信用卡業務機構管理辦法」

本辦法規範信用卡業務機構之各業務事項：

1. 信用卡公司

2. 外國信用卡公司

3. 經主管機關許可兼營信用卡業務之銀行、信用合作社或其

他機構。

4. 其他經主管機關許可專營信用卡業務之機構。

信用卡業務指下列業務之一：

1. 發行信用卡及辦理相關事宜。

2. 簽訂特約商店及辦理相關事宜。


5

3. 代理收付特約商店信用卡消費帳款。

4. 授權使用信用卡之商標或服務標章。

5. 提供信用卡交易授權或清算服務。

6. 辦理其他經主管機關核准之信用卡業務。

(二)「信用卡業務機構辦理手機信用卡業務安全控管作業基準」

本安控基準主要規範信用卡業務機構﹙發卡機構﹚自主發行或

與行動通信業者共用安全儲存媒介(SE)，針對安全儲存媒介

進行晶片個人化作業(Personalization)之安全控管。倘以接觸

式方式進行晶片個人化作業或信用卡業務機構(發卡機構)獨

立使用信用卡應用程式儲存媒介者，則依據信用卡組織作業

規範辦理即可。

安全儲存媒介發行方式信用卡晶片個人化作業方式安全控管基準

信用卡業務機構﹙發卡機

構﹚自主發行

依傳統信用卡方式，將資料交

付個人化處理中心作業

信用卡組織作

業規範

透過空中傳輸(OTA，Over the

Air)方式進行信用卡晶片個人

化作業

信用卡組織作

業規範及本安

控基準

與行動通信業者共用安

全儲存媒介

透過空中傳輸(OTA)方式進行

信用卡晶片個人化作業

信用卡組織作

業規範及本安

控基準

(三)「金融機構作業委託他人處理內部作業制度及程序辦法」

6

旨在金融機構作業委託他人辦理之作業品質及客戶權益保障

更臻完善，減低對金融機構營運可能造成之風險，俾規範金融

機構作業委託他人辦理之委託事項範圍、客戶權益保障、風險

管理及內部控制原則之內部作業及程序等事宜。

(四)「金融消費者保護法」

為保護金融消費者權益，公平、合理、有效處理金融消費爭議

事件，以增進金融消費者對市場之信心，並促進金融市場之健

全發展，特制定本法。

(五)「個人資料保護法」

為規範個人資料之蒐集、處理及利用，以避免人格權受侵害，

並促進個人資料之合理利用，特制定本法。

(六)「信用卡定型化契約範本」

規範信用卡定型化契約之內容，包含：申請、個人資料之蒐集

處理及利用、信用額度、契約雙方之基本義務、年費、一般交

易及退貨等處理程序、特殊交易、預借現金...等項目。

(七)「信用卡定型化契約應記載及不得記載事項」

規範信用卡定型化契約之應記載得記載事項，應記載事項如：

7

發卡機構之義務、持卡人之義務、信用額度之調整及通知、循

環信用利息之計算、各項費用及權益之調整與資訊揭露、匯率

之計算、退貨等之處理程序…等。不得記載事項如：持卡人拋

棄契約審閱期間之條款、少於七日之持卡人對契約變更得表

示異議期間、將當期消費帳款計入當期本金計算循環信用利

息…等。

(八)「金融監督管理委員會指定非公務機關個人資料檔案安全維

護辦法」

本辦法依個人資料保護法第二十七條第三項規定訂定之。本

辦法所稱非公務機關，包括下列各款：金融控股公司、銀行業、

證券業、期貨業、保險業、電子票證業、其他經金融監督管理

委員會公告之金融服務業、金融監督管理委員會主管之財團

法人。

三、金融卡暨行動儲值支付帳戶

(一)「辦理電子銀行業務安全控管作業基準」

中華民國銀行商業同業公會全國聯合會為確保金融機構辦理

電子銀行業務具有一致性基本準則之安全控管作業，特訂定

本基準。

8

(二)「銀行受理客戶以網路方式開立儲值支付帳戶作業範本」

為配合電子商務及網路交易代收代付服務之發展，規範銀行

受理客戶以網路方式開立儲值支付帳戶之作業審核程序及其

配套管理措施，特依據「存款帳戶及其疑似不法或顯屬異常交

易管理辦法」訂定作業範本。

(三)「金融機構作業委託他人處理內部作業制度及程序辦法」

旨在金融機構作業委託他人辦理之作業品質及客戶權益保障

更臻完善，減低對金融機構營運可能造成之風險，俾規範金融

機構作業委託他人辦理之委託事項範圍、客戶權益保障、風險

管理及內部控制原則之內部作業及程序等事宜。

(四)「金融消費者保護法」

為保護金融消費者權益，公平、合理、有效處理金融消費爭議

事件，以增進金融消費者對市場之信心，並促進金融市場之健

全發展，特制定本法。

(五)「金融機構提供行動裝置應用程式注意事項」

包含敏感性資料處理、認證與授權、邏輯漏洞、權限管理、例

外處理、登入驗證、程式安全等檢測項目。

9

(六)「個人資料保護法」

為規範個人資料之蒐集、處理及利用，以避免人格權受侵害，

並促進個人資料之合理利用，特制定本法。

(七)「活期(儲蓄)存款契約附屬金融卡定型化約款範本」

為維護消費者權益並利業者有所遵循，包含領取啟用及作廢、

密碼變更、存款金額之限制、存款行提款及轉帳金額之限制、

跨行提款及轉帳金額之限制、存摺補登、交易時點之認定、國

內提領外幣…等規範範本。

(八)「金融監督管理委員會指定非公務機關個人資料檔案安全維

護辦法」

本辦法依個人資料保護法第二十七條第三項規定訂定之。本

辦法所稱非公務機關，包括下列各款：金融控股公司、銀行業、

證券業、期貨業、保險業、電子票證業、其他經金融監督管理

委員會公告之金融服務業、金融監督管理委員會主管之財團

法人。

(九)「銀行間資金移轉帳務清算之金融資訊服務事業許可及管理

辦法」

10

本辦法稱銀行間資金移轉帳務清算之金融資訊服務事業，係

指提供金融機構間即時性跨行金融業務帳務清算加值網路之

跨行金融資訊網路事業。

四、電子支付/第三方支付

(一)「銀行法」(代理收付部分)

為健全銀行業務經營，保障存款人權益，適應產業發展，並使

銀行信用配合國家金融政策，特制定本法。

(二)「銀行受理客戶以網路方式開立儲值支付帳戶作業範本」

為配合電子商務及網路交易代收代付服務之發展，規範銀行

受理客戶以網路方式開立儲值支付帳戶之作業審核程序及其

配套管理措施。

(三)「電子支付機構管理條例」

為促進電子支付機構健全經營及發展，以提供安全便利之資

金移轉服務，特制定本條例。

參、注意事項

我國行動支付規範多以遵循國際組織所制定的標準為依據，再由


11

相關業管機關如金融監督管理委員會(金管會)、中華民國銀行公會，以

及財金資訊股份有限公司進行在地化的規定，主要仍是以金融在業務

營運規範及交易資料安全規範兩大層面，業者在投入建置服務後，不論

是試營運或商轉營運上需遵循並經過主管機關(金管會)之認可。

另金管會之管轄範圍為國內之金融服務業者，資訊服務業者或系

統整合商投入之相關行動支付服務，在服務上線核可認定上需由配合

之銀行協助向金管會申請。遂業者在投入行動支付服務領域時，建議參

考上述國內法規規範，並要求配合金融單位提出金管會核可試營運或

商轉營運之相關佐證文件。

12

第 3 部分感測/定位技術之管理訊息規範

壹、前言

一、規範目的

物聯網概念發燒，感測定位技術包含如聲波、QRCode、藍牙、

WiFi 等配合特殊之演算法，創造了多元的創新應用，包含訊息推播、

導引導覽等，舉例來說，應用於商務上可辨識消費者於商圈內的約略

區域位置，提供鄰近商家的加價消費商品項推薦與路程指引。

觀察國內業者相對積極投入發展項目，其中以藍牙技術為核心之

Beacon 微定位訊息推播應用為最多數，預估總計數萬以上的 Beacon

將在未來數年中遍布台灣各地，但 Beacon 服務建置模式就像孤島一

般一區一業者各自發展，甚至熱門商店擁有多個服務營運業者Beacon

設備，且管理方式各異或無人管理，如何建立有效之設備管理與跨業

者分享機制，創造整體營運綜效成為未來持續發展之關鍵。

遂透過分析國內外發展案例建立符合國際標準之 Beacon 管理資

訊(廣播之訊息、設備基本資料如建置地點等)欄位規範以及 Beacon 管

理資訊資料庫共通 API，提供給業者參考與運用，一方面協助業者管

理，確保 Beacon 服務的持續營運，另一方面促成未來在業者同意下，

13

新進業者、新創業者或政府相關創意開發活動(如通訊大賽)可透過標

準化的欄位取得感測/定位技術管理訊息進行Beacon設備及定位訊息

的再應用，創造 Beacon 設備共用之價值。

二、Beacon 服務簡介

傳統 GPS 精確度約在 3~25 米之間。然而室內 GPS 無用武之地，

因此業者利用基地台或 WiFi 信號，區域定位與導航，精度約在 30 米

左右。目前國際大廠紛紛投入在感測/定位領域之技術研發，其中以

2013 年蘋果提出 iBeacon 為先鋒，利用低功耗藍牙(BLE)廣播定位信

號，可於室內提供定位服務，精度在近距離可到 30cm，一時蔚為風

潮，而後在 2015 年 Google 也提出類似方案的 Eddystone，進一步讓

此等微定位應用快速進入市場。

(一) iBeacon 簡介

iBeacon，又被稱為 Proximity Beacon，是蘋果電腦公司基於

低功耗藍牙(BLE)於 2013 年提出的規範。每個封包總長度

為 30 個位元組(Byte)，其開頭符合藍牙規範。之後採取不

可連線的廣播封包。詳細定義如下：

iBeacon 的數據由四組代碼構成，分別是 UUID、Major、Minor、

14

Measured Power。UUID 是 ISO/IEC11578:1996 標準的

128bit 識別代碼，用以判斷何種APP被啟動。Major及Minor

都是 16 bit 的代碼，由 APP 自行設定，用以表示如『全家

便利商店』『A 櫃位』等等。

在物理上，iBeacon 仍然遵守低功耗藍牙的規範，由於 WiFi

與 BLE 同樣在 2.4GHz 頻率運作，而 iBeacon 有可能大

數量在空間中布建，因此其使用頻道為低功耗藍牙的 37, 38,

39 頻段。下圖藍色部分是 BLE 的頻道，紅色部分是 iBeacon

所使用的頻道。半圓形部分則是 WiFi 所使用的頻段。由下

圖可發覺， iBeacon 所使用的廣告頻段，剛好與 WiFi 錯開，

藉以避免干擾問題。

(二) Eddystone 簡介

相對於 iBeacon 得如火如荼，Android 的擁有者 Google 自然

15

不甘示弱，推出更完整的 Eddystone。其實 Google 早在 2010

年就推出 Near me now，2014 年推出 Nearby，都或多或少有

用到無線技術，但 Eddystone 可說是對 iBeacon 的正面回應。

本協定有幾個重要格式，介紹如下：

1. Eddystone-UID

Eddystone-UID 就像 iBeacon 一樣，包含 16 位元組的

UUID，以及各 2 bytes 的 Major, Minor，共 20bytes，這

種使用方式與 iBeacon 大同小異。

2. Eddystone-URL

Eddystone-URL 直接在廣播信息中夾帶網址，手機可直

接轉譯網址。相較於 iBeacon 許多時候必須先訪問雲端

伺服器才能取得網址，Eddystone-URL 可擁有較好的使

用者體驗。

3. Eddystone-TLM

相較於 iBeacon 對於藍牙的各種參數完全放任，

Eddystone-TLM 制定了藍牙管理者也許需要知道的資

訊，包含：

(1) 電池電壓

16

(2) Beacon 溫度

(3) 傳送的封包數：最後一次開機之後

(4) Beacon 開機時間：最後一次開機之後

值得一提的是，Eddystone 在藍牙封包上，除了自身之外，

還支援 iBeacon 以及一種被稱為 Altbeacon 的格式，試

圖籠絡市場上眾多既有 iBeacon 使用者，或者最少在

Android 上使用 Eddystone 既有的 API 或 SDK。

貳、Beacon 管理資訊欄位格式說明

以下針對管理資訊欄位及服務布建各階段需回傳之資料格式進

行說明：

一、管理資訊欄位設定之通則

為使 Beacon 能夠管理與互通，將依據 Java 組織所制定之 JSON

格式信息設定原則：

(一)資料切分為『筆』與『欄位』

(二)每個 Beacon 對應一筆資料

17

(三)Beacon 的每個特性對應到一個欄位

(四)每筆資料以字元「{」作為開頭，「}」作為結束

(三)每欄位以「(」作為前置符號、「)」作為結束符號

(六)每欄資料如下規範：(欄位名稱,欄位數值)

(七)擴充性欄位定義為：(欄位名稱,欄位長度,欄位數值)或(欄位

名稱,欄位長度 1,欄位長度 2,欄位數值 1,欄位數值 2)

(八)手動輸入狀況時，為求簡便，欄位名稱及分隔字元由系統

自動補足

依照以上原則，將資料列表如下，並於後文詳細說明：

18

二、整體管理資訊欄位說明

類

別計畫管理

設備

採購布建申報服務上線維運申報

欄

位

公司名

稱

( CMN,

Compan

y Name)

統一編號

(TID,tax

ID)

MAC

Address

(MAC)

UUID Major

(MAJ)

Minor

(MIN)

Txpowe

r(TX)

GPS

(GPS)

地址

(Physical

Address,

PADD)

樓層

(FL)

布建日期

(DATE)

照片網址

(PURL,Photo

URL)

APP

或網址

(URL)

服務上線日期

(SDATE,Servic

e Date)

電量

(PL,Power

Level,0-99)

維護日期

(MDATE,Mai

ntain Date)

範

例

1

(CMN,6,

經濟部)

(TID,

12345678

)

(MAC,11223

3445566)

(UUID,1122

33445566778

899AABBC

CDDEEFF00

)

(MAJ,

65535)

(MIN,5

1350)

(TX,96) (GPS,11,

10,125.0

1234567,

121.0123

456)

(PADD,23

,台北市中

正東路三

段 133

號)

(FL,123) (DATE,201

51213)

(URL,11,goo.gl/Q

uXj)

(URL,

13,ww

w.yaho

o.com)

(SDATE,20151

213)

(PL,99) (MDATE,201

51213)

範

例

2

(CMN,8,

大同公

司)

(TID,

55336699

)

(MAC,68372

2933355)

(UUID,4262

7384 9393

9238 1783

0938 0983)

(MAJ,

32444)

(MIN,3

2445)

(TX,80) (GPS,9,9,

125.2345

67,121.1

23456)

(PADD,16

,高雄建國

南路 13

號)

(FL,23) (DATE,200

40405)

(URL,11,goo.gl/2

k1K)

(URL,

13,ww

w.yaho

o.com)

(SDATE,20030

908)

(PL,53) (MDATE,200

20813)

19

三、各管理資訊欄位格式之細部說明

以下針對各管理資訊欄位依據管理面角度，分成計畫管理、設備

採購、布建申報、服務上線及維運申報進行細部說明：

(一)計畫管理

1. 計畫提案主導業者公司名稱

代號：CMN, Company Name

長度：由資料決定

格式：(代號,資料長度,資料值)

範例：(CMN,6,經濟部)

備註：一個中文字長度為 2Byte，英文為 1Byte

2. 計畫提案主導業者統編

代號：TID ( Tax ID )

長度：8Byte

格式：(代號,資料值)

20

範例：(TID, 53111234)

(二)設備採購之資料格式說明

1. MAC Address

代號：MAC(Mac Address)

長度：17 Byte


說明：藍芽設備的唯一編號，每個藍牙模組出場前皆會

燒錄一組唯一代碼，廠商需紀錄此碼，作為辨識的基

準。

範例：(MAC, 112233445566)

(三)布建申報之資料格式說明

廠商布建 Beacon 時，下列參數是作為施工標準的參數，說

明如下：

1. UUID

代號：UUID

21

長度：36 Bytes


說明：iOS 根據 UUID，判定由哪個 APP 處理或忽略。

範例：(UUID,112233445566778899AABBCCDDEE)

2. Major

代號：MAJ(Major)

長度：5 Bytes


說明：供 APP 做各類識別及應用。

範例：(MAJ,65535)

3. Minor

代號：MIN(Minor)

長度：5 Bytes


說明：供 APP 做各類識別及應用。

22

範例：(MIN,51350)

4. Measured Power

代號：TX(Txpower)

長度：4 Bytes


說明：iPhone 5s 在一公尺處可收到的信號強度

範例：(TX,96)

5. GPS

代號：GPS(GPS)

長度：最多 23 Bytes

格式：(代號,長度 1,長度 2,資料值 1,資料值 2)

說明：佈建 Beacon 場域的 GPS 座標，如為移動性佈建

點(如公車)或非常駐性之佈建點，請提供保管處(如公車

站、Beacon 保管倉庫)GPS 座標。

範例：(GPS,5,6,120.4,133.75)

23

6. 地點

代號：PADD(Physical Address)

長度：視實際地址字數而定，1 個中文字元 2bytes，1 個

英文字元 1Bytes

格式：(代號,長度,資料值)

說明：同一 GPS 地點往往可佈建數十 Beacon，本欄位供

補充說明，若佈建點無地址(如捷運站、路燈等)，請提

供最近之建築物地址。

範例：(PADD,13,台北市中正東路三段 133 號)

7. 樓層

代號：FL(Floor)

長度：3Bytes


範例：(FL, 123 )

8. 布建日期

24

代號：PDA, Place Date

長度：8Bytes


說明：Beacon 佈建日期。

範例：(DATE,20151213)

9. 照片網址(選填欄位)

代號：PURL (Photo URL)

長度：視實際網址長度而定，1 個英文字元 1Bytes

格式：(代號,資料長度,資料值)

範例：(URL,11,goo.gl/QuXj)

(四)服務上線之資料格式說明

1. APP(URL)

代號：URL

長度：視實際網址長度而定

25

格式： (代號,長度,資料值)

說明：提供服務的 APP 或其他 URL(如有多個 APP 使用

該 Beacon，請提供一個做為代表)。

範例：(URL,13,www.yahoo.com)

2. 服務上線日期

代號：SDATE,Service Date

長度：8Bytes


說明：APP 或服務上線日期。

範例：(SDATE,20151213)

(五)維運申報之資料格式說明

1. 電量

代號：PL(Power Level)

長度：3 Byte

26


說明：電量。

範例：(PL,99)

2. 維運日期(選填欄位)

代號：MDATE(Maintain Date)

長度： 33 bytes


說明：APP 或服務異動日期。。

範例：(MDATE,20151213)

肆、Beacon 管理資訊資料庫程式存取介面(API)

為促成未來在業者同意下，新創業者、新創業者或政府相關創意

開發活動(如通訊大賽)可透過標準化的欄位取得感測/定位技術管理

訊息進行 Beacon 設備及定位訊息的再應用，本規範亦制定共通 API

以利於擷取 Beacon 資料庫欄位資料。

27

一、程式存取介面(API) 參考說明

(一) REST API

REST API 是一種簡潔的設計風格。使用者使用 JSON 格式

的數據透過 HTTP 協議以 URL 的方式與系統作交流和數據

存儲。如以下範例我們可以 HTTP GET 方式向位於

54.65.111.245的伺服器請求關於 ID 186 beacon的相關訊息。

而資源的位置將取決於 URL 本身。如此範例將會訪問位於

/api/v1/beacons 文件底下的資源。

http://54.65.111.245/api/v1/beacons/186

(二) HTTP 協議

HTTP 在 REST API 主要有四種較常見的請求方式分別為

POST(新增)，GET(獲取)，PUT(更新)，DELETE(移除)。本

文檔將在 API 說明的章節透過 cURL 工具來展示數據傳送

的方式及回傳的數據以及其內容的說明。在 HTTP 協議中

有一些較常見的伺服器狀態碼。當使用者向伺服器傳送請

求後，不管成功與否，伺服器會回傳一個狀態碼來告知使

用者此請求是否成功。以下我們將列出較常見的狀態碼以

及其定義。

http://54.65.111.245/api/v1/beacons/186

29

狀態碼定義

200 請求成功

400 發生錯誤

401 權限不足

404 內容不存在

429 伺服器繁忙

500 伺服器內部錯

誤

二、程式存取介面(API) 使用說明

(一) 使用者權限請求操作

由佈建感測定位元件(Beacon)的營運商，提供可存取該

Beacon 管理系統之必要權限程式呼叫方式，說明如下：

系統會根據使用者的身份，給予該使用者對某裝置的操

作權限。因此，在操作裝置前，使用者必須擁有並登入一個

個人帳戶。使用者可以透過此 API 進行帳戶注冊或對個人的

帳戶進行操作和修改。登入後，系統會回傳給 App 得一個

Access Token。這個 Access Token 將會被用來驗證並獲取使

用者的身分及其相關資料。這個 Access Token 將給予使用者

在一定的時間內對系統進行相關操作的權限。

/users：POST

提供增添加一個新的使用者帳戶。註冊時調用呼叫的 API。

30

向伺服器透過 POST 方法發出新增使用者請求:

curl -X POST

-H "Content-Type: application/json"

-d '{

"user_name" : "test",

"password" : "123456",

"mobile" : "0933123456",

"email" : "[email protected]"

}' http://54.65.111.245/api/v1/users

伺服器回傳結果:

{

"status_code" : "200",

"message":"請求成功",

"result" : "true"

}

/users/{user_id}：PUT

當使用者需要修改帳戶訊息時，可以透過此 API 對系統進

行個人資料的修改。

向伺服器透過 PUT 方法發出更新使用者資料請求:

curl -X PUT


-d '{

"mobile" : "0933123456",


}' http://54.65.111.245/api/v1/users/e8xuS170dkjeo

當使用者沒登入時出現的回傳訊息:

{


"message":"權限不足",

"result" : "true"

}

31

/users/{user_id}：GET

用來讀取使用者帳戶的相關訊息。

* access_token 登入後將由系統自動生成並回傳。

向伺服器透過 GET 方法發出讀取使用者帳戶資料請求:

curl -X GET


-d '{

"access_token" : "e9joEdho…"

}' http://54.65.111.245/api/v1/users/e8xuS170dkjeo

回傳訊息:

{



"result" : {

"user_name" : "test",

"mobile" : "0933123456",


}

}

相關參數

參數列表

名稱變量名必填類型範例值備註帳號 user_name Y string(32) [email protected] — 密碼 password N int(8) 12345678 — 信箱 email Y string(16) FGI890HOEKXSFC88 郵件地址手機號

mobile Y string(16) 0923568080 —

登入令牌

access_token N String(26) 9Elkj2w0FGi890HOEKXSwe088u

加密後的會話 ID 由系統自動生成

32

返回參數

返回值

名稱變量名必填類型範例值

狀態碼 status_code int(8) 404 如無錯誤時，

代號為 2XX 錯誤訊息 message string(128) 訪問內容不存在 —

相關數據 result json object {"user_name":"test",

"phone":"123456"} 返回的數據

(二) 感測/定位裝置資訊存取操作說明

* 使用者必須登入後才能操作此功能。


用此 API 相對的參數以 JSON 格式傳送到系統，使用者便可

以將該裝置和相應使用者帳號做關聯，並進行裝置資訊的建

立，修改或讀取該裝置的相關訊息。

/beacons：POST

添加一個新的裝置。使用者可以透過此 API 對系統進行數

據建立。

33

向伺服器透過 POST 方法發出添加一個新的裝置請求:

curl -X POST


-d '{

"company" : "微風廣場",

"uuid" : "12345678910245",

"location" : "123.1324, 138.6645",

"access_token" : "e9joEdho…",

……

}' http://54.65.111.245/api/v1/beacons


{



"result" : "true"

}

/beacons/{MAC}：PUT

當使用者需要修改裝置訊息時，可以透過此 API 對系統進

行數據更新。

34

向伺服器透過 PUT 方法發出修改裝置訊息請求:

curl -X PUT


-d '{

"company" : "木柵動物園",

"battery_level" : "77",

"major" : "13",

"minor" : "1",

"access_token" : "e9joEdho…",

……

}' http://54.65.111.245/api/v1/beacons/12345678910245


{



"result" : "true"

}

/beacons/{MAC}：GET

用來讀取裝置的相關訊息。


35

向伺服器透過 GET 方法發出讀取裝置的請求:

curl -X GET


-d '{

"access_token" : "e9joEdho…"

}' http://54.65.111.245/api/v1/beacons/12345678910245


{


"message" : "請求成功",

"result" : {

"company" : "微風廣場",

"mac_address" : "FGI890HOEKXSFC88",

"power" : "99",

"battery_level" : "50",

"major" : "4",

"minor" : "2",

……

}

}

相關參數

36

參數列表

名稱變量名必填類型範例值備註

公司

名 company Y string(32) 微風廣場 —

統一

編號 tax_id N int(8) 53111234 —

MAC

地址 mac_address Y string(16)

FGI890HOEKXS

FC88

連接裝置時所需

地址

裝置

ID uuid Y string(16) 12345678910245 裝置唯一的 ID

主區

分號 major Y int(2) 5

用還來區分同場

合裝置主要位置

eg. 5 樓

副區

分號 minor Y int(2) 3

用還來區分同場

合裝置其他位置

訊息

eg. 3 號櫃台

信號

強度 power N int(8) 86 單位為 dB

GPS

定位 location Y string(24)

135.2244,

128.6645 經緯度

地址 physical_add

ress Y string(128)

台北市中正東路

三段 133 號 —

實境

圖 picture N string(32)

emhok93o39jep.j

pg

加密後的裝置的

位置展示圖

相關

網址 url N string(24)

www.ibeacon.co

m —

電量 battery_level N string(128) 65 單位為百分比(%)

註冊

日期 register_date N

time_

stamp

1447247702

以時間戳格式紀

錄時間

上線

日期 service_date N

time_

stamp

1447247702


錄時間

維修

日期

maintenance_

date N

time_

stamp

1447247702


錄時間

登入

令牌 access_token N String(26)

9Elkj2w0FGi890

HOEKXSwe088u

加密後的會話 ID

由系統自動生成

37

返回參數

返回值

名稱變量名必填類型範例值

狀態碼 status_code int(8) 404 如無錯誤時，

代號為 2XX 錯誤訊息 message string(128) 訪問內容不存在 —

相關數據 result json object

{"uuid":"12345678910245",

"company":"微風廣場"}

返回的數據

伍、小結

本規範定義了 Beacon 管理資訊欄位與格式，並規劃 Beacon 管理

資訊資料庫共通 API，其目的為透過 4G 智慧寬頻應用城市補助計畫

業者建置感測/定位技術服務(Beacon)填報之資料，協助主管機關-經

濟部工業局掌握業者服務佈建情形做為計畫查驗之參考，並透過資料

庫共通 API 利於未來可進行 Beacon 設備及定位訊息的再應用。

智慧金流加值應用服務規範建議書™º慧寬頻應用城市計畫_智慧... ·...

Documents