使用流程說明
營業人(特店)可使用此功能將折讓開立參數傳送至綠界,由綠界暫存折讓資料,並發折讓同意通知信給消費者,待消費者點選信件中的同意折讓後,綠界會即時通知營業人折讓單已開立並回傳折讓單號碼,並於隔日將折讓資料上傳至財政部電子發票整合服務平台,並通知消費者(買家)折讓已開立。
應用場景
若商品質量、規格等不符合消費者要求,特店同意在商品價格上給予減讓,可使用此API將開立折讓發票參數傳送至綠界,暫存折讓發票資料。綠界會寄折讓同意通知信給買家,待買家同意折讓後,綠界會依發票折讓開立參數,開立發票折讓單並於隔日,將折讓資料上傳至財政部電子發票整合服務平台。
注意事項:
- 送出後,還需買受人 Email 確認折讓內容,並點擊確認驗證連結(72小時有效),點擊驗證連結當下銷貨折讓才開立;買受人未點擊驗證連結前,您可隨時取消此筆折讓。
- 使用線上同意,您無須再郵寄紙本折讓單給消費者簽名存檔,綠界系統會記錄買受人點擊確認同意連結的相關 log。
- 測試環境(Stage)因資安考量不會寄發任何Mail,請在正式環境(Prod)進行Mail寄送測試
API介接網址
- 測試環境:https://einvoice-stage.ecpay.com.tw/B2CInvoice/AllowanceByCollegiate
- 正式環境:https://einvoice.ecpay.com.tw/B2CInvoice/AllowanceByCollegiate
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)
特店編號 必填
InvoiceNo String(10)
發票號碼 必填
長度固定為10碼
InvoiceDate String(10)
發票開立日期 必填
格式為「yyyy-MM-dd」or「yyyy/MM/dd」
AllowanceNotify String(1)
通知類別 必填
- 開立折讓後,寄送將相關發票折讓資訊通知消費者
- 請固定填 E:電子郵件
CustomerName String(60)
客戶名稱
格式為中、英文及數字等
NotifyMail String(100)
通知電子信箱
- 需為有效的Email格式
- 此參數值須做UrlEncode
- 可帶入多組Email,並以分號區隔
ex: aa@aa.aa;bb@bb.bb - 格式檢核正規表達式為:^((([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])))\.?$
AllowanceAmount Number
折讓單總金額(含稅) 必填
支援整數12位
注意事項:
折讓單總金額應該大於0元
- 如此張發票未折讓過,則應小於或等於原發票總金額
- 如此張發票已折讓過,則應小於或等於折讓剩餘金額
- 折讓單總金額設0元不被允許,是因為此行為代表此張發票不需折讓,不代表此張發票要被折讓到0元
Items Array[Object]
商品
ItemSeq Int
商品序號
ItemName String(100)
商品名稱 必填
不可為空字串
ItemCount Number
商品數量 必填
支援整數8位,小數2位
ItemWord String(6)
商品單位 必填
ItemPrice Number
商品單價 必填
支援整數10位,小數7位
ItemTaxType String(1)
商品課稅別
1:應稅
2:零稅率
3:免稅
注意事項:
- 預設為空字串,當課稅類別[TaxType] = 9時,此欄位不可為空。
- 課稅類別為混合稅率時,需含二筆或以上的商品課稅別[ItemTaxType],且至少需有一筆商品課稅別為應稅及至少需有一筆商品課稅別為免稅或零稅率,即混稅發票只能
1.應稅+免稅
2.應稅+零稅率,
免稅和零稅率發票不能同時開立。
ItemAmount Number
商品合計 必填
- 此為含稅小計金額
- 支援整數12位,小數7位
注意事項:
- 假設A =商品單價[ItemPrice]x商品數量[ItemCount],則A與商品合計[ItemAmount]允許1元以內的誤差
- 各商品之商品合計[ItemAmount]加總需等於折讓單總金額[AllowanceAmount]
- 提醒您,依營業稅電子資料申報繳稅作業要點,電子發票銷貨退回、進貨退出或折讓證明單之「金額(不含稅之進貨額)」及「營業稅額」欄位須為整數,以利申報資料正確,建議此欄位請帶入整數
ReturnURL String(200)
消費者同意後回傳網址
當消費者點選同意後,綠界會將成功的結果參數以幕後(Server POST)回傳到該網址。
注意事項:請在收到 Server 端折讓成功結果通知後,請正確回應 1|OK 給綠界。
Data參數範例
{
"MerchantID": 2000132,
"InvoiceNo": "UV11100015",
"InvoiceDate": "2019/09/17",
"AllowanceNotify": "E",
"CustomerName": "綠界科技股份有限公司",
"NotifyMail": "test@ecpay.com.tw",
"AllowanceAmount": 50,
"Items": [
{
"ItemSeq": 1,
"ItemName": "item01",
"ItemCount": 1,
"ItemWord": "件",
"ItemPrice": 50,
"ItemTaxType": "2",
"ItemAmount": 50
}
],
"ReturnURL": "https://allowance.yoursite/Revice"
}
綠界回傳參數格式
- 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 執行成功,其餘代碼均為失敗。
注意事項:
成功代表API呼叫成功,需消費者同意後才算開立折讓單成功
RtnMsg String(200)
回應訊息
IA_Allow_No String(16)
折讓單號
- 建立成功,會回傳折讓單號;
- 建立失敗,則會回傳空值。
IA_Invoice_No String(10)
發票號碼
- 建立成功,會回傳當初開立的發票號碼;
- 建立失敗,則會回傳空值。
IA_TempDate String(20)
線上折讓時間
- 建立成功,會回傳線上折讓時間
回傳格式為「yyyy-MM-dd HH:mm:ss」; - 建立失敗,則會回傳空值
IA_TempExpireDate String(20)
線上折讓同意到期日
- 建立成功,會回傳線上折讓同意到期日
- 回傳格式為「yyyy-MM-dd HH:mm:ss」;
- 建立失敗,則會回傳空值
IA_Remain_Allowance_Amt Int
折讓剩餘金額
- 建立成功,會回傳開立折讓後剩餘金額
- 建立失敗,則會回傳空值
Data參數範例
{
"RtnCode": 1,
"RtnMsg": "折讓單資料新增成功",
"IA_Allow_No": "1909181313013546",
"IA_Invoice_No": "UV11100019",
"IA_TempDate": "2019-09-18 13:13:23",
"IA_TempExpireDate": "2019-09-21 13:13:23",
"IA_Remain_Allowance_Amt": 0
}
ReturnURL綠界回傳參數說明
RtnCode Int
回應代碼
1 代表客戶折讓成功。
RtnMsg String(200)
回應訊息
IA_Allow_No String(16)
折讓單號
- 開立成功,會回傳折讓單號;
- 開立失敗,則會回傳空值。
IA_Invoice_No String(10)
發票號碼
- 開立成功,會回傳當初開立的發票號碼;
- 開立失敗,則會回傳空值。
IA_Date String(20)
折讓時間
- 開立成功,會回傳開立折讓時間
回傳格式為「yyyy-MM-dd HH:mm:ss」; - 開立失敗,則會回傳空值
IIS_Remain_Allowance_Amt Int
折讓剩餘金額
- 開立成功,會回傳開立折讓後剩餘金額
- 開立失敗,則會回傳空值
- 支援整數12位
範例
RtnCode=1&RtnMsg=&IA_Allow_No=1909181313013546&IA_Invoice_No=UV11100019&IA_Date=2019-09-18 13:13:23&IIS_Remain_Allowance_Amt=0&CheckMacValue=72F8C0BB157D97E68FCAF5E79E8E142D6B346BEEB756288BC668A5AA2C34980E
YAML
提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊,方便開發人員理解和使用 API。
openapi: 3.1.0
info:
title: ECPay Online Issue Allowance API
version: 1.0.0
servers:
- url: https://einvoice-stage.ecpay.com.tw
- url: https://einvoice.ecpay.com.tw
paths:
/B2CInvoice/AllowanceByCollegiate:
post:
summary: Online Issue Allowance
description: This API issues allowances electronically, notifying customers via email for confirmation.
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
RpHeader:
type: object
properties:
Timestamp:
type: integer
description: Unix timestamp in GMT+8
TransCode:
type: integer
description: Transmission code indicating success or failure
TransMsg:
type: string
maxLength: 200
description: Transmission message
Data:
type: string
description: Encrypted response data
components:
schemas:
requestBody.Data:
type: object
properties:
MerchantID:
type: string
maxLength: 10
description: Merchant ID
InvoiceNo:
type: string
maxLength: 10
description: Invoice number
InvoiceDate:
type: string
format: date
description: Invoice date (yyyy-MM-dd or yyyy/MM/dd)
AllowanceNotify:
type: string
maxLength: 1
description: Notification type (fixed value "E")
CustomerName:
type: string
maxLength: 60
description: Customer name
NotifyMail:
type: string
maxLength: 100
description: Notification email
AllowanceAmount:
type: number
description: Total allowance amount (including tax)
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
ReturnURL:
type: string
maxLength: 200
description: URL to notify merchant after customer confirms allowance
responses.Data:
type: object
properties:
RtnCode:
type: integer
description: Response code indicating success or failure
RtnMsg:
type: string
maxLength: 200
description: Response message
IA_Allow_No:
type: string
maxLength: 16
description: Allowance number
IA_Invoice_No:
type: string
maxLength: 10
description: Invoice number
IA_TempDate:
type: string
description: Online allowance date (yyyy-MM-dd HH:mm:ss)
IA_TempExpireDate:
type: string
description: Online allowance expiration date (yyyy-MM-dd HH:mm:ss)
IA_Remain_Allowance_Amt:
type: number
description: Remaining allowance amount