發票作業 / 開立折讓 / 一般開立折讓（紙本開立）

使用流程說明

營業人(特店)可使用此功能將折讓開立參數傳送至綠界，由綠界暫存折讓資料。綠界於隔日將折讓資料上傳至財政部電子發票整合服務平台，並通知消費者(買家)折讓已開立。

應用場景

若商品質量、規格等不符合消費者要求，特店同意在商品價格上給予減讓，可使用此API將開立折讓發票參數傳送至綠界，暫存折讓發票資料。綠界會於隔日，將折讓資料上傳至財政部電子發票整合服務平台。

注意事項：根據財政部規定，API送出紙本折讓資料後，還需請買受人確認折讓單內容，所以您必須再郵寄紙本折讓單給消費者簽名後寄回自行存檔，以備主管機關不定期查核。

API介接網址

測試環境：https://einvoice-stage.ecpay.com.tw/B2CInvoice/Allowance
正式環境：https://einvoice.ecpay.com.tw/B2CInvoice/Allowance

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)
通知類別 必填

開立折讓後，寄送將相關發票折讓資訊通知消費者
S：簡訊
E：電子郵件
A：皆通知時
N：皆不通知

CustomerName String(60)
客戶名稱

格式為中、英文及數字等

NotifyMail String(100)
通知電子信箱

若通知類別[AllowanceNotify]為電子郵件(E)，此欄位須有值
需為有效的Email格式
可帶入多組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])))\.?$

NotifyPhone String(20)
通知手機號碼

若通知類別[AllowanceNotify]為簡訊方式(S)，此欄位須有值
格式為數字組成

AllowanceAmount Number
折讓單總金額(含稅) 必填

支援整數12位

注意事項：該筆折讓單總金額應該大於0元

如此張發票未折讓過，則應小於或等於原發票總金額
如此張發票已折讓過，則應小於或等於折讓剩餘金額
折讓單總金額設0元不被允許，是因為此行為代表此張發票不需折讓，不代表此張發票要被折讓到0元

Items Array[Object]
商品

ItemSeq Int
商品序號 必填

ItemName String(500)
商品名稱 必填

不可為空字串

ItemCount Number
商品數量 必填

支援整數8位，小數7位

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]
提醒您，依營業稅電子資料申報繳稅作業要點，電子發票銷貨退回、進貨退出或折讓證明單之「金額(不含稅之進貨額)」及「營業稅額」欄位須為整數，以利申報資料正確，建議此欄位請帶入整數

Data參數範例

				
					{
    "MerchantID": "2000132",
    "InvoiceNo": "UV11100013",
    "InvoiceDate": "2019/09/17",
    "AllowanceNotify": "E",
    "CustomerName": "綠界科技股份有限公司",
    "NotifyMail": "test@ecpay.com.tw",
    "NotifyPhone": "0912345678",
    "AllowanceAmount": 50,
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "件",
            "ItemPrice": 50,
            "ItemTaxType": "2",
            "ItemAmount": 50
        }
    ]
}

綠界回傳參數格式

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)
回應訊息

IA_Allow_No String(16)
折讓單號

開立成功，會回傳折讓單號；
開立失敗，則會回傳空值。

IA_Invoice_No String(10)
發票號碼

開立成功，會回傳當初開立的發票號碼；
開立失敗，則會回傳空值。

IA_Date String(20)
折讓時間

開立成功，會回傳開立折讓時間
回傳格式為「yyyy-MM-dd HH:mm:ss」；
開立失敗，則會回傳空值

IA_Remain_Allowance_Amt Number
折讓剩餘金額

開立成功，會回傳開立折讓後剩餘金額
開立失敗，則會回傳空值
支援整數12位

Data參數範例

				
					{
    "IA_Allow_No": "2019091717363987",
    "IA_Invoice_No": "UV11100013",
    "IA_Date": "2019-09-17 17:36:18",
    "IA_Remain_Allowance_Amt": 50,
    "RtnCode": 1,
    "RtnMsg": "折讓單資料新增成功"
}

YAML

提供的 YAML 文件用於定義 API 的配置、結構、操作和基礎設施管理等資訊，方便開發人員理解和使用 API。

				
					openapi: 3.1.0
info:
  title: ECPay General Issue Allowance API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
  - url: https://einvoice.ecpay.com.tw
paths:
  /B2CInvoice/Allowance:
    post:
      summary: General Issue Allowance
      description: This API issues allowances for discrepancies such as quality or specification issues.
      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 (S=SMS, E=Email, A=All, N=None)
        CustomerName:
          type: string
          maxLength: 60
          description: Customer name
        NotifyMail:
          type: string
          maxLength: 100
          description: Notification email
        NotifyPhone:
          type: string
          maxLength: 20
          description: Notification phone number
        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
    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_Date:
          type: string
          description: Allowance issue date (yyyy-MM-dd HH:mm:ss)
        IA_Remain_Allowance_Amt:
          type: number
          description: Remaining allowance amount

綠界官方網站