如何使用電子發票應用API

財政部在電子發票推行上，為了方便開發更多應用所以提供了API可供個人或者廠商進行相關應用的開發，申請的方式請參考 –> 電子發票API申請最簡單的申請方式就是透過自然人憑證或者工商憑證申請，這樣就不需要檢附任何證明文件。不過這不是本篇的重點，當申請到時會給你一組AppID跟APIKey，然後你可以下載電子發票應用規格1.4版來了解怎樣使用這個API，或許是我才疏學淺，所以在1.3版的時候其實搞不太懂他的API文件，到了1.4版才摸清楚發生了什麼事，當然還是花了點時間才搞懂，現在就簡單說明一下API的使用方式，希望看到本篇文章的同好就不需要花時間測試了。

我簡單用API中的[查詢中獎發票號碼清單]這個功能來說明，首先我們根據文件得知要取得API是用HTTPS協定存取https://www.einvoice.nat.gov.tw/這個網址，而[查詢中獎發票號碼清單]的API Method是/PB2CAPIVAN/invapp/InvApp所以完整的查詢URL就是
https://www.einvoice.nat.gov.tw/PB2CAPIVAN/invapp/InvApp
而在API說明的需求參數告訴你有底下幾個參數需要提供：
1. version
2. action
3. invTerm
4. UUID
5. appID
且說明了相關的參數值，如：
version=0.2
action=QryWinningList
invTerm=10106 (101年05-06月該期)
而且底下就提供了範例：
/PB2CAPIVAN/invapp/InvApp?version=&action=QryWinningList&invTerm=&appID= &UUID=
在看起來近乎完美的說明下，其實有許多沒有說清楚的秘密。
1. 參數還需要加上Signature這個參數，而且此參數是必須採用 Base64編碼之 HMAC-SHA1 演算法，以APIKey作為秘密鑰匙，針對UTF-8字串所有參數，產生簽名結果。
2. UUID其實是用來控管機器用的，防止程式在某些機器上被亂用，因此UUID可以用來控管惡意機器，但是這是非必要條件。
綜合以上的說明，因此我們回頭檢視查詢網址與參數，應該是如下所示：
https://www.einvoice.nat.gov.tw/PB2CAPIVAN/invapp/InvApp?action=QryWinningList&appID=EINV020130529XXXX&invTerm=10106&UUID=&version=0.2&Signature=XXXXXXXXXXXXXXXXXX
簡易說明一下：
1.在URL?後的參數是排序過的
2.appID是申請後財政部電子發票平台發給的格式EINV020130529XXXX
3.Signature=後的XXXXXXXXXXXXXXXXXX是把"action=QryWinningList&appID=EINV020130529XXXX&invTerm=10106&UUID=&version=0.2"的內容以APIKey透過Base64編碼之 HMAC-SHA1 演算法產生出來的。
這樣就可以查詢到你要的資訊，資訊會透過JSON來回傳，如：

{"fifthPrizeAmt":"0001000","firstPrizeAmt":"0200000","firstPrizeNo1":"91180939","firstPrizeNo10":"","firstPrizeNo2":"12753377","firstPrizeNo3":"22638178","firstPrizeNo4":"","firstPrizeNo5":"","firstPrizeNo6":"","firstPrizeNo7":"","firstPrizeNo8":"","firstPrizeNo9":"","fourthPrizeAmt":"0004000","invoYm":"10106","secondPrizeAmt":"0040000","sixthPrizeAmt":"0000200","sixthPrizeNo1":"258","sixthPrizeNo2":"066","sixthPrizeNo3":"","spcPrizeAmt":"2000000","spcPrizeNo":"99028391","spcPrizeNo2":"","spcPrizeNo3":"","superPrizeAmt":"10000000","superPrizeNo":"29734661","thirdPrizeAmt":"0010000","v":"0","code":"200","msg":"查詢成功"}