使用流程說明
營業人(特店)可使用此功能先將開立發票參數傳送至綠界系統，由綠界暫存發票資料，待延遲開立時間到，系統會自動開立電子發票上傳財政部，並通知消費者(買家)電子發票已開立。
應用場景
I. 預約開立發票：
特店可使用此功能先將開立發票參數傳送至綠界，由綠界暫存發票資料，待預約開立時間到，系統會自動開立發票。
II. 觸發開立發票：
特店可使用此功能先將開立發票參數傳送至綠界，由綠界暫存發票資料，等待確認要開立時，再由特店進行觸發開立。
注意事項：
如果使用延遲開立發票API，還會需要接收綠界呼叫貴司的請求，請放行postgate.ecpay.com.tw TCP 443(正式環境)、
postgate-stage.ecpay.com.tw TCP 443(測試環境)，如貴司防火牆需固定IP，postgate IP不須另外申請，請自行使用ping指令查詢IP位址。
API介接網址
- 測試環境：https://einvoice-stage.ecpay.com.tw/B2CInvoice/DelayIssue
- 正式環境：https://einvoice.ecpay.com.tw/B2CInvoice/DelayIssue
HTTPS傳輸協定
- Content Type ：application/json
- HTTP Method ：POST
特店傳入參數(Json格式)
PlatformID String(10)
特約合作平台商代號
- 這個參數是專為與綠界簽約的指定平台商所設計，只有在申請開通後才能使用。
- 如果您是一般廠商，請在介接時將此參數欄位保留為空。
- 對於平台商，在使用時需要在MerchantID(特店編號)欄位中填入與您已經完成綁定子廠商的MerchantID(特定編號)。
請注意，只能使用已綁定的子廠商編號，以避免操作失敗。綁定作業請洽所屬業務。
MerchantID String(10)
特店編號 必填
RqHeader Object
傳入資料 必填
Timestamp Number
傳入時間 必填
請將傳輸時間轉換為時間戳(GMT+8)，綠界會利用此參數將當下的時間轉為Unix TimeStamp來驗證此次介接的時間區間。
注意事項：
- 驗證時間區間暫訂為 10 分鐘內有效，若超過此驗證時間則此次訂單將無法建立，參考資料：http://www.epochconverter.com/。
- 合作特店須進行主機「時間校正」，避免主機產生時差，導致API無法正常運作。
Data String
加密資料 必填
此為加密過JSON格式的資料。加密方法說明
特店傳入參數範例(Json格式)
{
"MerchantID": "2000132",
"RqHeader": {
"Timestamp": 1525168923
},
"Data": "加密資料"
}
Data參數說明(Json格式) : 請先將Json字串進行urlencode後再進行AES加密
MerchantID String(10)
特店編號 必填
RelateNumber String(30)
特店自訂編號 必填
需為唯一值不可重複使用
注意事項：
- 請勿使用特殊符號
- 大小寫英文視為相同 (e.g. 123abc456=123ABC456)
ChannelPartner String(1)
通路商編號
1:蝦皮
其餘數值忽略無效
CustomerID String(20)
客戶編號
格式為『英文、數字、下底線』等字元
ProductServiceID String(10)
產品服務別代號
- 該參數必須由英文字母（A-Z, a-z）和數字（0-9）組成，其長度必須在1到10個字符之間。
- 此參數只有在【B2C系統多組字軌】開關為【啟用】時，帶入值才會進行處理，否則會忽略此參數。如需啟用請洽所屬業務。
CustomerIdentifier String(8)
統一編號
- 格式為數字，固定長度為8碼
- 根據財政部的最新公告，針對統一編號的檢核方式做了調整。
您可以點擊以下連結查看：
[財政部財政資訊中心營利事業統一編號檢查碼邏輯修正說明] - 如未符合上述檢核邏輯，則開立發票、設定交易對象維護資料時將會失敗，請營業人務必提供正確的統一編號
CustomerName String(60)
客戶名稱
- 當列印註記[Print]=1(列印)時，此參數為必填
- 格式為中、英文及數字等。
- 當統一編號[CustomerIdentifier]有值時，請帶入相對應的營業人名稱，可參照以下API取得多數的對應公司名稱統一編號驗證API
CustomerAddr String(100)
客戶地址
當列印註記[Print]=1(列印)時，此參數為必填
CustomerPhone String(20)
客戶手機號碼
- 當客戶電子信箱[CustomerEmail]為空字串時，為必填。
- 格式為數字
CustomerEmail String(80)
客戶電子信箱
- 當客戶手機號碼[CustomerPhone]為空字串時，為必填。
- 需為有效的Email格式，且僅可填寫一組Email。
注意事項：
- 測試環境請勿帶入之真實電子信箱，避免個資外洩。
- 測試環境僅作API串接測試使用，僅以API回覆成功或失敗；不提供發信測試，僅驗規則。
- 格式檢核正規表達式為：^((([A-Za-z]|\d|[!#\$%&’\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+(\.([A-Za-z]|\d|[!#\$%&’\*\+\-\/=\?\^_`{\|}~]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])+)*)|((\x22)((((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(([\x01-\x08\x0b\x0c\x0e-\x1f\x7f]|\x21|[\x23-\x5b]|[\x5d-\x7e]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(\\([\x01-\x09\x0b\x0c\x0d-\x7f]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF]))))*(((\x20|\x09)*(\x0d\x0a))?(\x20|\x09)+)?(\x22)))@((([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([A-Za-z]|\d|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.)+(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])|(([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])([A-Za-z]|\d|-|\.|_|~|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])*([A-Za-z]|[\u00A0-\uD7FF\uF900-\uFDCF\uFDF0-\uFFEF])))\.?$
ClearanceMark String(1)
通關方式
- 當課稅類別[TaxType]=2(零稅率)時，為必填
1：非經海關出口
2：經海關出口
Print String(1)
列印註記 必填
0：不列印
1：要列印
注意事項：
- 請注意此參數的意義為註記這張發票之後會被廠商自行印出紙本，綠界上傳財政部時也會提供這個參數讓財政部知道這張發票是被列印成紙本的，並不是指由綠界代為列印與寄送
- 當捐贈註記[Donation]=1(要捐贈)，此參數請帶0
- 當統一編號[CustomerIdentifier]有值時
2.a 載具類別[CarrierType]為空值時，此參數請帶1
2.b 載具類別[CarrierType]=1或2時，此參數請帶0
2.c 載具類別[CarrierType]=3時，此參數可帶0或1
注意事項：
超商KIOSK事務機列印注意事項(除須向業務申請開通外，請按以下需求帶入參數)
1. 要列印消費發票(ibon)
Print=1，CarrierType=””，CustomerIdentifier=””，Donation=0，只能列印一次(之後中獎也無法再次列印)
2. 要列印中獎發票(iborn, FamiPort)
Print=0，CarrierType=1，CustomerIdentifier=””，Donation=0，只能列印一次
3. 折讓後發票金額為0元，不可列印
Donation String(1)
捐贈註記 必填
0：不捐贈
1：要捐贈
注意事項：
- 當統一編號[CustomerIdentifier]有值時，此參數請帶0
- 當載具類別[CarrierType]不為空字串且捐贈註記[Donation]=1時，代表此張發票開立當下是存在載具內，之後消費者將此張發票進行捐贈成功，所以此張發票最終狀態是捐贈成功
LoveCode String(7)
捐贈碼
- 當捐贈註記[Donation]=1(要捐贈)時，為必填。
- 格式為阿拉伯數字為限，最少三碼，最多七碼，首位可以為零。
注意事項：
使用捐贈碼時，請先呼叫捐贈碼驗證進行檢核，避免輸入錯誤。
推薦捐贈碼 168001
OMG關懷社會愛心基金會
成立於2009年，希望能集結網友族群的心意，將愛傳遞到社會的每一個角落。
本基金會致力於：清寒學生及偏遠學校助學、流浪動物與動物保育議題、老人及弱勢團體、急難救助、人道救援、社會公益活動推廣及廣告贊助…等。
CarrierType String(1)
載具類別
空字串：無載具
1：綠界電子發票載具
2：自然人憑證號碼
3：手機條碼載具
注意事項：
- 如果列印參數[Print]=1(表示要列印)，且需要同時存放載具，則只能帶3 : 手機條碼載具。如果不需要載具，請帶入空字串。
- 當列印註記[Print] =0(不列印)，且統一編號[CustomerIdentifier]有值時，此參數不可帶空字串。
- 只有存在綠界電子發票載具(此參數帶1)的發票，中獎後才能在ibon列印領取必填
CarrierNum String(64)
載具編號
- 當[CarrierType]=””
請帶空字串。 - 當[CarrierType]=1時
請帶空字串，系統會自動帶入值，為客戶電子信箱或客戶手機號碼擇一(以客戶電子信箱優先)，由於資安考量，綠界會重新編碼後產出綠界載具編號。 - [CarrierType]=2
請帶固定長度為16且格式為2碼大寫英文字母加上14碼數字 - [CarrierType]=3：請帶固定長度為8碼字元，第1碼為【/】; 其餘7碼則由數字【0-9】、大寫英文【A-Z】與特殊符號【+】【-】【.】這39個字元組成的編號。
注意事項：
- 英文、數字、符號僅接受半形字元，格式錯誤會造成開立失敗
- 若為手機條碼載具時，請先呼叫手機條碼驗證進行檢核，一旦手機條碼有誤，會造成發票歸戶失敗。
TaxType String(1)
課稅類別 必填
- 當字軌類別[InvType]為07時，則此欄位請填入1、2、3或9
- 當字軌類別[InvType]為08時，則此欄位請填入3或4
1：應稅。
2：零稅率。
3：免稅。
4：應稅（特種稅率）
9：混合應稅與免稅或零稅率時，必需通過申請核可。
SpecialTaxType Int
特種稅額類別
- 當課稅類別[TaxType]為1/2/9時，系統將會自動帶入數字【0】
- 當課稅類別[TaxType]為3時，則該參數必填，請填入數字【8】
- 當課稅類別[TaxType]為4時，則該參數必填，可填入數字【1-8】，
- 並分別代表以下類別與稅率
1：代表酒家及有陪侍服務之茶室、咖啡廳、酒吧之營業稅稅率，稅率為25%
2：代表夜總會、有娛樂節目之餐飲店之營業稅稅率，稅率為15%
3：代表銀行業、保險業、信託投資業、證券業、期貨業、票券業及典當業之專屬本業收入(不含銀行業、保險業經營銀行、保險本業收入)之營業稅稅率，稅率為2%
4：代表保險業之再保費收入之營業稅稅率，稅率為1%
5：代表銀行業、保險業、信託投資業、證券業、期貨業、票券業及典當業之非專屬本業收入之營業稅稅率，稅率為5%
6：代表銀行業、保險業經營銀行、保險本業收入之營業稅稅率(適用於民國103年07月以後銷售額) ，稅率為5%
7：代表銀行業、保險業經營銀行、保險本業收入之營業稅稅率(適用於民國103年06月以前銷售額) ，稅率為5%
8：代表空白為免稅或非銷項特種稅額之資料
SalesAmount Number
發票總金額(含稅) 必填
- 請帶整數，支援至12位，不可有小數點。
- 僅限新台幣。
InvoiceRemark String(200)
發票備註
Items Array[Object]
商品
可多筆，商品最多支援200項
ItemSeq Int
商品序號
ItemName String(100)
商品名稱 必填
ItemCount Number
商品數量 必填
支援整數8位，小數2位
ItemWord String(6)
商品單位 必填
ItemPrice Number
商品單價 必填
- 支援整數10位，小數7位
- 若vat=0(未稅)，商品金額需為未稅金額
- 若vat=1(含稅)，商品金額需為含稅金額
ItemTaxType String(1)
商品課稅別
- 當課稅類別[TaxType] = 9時，此欄位不可為空。
1：應稅
2：零稅率
3：免稅
注意事項：
當課稅類別[TaxType] = 9時，商品課稅類別只能
- 應稅+免稅
- 應稅+零稅率
- 免稅和零稅率發票不能同時開立。
ItemAmount Number
商品合計 必填
- 支援整數12位，小數7位
- 此為含稅小計金額
- 所有商品的ItemAmount加總後四捨五入=SalesAmount(含稅)
注意事項：
ItemAmount需統一為含稅金額，且商品金額需符合以下規則：
- 當vat = 1, 且TaxType = 1:
ItemPrice(含稅)*ItemCount = ItemAmount(含稅)
ex: 500*5 = 2500 - 當vat = 0,且TaxType = 1(稅率5%):
ItemPrice(不含稅)*ItemCount*1.05 = ItemAmount(含稅)
ex: 500*5*1.05 = 2625
InvType String(2)
字軌類別 必填
- 該張發票的發票字軌類型。
07：一般稅額
08 : 特種稅額
DelayFlag String(1)
延遲註記 必填
- 可註記此張發票要延遲開立或觸發開立發票
1：延遲開立
2：觸發開立
DelayDay Int
延遲天數 必填
- 若為延遲開立時，延遲天數須介於1至15天內
- 觸發開立時也可設定延遲天數，但須介於0至15天內
注意事項：
- 開立當天10點後無法取消開立
EX1:
DelayFlag=1(延遲)
DelayDay=7(天數)
此為7天後自動開立
EX2:
DelayFlag = 2(觸發)
DelayDay=2(天數)
此為被觸發後過2天才會開立，若此張發票都沒有被觸發，將不會被開立
Tsr String(30)
交易單號 必填
- 用來呼叫付款完成觸發或延遲開立發票API的依據。
- 均為唯一值不可重覆使用。
PayType String(1)
交易類別 必填
請固定帶 ‘2’
PayAct String(6)
交易類別名稱 必填
請固定帶 ‘ECPAY’
NotifyURL String(200)
開立完成時通知特店系統的網址
注意事項：
- 提醒您！使用測試環境時，不提供NotifyURL開立通知
- 請在收到開立成功結果通知後，請正確回應 1|OK 給綠界。
vat String(1)
商品單價是否含稅
- 1：含稅(預設)
- 0：未稅
Data參數範例(Json格式)
{
"MerchantID":2000132,
"RelateNumber": "20181028000000021",
"CustomerID": "",
"CustomerIdentifier": "53538851",
"CustomerName": "綠界科技股份有限公司",
"CustomerAddr": "106台北市南港區發票街1號1樓",
"CustomerPhone": "",
"CustomerEmail": "test@ecpay.com.tw",
"ClearanceMark": "1",
"Print": "1",
"Donation": "0",
"LoveCode": "",
"CarrierType": "",
"CarrierNum": "",
"TaxType": "1",
"SalesAmount": 100,
"InvoiceRemark": "發票備註",
"InvType": "07",
"DelayFlag": "1",
"DelayDay": 5,
"Tsr": "1231000000",
"PayType": "2",
"PayAct": "ECPAY",
"NotifyURL": "test@ecpay.com.tw",
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "件",
"ItemPrice": 50,
"ItemTaxType": "2",
"ItemAmount": 50,
"ItemRemark": "item01_desc"
},
{
"ItemSeq": 2,
"ItemName": "item02",
"ItemCount": 1,
"ItemWord": "個",
"ItemPrice": 20,
"ItemTaxType": "1",
"ItemAmount": 20,
"ItemRemark": "item02_desc"
},
{
"ItemSeq": 3,
"ItemName": "item03",
"ItemCount": 3,
"ItemWord": "粒",
"ItemPrice": 10,
"ItemTaxType": "2",
"ItemAmount": 30,
"ItemRemark": "item03_desc"
}
]
}
綠界回傳參數格式
- Content Type ：application/json
- HTTP Method ：POST
綠界回傳參數(Json格式)
PlatformID String(10)
特約合作平台商代號
MerchantID String(10)
特店編號
RpHeader Object
回傳資料
Timestamp Number
回傳時間
Unix timestamp(GMT+8)
TransCode Int
回傳代碼
1 代表 API 傳輸資料(MerchantID, RqHeader, Data)接收成功，實際的 API 執行結果狀態請參考 RtnCode。
TransMsg String(200)
回傳訊息
Data String
加密資料
回傳相關資料，此為加密過JSON格式的資料。加密方法說明
綠界回傳參數範例
{
"MerchantID": "2000132",
"RpHeader": {
"Timestamp": 1525169058
},
"TransCode": 1,
"TransMsg": "",
"Data": "加密資料"
}
Data參數說明(Json格式) : 請先將Data進行AES解密後再做urldecode
RtnCode Int
回應代碼
1 代表 API 執行成功，其餘代碼均為失敗。
RtnMsg String(200)
回應訊息
OrderNumber String(30)
交易單號
- 若開立成功，則會回傳交易單號(Tsr)
- 若開立失敗，則會回傳空值。
Data參數範例
{
"RtnCode": 1,
"RtnMsg": "開立發票成功",
"OrderNumber": "1231000000"
}
NotifyURL 通知綠界Response回傳參數說明
NotifyURL接收端Http Header 設定
- Accept：text/html
- Content-Type：application/x-www-form-urlencoded
回傳參數說明
inv_mer_id String(10)
特店編號
od_sob String(30)
商家自訂訂單編號
tsr String(30)
交易單號
- 若開立成功，才會回傳。
- 若開立失敗，則會回傳空值。
invoicedate String(10)
發票日期
若開立成功，才會回傳。
invoicetime String(8)
發票時間
若開立成功，才會回傳。
invoicenumber String(10)
發票號碼
若開立成功，才會回傳。
invoicecode String(8)
發票檢查碼
若開立成功，才會回傳。
inv_error Int
錯誤代碼
範例
inv_mer_id=2000132&od_sob=20181028000000021&tsr=1231000000&invoicedate=2019-09-17&invoicetime=15:30:00&invoicenumber=UV11100012&invoicecode=12345678&inv_error=