使用流程說明
營業人(特店)可使用此功能先將開立發票參數傳送至綠界系統,由綠界暫存發票資料,待延遲開立時間到,系統會自動開立電子發票上傳財政部,並通知消費者(買家)電子發票已開立。
應用場景
I. 預約開立發票:
特店可使用此功能先將開立發票參數傳送至綠界,由綠界暫存發票資料,待預約開立時間到,系統會自動開立發票。
II. 觸發開立發票:
特店可使用此功能先將開立發票參數傳送至綠界,由綠界暫存發票資料,等待確認要開立時,再由特店進行觸發開立。
使用情境說明
捐贈(Donation)、 統一編號(CustomerIdentifier)、載具(CarrierType)、列印(Print)
使用情境一:捐贈發票 - 當用戶選擇捐贈發票[Donation]=1 - 列印參數[Print]=0:因為捐贈發票不需要列印。 - 統一編號[CustomerIdentifier]:必須為空,捐贈時不能指定統一編號。 - 載具類別[CarrierType]:當載具類別[CarrierType]不為空字串且捐贈註記[Donation]=1時,
代表此張發票開立當下是存在載具內,之後消費者將此張發票進行捐贈成功,所以此張發票最終狀態是捐贈成功。 使用情境二:統一編號發票 - 當用戶提供統一編號[CustomerIdentifier] - 捐贈參數[Donation]只能是 0:指定統一編號時,不能進行捐贈。
- 可以存載具[CarrierType] - 列印參數(Print):依載具類別[CarrierType]而定 - 載具類別為空時:Print只能是 1(要列印)。 - 載具類別為 1 或 2 時:Print只能是 0(不列印)。 - 載具類別為 3 時:Print可以是 0 或 1
使用情境三:選擇存放載具 - 當用戶選擇特定載具[CarrierType] - 若統一編號[CustomerIdentifier]有值且需要列印發票[Print=1]:載具類別[CarrierType]只能選擇3(手機條碼載具)
- 若不需要列印[Print=0]且提供了統一編號[CustomerIdentifier]:載具不可為空。
注意事項:
如果使用延遲開立發票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系統多組字軌】開關為【啟用】時,帶入值才會進行處理,否則會忽略此參數。如需啟用請洽所屬業務。
- 具體步驟參考如下:
1. 聯繫所屬業務<啟用>B2C系統多組字軌功能
2. 至廠商後台<字軌分類管理>節點,新增商品/服務別,例如A0001-餐具、A0002-清潔用品,可參考 電子發票系統操作手冊 <字軌分類管理> 章節說明
3. 至廠商後台<字軌與配號設定>節點,新增字軌配號,可參考 電子發票系統操作手冊 <字軌與配號設定> 章節說明
4. 透過開立發票API,此參數[ProductServiceID]帶入先前廠商後台設定的A0001或A0002,即可完成發票開立
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:混合應稅與免稅或零稅率時,必需通過申請核可。 - 綠界稅額計算方式
一般發票(非混稅、非特種) :
( 發票金額 / 1.05 ) * 0.05 並四捨五入至整數
混稅發票 :
( 應稅品項小計總和 / 1.05 ) * 0.05 並四捨五入至整數
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]
商品
可多筆,商品最多支援999項
ItemSeq Int
商品序號
請帶入1~999的整數數字
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=
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊,方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Delay Issue Invoice API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
- url: https://einvoice.ecpay.com.tw
paths:
/B2CInvoice/DelayIssue:
post:
summary: Delay Issue Invoice
description: This API allows merchants to pre-schedule the issuance of invoices.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- MerchantID
- RqHeader
- Data
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RqHeader:
type: object
required:
- Timestamp
properties:
Timestamp:
type: integer
description: Unix timestamp in GMT+8
Data:
type: string
description: Encrypted data
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
MerchantID:
type: string
description: Merchant ID
RqHeader:
type: object
properties:
Timestamp:
type: integer
description: Unix timestamp in GMT+8
Data:
type: string
description: Encrypted response data
components:
schemas:
requestBody.Data:
type: object
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
RelateNumber:
type: string
maxLength: 30
description: Custom unique identifier
ChannelPartner:
type: string
maxLength: 1
description: Channel partner ID
CustomerID:
type: string
maxLength: 20
description: Customer ID
CustomerIdentifier:
type: string
maxLength: 8
description: Customer tax ID
CustomerName:
type: string
maxLength: 60
description: Customer name
CustomerAddr:
type: string
maxLength: 100
description: Customer address
CustomerPhone:
type: string
maxLength: 20
description: Customer phone number
CustomerEmail:
type: string
maxLength: 80
description: Customer email
ClearanceMark:
type: string
maxLength: 1
description: Customs clearance mark
Print:
type: string
maxLength: 1
description: Print mark
Donation:
type: string
maxLength: 1
description: Donation mark
LoveCode:
type: string
maxLength: 7
description: Donation code
CarrierType:
type: string
maxLength: 1
description: Carrier type
CarrierNum:
type: string
maxLength: 64
description: Carrier number
TaxType:
type: string
maxLength: 1
description: Tax type
SpecialTaxType:
type: integer
description: Special tax type
SalesAmount:
type: integer
description: Total sales amount including tax
InvoiceRemark:
type: string
maxLength: 200
description: Invoice remark
Items:
type: array
properties:
ItemSeq:
type: integer
description: Item sequence
ItemName:
type: string
maxLength: 100
description: Item name
ItemCount:
type: number
description: Item count
ItemWord:
type: string
maxLength: 6
description: Unit
ItemPrice:
type: number
description: Item price
ItemAmount:
type: number
description: Item amount
ItemTaxType:
type: string
maxLength: 1
description: Item tax type
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code
RtnMsg:
type: string
description: Response message
OrderNumber :
type: string
description: order number