電子發票 API (三) 查詢發票表頭與明細

這篇要來做我們準備加進專案裡面的功能，在這之前我們需要先了解發票上 QRCode 裡包含的資訊，可先下載財政部提供的文件：電子發票證明聯一維及二維條碼規格說明。

上圖是從文件中「一維條碼規格」的章節中擷取的發票範本，發票上的 Barcode (一維條碼) 暫時用不到，我們只需要左邊的 QRCode，解碼後會得到以下內容(有加粗體的項目建議先記錄起來，待會查詢發票表頭和明細時會用到)：

發票號碼 (10碼)
發票開立日期 (7碼，3碼民國年、2碼月份、2碼日期)
隨機碼 (4碼)
銷售額 (8碼，未稅總金額，十六進制，不足八碼左補0)
總計額 (8碼，含稅總金額，十六進制，不足八碼左補0)
買方統一編號 (8碼)
賣方統一編號 (8碼)
加密驗證資訊 (24碼)

以上這些欄位總計 77 碼，基本上我們只會需要用到這些，後面還有一些欄位有興趣可以再看看文件，每個欄位都會使用冒號區隔開來，只要記得左方 QRCode 解碼後第一個冒號前的前 77 碼就是我們要的資訊，接下來找張手邊的發票來進行解碼：

左邊 QRCode 解碼之後會出現下面這串，我們先把記下來 (●是碼起來的意思)
EZ9371●●●●109090863●●00000320000003480000000054911841●●●●●●●●●●●●●●●●●●●●●●==:**:1:1:1:超市商品:1:840

接著回去看昨天 API 規格文件，查詢發票表頭的部分

● 查詢發票表頭

功能說明
利用電子發票證明聯上的二維條碼(QR Code)或者一維條碼(BarCode)，查詢該電子發票證明聯表頭資訊，其回應資訊含：發票號碼、發票開立日期、賣方名稱及發票狀態等資訊。

需求參數

參數名稱	是否必填	參數格式	說明	範例
version	是	字串	版本號碼 (帶入範例值即可)	0.5
type	是	特定字串 (QRCode / Barcode)	發票查詢時使用的條碼別 (大小寫有別)	QRCode
invNum	是	字串	發票號碼	EZ9371●●●●
action	是	字串	API 行為 (帶入範例值即可)	qryInvHeader
generation	是	字串	(帶入範例值即可)	V2
invDate	是	日期字串 (yyyy/MM/dd)	發票日期	2020/09/08
UUID	是	字串	行動工具 Unique ID (於文末補充說明)
appID	是	字串	透過財政資訊中心申請之軟體 ID

這邊 type 用 QRCode 來做測試

一樣開啟 Postman，HTTP Method 設定為 POST，Request URL 填上

https://api.einvoice.nat.gov.tw/PB2CAPIVAN/invapp/InvApp?version=0.5&type=QRCode&invNum=填入發票號碼&action=qryInvHeader&generation=V2&invDate=填入發票開立日期&UUID=填入Unique_ID&appID=填入APP_ID

Postman 設定如下圖

送出後沒問題的話就會收到回傳的 JSON

{
    "msg": "執行成功",
    "code": "200",
    "invNum": "EZ9371●●●●",
    "invoiceTime": "19:22:18",
    "invStatus": "已確認",
    "sellerName": "遠東百貨股份有限公司信義分公司",
    "invPeriod": "10910",
    "sellerAddress": "台北市信義區松仁路58號",
    "sellerBan": "54911841",
    "buyerBan": "",
    "v": "0.5",
    "currency": "",
    "invDate": "20200908"
}

得到結果後，把下面幾個項目記錄下來，順便加上剛剛解析 QRCode 時的資料，等等會用在查詢發票明細上

invNum (發票號碼)
invPeriod (發票期別)
sellerBan (商家統編)
invDate (發票開立日期，年月日要改用 / 分隔，即 YYYY/MM/DD 的格式)
前面解析 QRCode 的隨機碼 (4碼)
前面解析 QRCode 的加密驗證資訊 (24碼)

● 查詢發票明細

功能說明
利用電子發票證明聯上的二維條碼(QR Code)或者一維條碼(BarCode)，查詢該電子發票證明聯消費明細資料，至多查詢 99 次。

需求參數

參數名稱	是否必填	參數格式	說明	範例
version	是	字串	版本號碼 (帶入範例值即可)	0.5
type	是	特定字串 (QRCode/ Barcode)	發票查詢時使用的條碼別	QRCode
invNum	是	字串	發票號碼(英文大寫)	EZ9371●●●●
action	是	字串	API 行為 (帶入範例值即可)	qryInvDetail
generation	是	字串	(帶入範例值即可)	V2
invTerm	Type 為 Barcode 時為必填	日期字串 (yyyMM)	發票期別 (發票民國年月，年分為民國年，月份必須為雙數月)	10910
invDate	是	日期字串 (yyyy/MM/dd)	發票開立日期	2020/09/08
encrypt	Type為 QRCode 時為必填	字串	發票檢驗碼，前面解析 QRCode 的加密驗證資訊 (24碼)
sellerID	Type為 QRCode 時為必填	字串	商家統編
UUID	是	字串	行動工具 Unique ID (於文末補充說明)
randomNumber	是	字串	前面解析 QRCode 的隨機碼 (4碼)	63●●
appID	是	字串	透過財政資訊中心申請之軟體 ID

開啟 Postman，HTTP Method 設定為 POST，Request URL 填上

https://api.einvoice.nat.gov.tw/PB2CAPIVAN/invapp/InvApp?version=0.5&type=QRCode&invNum=填入發票號碼&action=qryInvDetail&generation=V2&invDate=填入發票開立日期&encrypt=填入發票檢驗碼&sellerID=填入商家統編&UUID=填入Unique_ID&randomNumber=填入發票隨機碼&appID=填入APP_ID

Postman 設定如下圖

送出成功後回傳的 JSON 如下

{
    "msg": "執行成功",
    "code": "200",
    "invNum": "EZ9371●●●●",
    "invoiceTime": "19:22:18",
    "invStatus": "已確認",
    "sellerName": "遠東百貨股份有限公司信義分公司",
    "invPeriod": "10910",
    "sellerAddress": "台北市信義區松仁路58號",
    "sellerBan": "54911841",
    "buyerBan": "",
    "currency": "",
    "details": [
        {
            "unitPrice": "840",
            "amount": "840",
            "quantity": "1",
            "rowNum": "1",
            "description": "超市商品"
        }
    ],
    "invDate": "20200908"
}

這樣一來就能取得該發票購買的所有品項了，在寫這篇的時候手邊只有這張發票品項有點少，不過之前試過麥X登的，裡面確實有我點的各品項，查明細的部分就到這邊，下一篇再來講查詢載具發票表頭與明細的部分，有錯誤歡迎指證，感謝

● 補充說明

UUID 參數使用說明
“行動工具 Unique ID 係由開發者自行管控之編號，平台僅以記錄方式存放，若因行動工具使用者做出侵害本中心業務之完整性時，本中心將依狀況停止該 UUID 之使用者存取或停止 AppID 存取之處理。(請注意開發者開發之產品若使用者做出違法或損害本平台行為時，責任歸屬於開發者，UUID 僅是輔助開發者之方式，於特定平台可能會有無法取得 UUID 或是 UUID 隨機給付的情形，開發者應視風險承擔程度決定是否提供服務)。”

發佈留言 取消回覆

發佈留言取消回覆