電子發票 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
invTermType 為 Barcode
時為必填
日期字串
(yyyMM)
發票期別
(發票民國年月,年分
為民國年,月份必須為
雙數月)
10910
invDate日期字串
(yyyy/MM/dd)
發票開立日期2020/09/08
encryptType為 QRCode
時為必填
字串發票檢驗碼,前面解析 QRCode 的加密驗證資訊 (24碼)
sellerIDType為 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 隨機給付的情形,開發者應視風險承擔程度決定是否提供服務)。”

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *