B2C電子發票API技術文件

發票查詢／查詢折讓明細

應用場景

可使用此API查詢已開立折讓之發票資訊，但不包含消費者尚未同意之線上折讓單

API介接網址

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

HTTPS傳輸協定

  • Content Type ：application/json
  • HTTP Method ：POST

特店傳入參數(Json格式)

PlatformID String(10)
特約合作平台商代號

  • 這個參數是專為與綠界簽約的指定平台商所設計，只有在申請開通後才能使用。
  • 如果您是一般廠商，請在介接時將此參數欄位保留為空。
  • 對於平台商，在使用時需要在MerchantID(特店編號)欄位中填入與您已經完成綁定子廠商的MerchantID(特定編號)。
    請注意，只能使用已綁定的子廠商編號，以避免操作失敗。綁定作業請洽所屬業務。

MerchantID String(10)
特店編號 必填

  1. 測試環境合作特店編號
  2. 正式環境金鑰取得

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)
特店編號 必填

SearchType String(1)
查詢方式 必填

0: 折讓編號 查詢
1: 發票號碼+發票開立日期 查詢
2: 發票號碼+發票折讓日期 查詢

AllowanceNo String(16)
折讓編號

  • 當查詢方式[SearchType]=0時，此參數必填
  • 其他值時，此參數無效

InvoiceNo String(10)
發票號碼

  • 當查詢方式[SearchType]=1或2時，此參數必填
  • 其他值時，此參數無效

Date String(10)
日期

1.當查詢方式[SearchType]=1時，請傳入發票開立日期
2.當查詢方式[SearchType]=2時，請傳入發票折讓日期
3.格式為「yyyy-MM-dd」或「yyyy/MM/dd」 

Data參數範例(Json格式)

				
					{
  "MerchantID": 2000132,
  "SearchType": "0",
  "AllowanceNo": "2019091719477262"
}

綠界回傳參數格式

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

AllowanceInfo Array
折讓資訊列表

Data參數範例

				
					{
  "RtnCode": 1,
  "RtnMsg": "成功",
  "AllowanceInfo": [
  {…},
  {…}
    ]
}

AllowanceInfo參數說明(Json格式)

ChannelPartner String(1)
通路商編號

1:蝦皮

IA_Allow_No String(16)
折讓單號

長度固定為16碼

IA_Check_Send_Mail String(1)
折讓通知

S：簡訊
E：電子郵件
A：皆通知時
N：皆不通知

IA_Date String(20)
折讓時間

格式為「yyyy-MM-dd HH:mm:ss」

Items Array[Object]
商品

ItemSeq Int
商品序號

ItemName String(100)
商品名稱

ItemCount Number
商品數量

ItemWord String(6)
商品單位

ItemPrice Number
商品單價

支援整數10位，小數7位

ItemRateAmt Number
商品營業稅額

支援整數11位

ItemTaxType String(1)
商品課稅別

1：應稅
2：零稅率
3：免稅

❗ 注意事項：

  • 預設為空字串，當課稅類別[TaxType] = 9時，此欄位不可為空。
  • 課稅類別為混合稅率時，需含二筆或以上的商品課稅別[ItemTaxType]，且至少需有一筆商品課稅別為應稅及至少需有一筆商品課稅別為免稅或零稅率，即混稅發票只能
    1.應稅+免稅
    2.應稅+零稅率，
    免稅和零稅率發票不能同時開立。

ItemAmount Number
商品合計

  • 此為含稅小計金額
  • 支援整數12位，小數7位

IA_IP String(20)
折讓IP

IA_Identifier String(10)
買受人統編

0000000000代表沒有統編

IA_Invalid_Status String(1)
折讓作廢狀態

1：折讓單已作廢
0：折讓單未作廢

IA_Invoice_Issue_Date String(20)
發票開立時間

格式為「yyyy-MM-dd HH:mm:ss」

IA_Invoice_No String(10)
發票號碼

長度固定為10碼

IA_Mer_ID String(10)
特店代號

IA_Send_Mail String(100)
通知的MAIL

送出通知時，所送的Email

IA_Send_Phone String(100)
通知的手機號碼

送出通知時，所送的手機號碼

IA_Tax_Amount Number
營業稅額合計

支援整數11位

IA_Tax_Type String(1)
課稅別

1：應稅
2：零稅率
3：免稅
4：應稅(特種稅率)

IA_Total_Amount Number
金額合計(不含稅之進貨額)

支援整數12位

IA_Total_Tax_Amount Number
金額合計(含稅)

支援整數12位

IA_Upload_Date String(20)
上傳時間

格式為「yyyy-MM-dd HH:mm:ss」

IA_Upload_Status String(1)
折讓上傳狀態

1：已上傳
0：未上傳

IIS_Customer_Name String(60)
買受人姓名

回傳AllowanceInfo參數範例

				
					{
    "ChannelPartner": "",
    "IA_Allow_No": "2019091719477262",
    "IA_Check_Send_Mail": "E",
    "IA_Date": "2019-09-17 19:47:19",
    "IA_IP": "0",
    "IA_Identifier": "0000000000",
    "IA_Invalid_Status": "1",
    "IA_Invoice_Issue_Date": "2019-09-17 19:47:05",
    "IA_Invoice_No": "UV11100016",
    "IA_Mer_ID": "2000132",
    "IA_Send_Mail": "test@ecpay.com.tw",
    "IA_Send_Phone": "0912345678",
    "IA_Tax_Amount": 2,
    "IA_Tax_Type": "1",
    "IA_Total_Amount": 48,
    "IA_Total_Tax_Amount": 50,
    "IA_Upload_Date": "",
    "IA_Upload_Status": "0",
    "IIS_Customer_Name": "綠界科技股份有限公司",
    "Items": [
        {
            "ItemSeq": 1,
            "ItemName": "item01",
            "ItemCount": 1,
            "ItemWord": "件",
            "ItemPrice": 50,
            "ItemTaxType": "1",
            "ItemRateAmt": 2,
            "ItemAmount": 50
        }
    ]
}

YAML

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

				
					openapi: 3.1.0
info:
  title: ECPay Query Allowance Details API
  version: 1.0.0
servers:
  - url: https://einvoice-stage.ecpay.com.tw
    description: Testing Environment
  - url: https://einvoice.ecpay.com.tw
    description: Production Environment
paths:
  /B2CInvoice/GetAllowanceList:
    post:
      summary: Query Allowance Details
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - MerchantID
                - RqHeader
                - Data
              properties:
                PlatformID:
                  type: string
                  maxLength: 10
                  description: Platform ID for partnered platforms
                MerchantID:
                  type: string
                  maxLength: 10
                  description: Merchant ID
                RqHeader:
                  type: object
                  required:
                    - Timestamp
                  properties:
                    Timestamp:
                      type: integer
                      description: Unix timestamp (GMT+8)
                Data:
                  type: string
                  description: Encrypted data containing request details
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  PlatformID:
                    type: string
                    maxLength: 10
                    description: Platform ID for partnered platforms
                  MerchantID:
                    type: string
                    maxLength: 10
                    description: Merchant ID
                  RpHeader:
                    type: object
                    properties:
                      Timestamp:
                        type: integer
                        description: Unix timestamp (GMT+8)
                  TransCode:
                    type: integer
                    description: Transmission code
                  TransMsg:
                    type: string
                    maxLength: 200
                    description: Transmission message
                  Data:
                    type: string
                    description: Encrypted data containing response details
components:
  schemas:
    requestBody.Data:
      type: object
      required:
        - MerchantID
        - SearchType
      properties:
        MerchantID:
          type: string
          maxLength: 10
          description: Merchant ID
        SearchType:
          type: string
          maxLength: 1
          description: Search type (0 is Allowance number, 1 is Invoice number and issue date, 2 is Invoice number and allowance date)
          enum: 
            - 0
            - 1
            - 2
        AllowanceNo:
          type: string
          maxLength: 16
          description: Allowance number (required if SearchType is 0)
        InvoiceNo:
          type: string
          maxLength: 10
          description: Invoice number (required if SearchType is 1 or 2)
        Date:
          type: string
          description: Date in 'yyyy-MM-dd' or 'yyyy/MM/dd' format (required if SearchType is 1 or 2)
    responses.Data:
      type: object
      properties:
        RtnCode:
          type: integer
          description: Response code
        RtnMsg:
          type: string
          maxLength: 200
          description: Response message
        AllowanceInfo:
          type: array
          items:
            type: object
            properties:
              ChannelPartner:
                type: string
                maxLength: 1
                description: Channel partner ID
              IA_Allow_No:
                type: string
                maxLength: 16
                description: Allowance number
              IA_Check_Send_Mail:
                type: string
                maxLength: 1
                description: Allowance notification (S is SMS, E is Email, A is Both, N is None)
                enum: 
                  - S
                  - E
                  - A
                  - N
              IA_Date:
                type: string
                description: Allowance date in 'yyyy-MM-dd HH:mm:ss' format
              Items:
                type: array
                items:
                  type: object
                  properties:
                    ItemSeq:
                      type: integer
                      description: Item sequence number
                    ItemName:
                      type: string
                      maxLength: 100
                      description: Item name
                    ItemCount:
                      type: number
                      description: Item quantity
                    ItemWord:
                      type: string
                      maxLength: 6
                      description: Item unit
                    ItemPrice:
                      type: number
                      description: Item unit price
                    ItemRateAmt:
                      type: number
                      description: Item tax amount
                    ItemTaxType:
                      type: string
                      maxLength: 1
                      description: Item tax type (1 is Taxable, 2 is Zero tax rate, 3 is Exempt)
                    ItemAmount:
                      type: number
                      description: Item total amount
              IA_IP:
                type: string
                maxLength: 20
                description: Allowance IP
              IA_Identifier:
                type: string
                maxLength: 10
                description: Buyer identifier (0000000000 if none)
              IA_Invalid_Status:
                type: string
                maxLength: 1
                description: Allowance invalidation status (1 is Invalid, 0 is Not invalid)
              IA_Invoice_Issue_Date:
                type: string
                description: Invoice issue date in 'yyyy-MM-dd HH:mm:ss' format
              IA_Invoice_No:
                type: string
                maxLength: 10
                description: Invoice number
              IA_Mer_ID:
                type: string
                maxLength: 10
                description: Merchant ID
              IA_Send_Mail:
                type: string
                maxLength: 100
                description: Notification email
              IA_Send_Phone:
                type: string
                maxLength: 100
                description: Notification phone number
              IA_Tax_Amount:
                type: number
                description: Total tax amount
              IA_Tax_Type:
                type: string
                maxLength: 1
                description: Tax type (1 is Taxable, 2 is Zero tax rate, 3 is Exempt, 4 is Taxable (special rate))
              IA_Total_Amount:
                type: number
                description: Total amount (excluding tax)
              IA_Total_Tax_Amount:
                type: number
                description: Total amount (including tax)
              IA_Upload_Date:
                type: string
                description: Upload date in 'yyyy-MM-dd HH:mm:ss' format
              IA_Upload_Status:
                type: string
                maxLength: 1
                description: Allowance upload status (1 is Uploaded, 0 is Not uploaded)
              IIS_Customer_Name:
                type: string
                maxLength: 60
                description: Buyer name

Copyright © Green World FinTech Service Co., Ltd. All rights reserved.

綠界官方網站