使用流程說明
綠界收到營業人(特店)傳送參數後會進行開立，綠界加值中心會於48小時內協助上傳財政部。
應用場景
適用於即時開立發票
營業人可提供以下發票資料設定項目供買受人選擇(下圖為參考範例，營業人可自行設計)
使用情境說明
捐贈(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介接網址
- 測試環境：https://einvoice-stage.ecpay.com.tw/B2CInvoice/Issue
- 正式環境：https://einvoice.ecpay.com.tw/B2CInvoice/Issue
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. 要列印中獎發票(ibon, 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時，商品課稅類別只能
1.應稅+免稅
2.應稅+零稅率，
免稅和零稅率發票不能同時開立。
ItemAmount Number
商品合計 必填
- 支援整數12位，小數7位
- 此為含稅小計金額
- 所有商品的ItemAmount加總後四捨五入=SalesAmount(含稅)
注意事項：
- ItemAmount需統一為含稅金額，且商品金額需符合以下規則：
1. 當vat = 1, 且TaxType = 1:
ItemPrice(含稅)*ItemCount = ItemAmount(含稅)
ex: 500*5 = 2500
2. 當vat = 0,且TaxType = 1(稅率5%):
ItemPrice(不含稅)*ItemCount*1.05 = ItemAmount(含稅)
ex: 500*5*1.05 = 2625
ItemRemark String(40)
商品備註
InvType String(2)
字軌類別 必填
- 該張發票的字軌類型
07：一般稅額
08 : 特種稅額
vat String(1)
商品單價是否含稅
- 預設為含稅價
1：含稅
0：未稅
Data參數範例(Json格式)
{
"MerchantID": "2000132",
"RelateNumber": "20181028000000001",
"CustomerID": "",
"CustomerIdentifier": "",
"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",
"vat": "1",
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "件",
"ItemPrice": 50,
"ItemTaxType": "1",
"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": "1",
"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)
回應訊息
InvoiceNo String(10)
發票號碼
- 若開立成功，則會回傳一組發票號碼
- 若開立失敗，則會回傳空值
InvoiceDate String(20)
發票開立時間
格式為「yyyy-MM-dd HH:mm:ss」或「 yyyy/MM/dd HH:mm:ss」
RandomNumber String(4)
隨機碼
Data參數範例
{
"RtnCode": 1,
"RtnMsg": "開立發票成功",
"InvoiceNo": "UV11100012",
"InvoiceDate": "2019-09-17 17:17:31",
"RandomNumber": "6866"
}
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay General Invoice Issuance API
version: 1.0.0
servers:
- url: https://einvoice.ecpay.com.tw
description: Production Environment
- url: https://einvoice-stage.ecpay.com.tw
description: Testing Environment
paths:
/B2CInvoice/Issue:
post:
summary: General Invoice Issuance
description: Issue an invoice immediately.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- MerchantID
- RqHeader
- Data
properties:
PlatformID:
type: string
description: Platform identifier (optional)
MerchantID:
type: string
description: Merchant identifier
RqHeader:
type: object
properties:
Timestamp:
type: number
description: Timestamp of the request
Data:
type: string
description: Encrypted data in JSON format
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
PlatformID:
type: string
description: Platform identifier
MerchantID:
type: string
description: Merchant identifier
RpHeader:
type: object
properties:
Timestamp:
type: number
description: Timestamp of the response
TransCode:
type: integer
description: Transmission code
TransMsg:
type: string
description: Transmission message
Data:
type: string
description: Encrypted data in JSON format
'400':
description: Invalid request
'500':
description: Server error
components:
schemas:
requestBody.Data:
type: object
properties:
MerchantID:
type: string
description: Merchant identifier
RelateNumber:
type: string
description: Unique merchant-defined number
CustomerID:
type: string
description: Customer identifier
CustomerIdentifier:
type: string
description: Unified business number
CustomerName:
type: string
description: Customer name
CustomerAddr:
type: string
description: Customer address
CustomerPhone:
type: string
description: Customer phone number
CustomerEmail:
type: string
description: Customer email
ClearanceMark:
type: string
description: Clearance mark
Print:
type: string
description: Print mark (0 = no print, 1 = print)
Donation:
type: string
description: Donation mark (0 = no donation, 1 = donation)
LoveCode:
type: string
description: Donation code
CarrierType:
type: string
description: Carrier type
CarrierNum:
type: string
description: Carrier number
TaxType:
type: string
description: Tax type
SalesAmount:
type: number
description: Total sales amount
InvoiceRemark:
type: string
description: Invoice remark
Items:
type: array
items:
type: object
properties:
ItemSeq:
type: integer
description: Item sequence number
ItemName:
type: string
description: Item name
ItemCount:
type: number
description: Item quantity
ItemWord:
type: string
description: Item unit
ItemPrice:
type: number
description: Item price
ItemTaxType:
type: string
description: Item tax type
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code
RtnMsg:
type: string
description: Response message
InvoiceNo:
type: string
description: Invoice number
InvoiceDate:
type: string
format: date
description: Invoice date (yyyy-MM-dd HH:mm:ss)
RandomNumber:
type: string
description: Random number for the invoice