---
# System prepended metadata

title: 目錄

---

# 目錄
[[_TOC_]]

- [ Version ](#Version)
- [ 1. 即時核銷票卷 ](#1.-即時核銷票卷)
- [ 2. 批次核銷票卷 ](#2.-批次核銷票卷)
- [ 3. 取得用戶票券清單 ](#3.-取得用戶票券清單)
- [ 4. 新增用戶票券 ](#4.-新增用戶票券)
- [ Appendix. 錯誤碼列表 ](#Appendix.-錯誤碼列表)

# Version

| 版本 | 日期 | 資訊 |
| -------- | -------- | -------- | 
| v1.0.0    |  2022/11/01  | 初版    | 
| v1.0.1 | 2023/02/03 | **新增用戶票券 API** 回傳值更新 | 

---
# 1. 即時核銷票卷

## Requirement
- 需提供IP開通白名單才可使用此 api

## API : updateCouponStatus

### * **URL**

  `/store/api/v1/updateCouponStatus`
  
### * **Method**

  `POST`
  
### * **Headers**

  ```json
  "content-type": "application/json"
  ```
  
### **Request Body**

#### **Required:**
  
  * **廠商代碼**

    由遠傳提供

    `partner_prefix=[string]`

  * **廠商核銷序號**

    `ecoupon_sn_string=[string]`

#### **Optional:**

  * **動作**

    `action=[string]`

    redeem: 核銷， recover: 回復票券， 預設redeem
  
  **範例**

  ```json
  {
    "partner_prefix": "XIAOMI",
    "ecoupon_sn_string": "5JQyd6TfqEsJJgPp",
    "action": "redeem"
  }
  ```
  
### Response

  **Required:**

  * **錯誤碼**

    `errCode=[string]`

  * **錯誤訊息**

    `errMsg=[string]`

  * **詳細錯誤訊息**

    `errDetail=[string]`


#### 成功範例

  ```json
  {
    "errCode": "00",
    "errMsg": "",
    "errDetail": ""
  }
  ```

#### 失敗範例

  ```json
  {
    "errCode": "101",
    "errMsg": "Invalid request",
    "errDetail": ""
  }
  ```

# 2. 通用型批次核銷票卷

## Requirement
- 廠商提供IP白名單後，可將每日核銷票卷序號上傳至遠傳提供的SFTP。

## 核銷資料檔

* **目錄**

  `SFTP根目錄`

* **檔名**

  `大小寫英文數字組合`

* **內容**

  ```
  5JQyPDOd6TfqEsJJgPp
  GksnWvvsamufuJXp
  DWP8CcPXRYkudwTv
  ```

# 3. 取得用戶票券清單

## Requirement

- 需提供IP開通白名單才可使用此 api
- 需申請 partner_prefix

## API : getUserCoupon

### * **URL**

  `/store/api/v1/getUserCoupon`
  
### * **Method**

  `POST`
  
### * **Headers**

  ```json
  "content-type": "application/json"
  ```
  
### Request

#### **Required:**

  * **用戶ID**

    `user_id=[string]`

#### **Optional:**
  
  * **廠商代碼**

    `partner_prefix=[string]`
  
  * **票卷核銷狀態**

    `isDisabled=[boolean]`
    
  **範例**

  ```json
  {
    "user_id": "1234567890"
    "partner_prefix": "XIAOMI"
  }
  ```
  
### Response

  **Required:**

  * **錯誤碼**

    `errCode=[string]`

  * **錯誤訊息**

    `errMsg=[string]`

  * **詳細錯誤訊息**

    `errDetail=[string]`

  * **票卷序號**
  
    `ecoupon_sn_string=[string]`
    
  * **廠商編碼**
  
    `partner_prefix=[string]`

  * **票卷圖示**
  
    `prod_images_ratio1x1=[string]`
    
  * **起始日期**
  
    `start_date=[string]`
    
  * **結束日期**
  
    `end_date=[string]`
    
  * **用戶手動核銷**
  
    `can_be_marked_used_by_user=[boolean]`
    
  * **廠商自動核銷**
  
    `can_be_marked_used_by_partner=[boolean]`
    
  * **票卷名稱**
  
    `ecoupon_name=[string]`
    
  * **票卷備註**
  
    `foot_note=[string]`
    
  * **票卷說明**
  
    `description=[string]`
  
  * **二段條碼隱藏**
  
    `barcode_2_display_value_hide=[string]`
   
  * **用戶核銷**
  
    `status_marked_used_by_user=[boolean]`
 
  * **用戶核銷時間**
  
    `status_marked_used_by_user_time=[datetime]`
    
  * **廠商核銷**
  
    `status_marked_used_by_partner=[boolean]`

  * **廠商核銷時間**
  
    `status_marked_used_by_partner_time=[datetime]`

  * **票卷取得時間**

    `received_time=[datetime]`
    
  * **票卷核銷狀態**

    `isDisabled=[boolean]`

#### 成功範例

  ```json
  {
    "errCode": "00",
    "errMsg": "",
    "errDetail": "",
    "coupons": [
      {
        "ecoupon_sn_string": "5JQyd6TfqEsJJgPp",
        "partner_prefix": "XIAOMI",
        "prod_images_ratio1x1": "https://picdn.gomaji.com/products/o/469/235469/235469_1_9.jpg",
        "start_date": "2021-01-01",
        "end_date": "2023-01-01",
        "can_be_marked_used_by_user": false,
        "can_be_marked_used_by_partner": true,
        "ecoupon_name": "小米電風扇兌換卷",
        "display_label": "兌換券",
        "foot_note": "此券只能使用一次",
        "description": "這是測試票券",
        "barcode_2_display_value_hide": false,
        "status_marked_used_by_user": false,
        "status_marked_used_by_partner": false,
        "status_marked_used_by_user_time": "",
        "status_marked_used_by_partner_time": "",
        "received_time": "2022-03-22T10:59:54+08:00",
        "isDisabled": false
      },
      {
        "ecoupon_sn_string": "fpNF5VNqmEUu7yat",
        "partner_prefix": "XIAOMI",
        "prod_images_ratio1x1": "https://picdn.gomaji.com/products/o/469/235469/235469_1_9.jpg",
        "start_date": "2021-01-01",
        "end_date": "2023-01-01",
        "can_be_marked_used_by_user": false,
        "can_be_marked_used_by_partner": true,
        "ecoupon_name": "小米電風扇兌換卷",
        "display_label": "兌換券",
        "foot_note": "此券只能使用一次",
        "description": "這是測試票券",
        "barcode_2_display_value_hide": false,
        "status_marked_used_by_user": false,
        "status_marked_used_by_partner": true,
        "status_marked_used_by_user_time": "",
        "status_marked_used_by_partner_time": "2021-12-21T00:04:52+08:00",
        "received_time": "2022-03-22T10:59:54+08:00",
        "isDisabled": false
      }
    ]
  }

  ```
# 4. 新增用戶票券

## Requirement
- 需提供IP開通白名單才可使用此 api
- 需申請 partner_prefix
- 需申請 partnerApikey

## API : addUserCoupon

### **URL**

  `/store/api/v1/addUserCoupon`
  
### **Method**

  `POST`
  
### **Headers**

  ```json
  "content-type": "application/json",
  "partner_prefix": "tw_fetnet"
  "apikey": "9e8a0dd6558896fa23868308f16fd970"
  ```
    - apikey = MD5(moment().format('YYYYMMDD') + partnerApikey)  
    - YYYYMMDD 的時區必須是台灣時區(+8)
  
### Request Body

#### **Required:**

  * **加密後資料**

    `encryptedData=[string]`

    - 加密方式為 AES_CBC，將整個原始 json 加密後放置此欄位

  * **用戶ID**

    `user_id=[string]`

  * **coupon序號**

    `ecoupon_sn_string=[string]`

  * **序號類型**

    `sn_type=[string]`

    - valid value: RAW_STRING | BARCODE | BARCODE1_BARCODE2 | QRCODE
    - If value is 'BARCODE1_BARCODE2', the $ecoupon_sn_string SHOULD be in this format: "11122bwe,123444cde".
    - If value is "BARCODE" or "QRCODE" or "RAW_STRING", the $ecoupon_sn_string SHOULD be in this format: "11122bwe"

  * **廠商代碼**

    `partner_prefix=[string]`

  * **產品圖檔 1X1**

    `prod_images_ratio1x1=[string]`

    - ratio 為 1:1 的圖，

  * **票券起始日**

    `start_date=[string]`

  * **票券截止日**

    `end_date=[string]`

  * **票券名稱**

    `ecoupon_name=[string]`

  * **顯示標籤**

    `display_label=[string]`

    - This field is for this e-coupon displaying (in order) on app. Please be careful, if the value is not valid, then this e-coupon won't be allowed to display on app.

    - valid value: 兌換券 | 折價券

  * **底部顯示**

    `foot_note=[string]`

    - The '注意事項' area in app

  * **描述**

    `description=[string]`

    - The description of this e-coupon. It is valid for the value is '' (empty string).

  * **交易序號**

    `transationId=[string]`

    - 賦予此次入劵交易一個 unique string
  
#### **Optional:**

  * **活動網址**

    `activity_url=[string]`

    - The URL which app will go when '前往活動頁' button is clicked. If the value is '' (empty string), then the button won't show.

  * **批次序號**

    `batch_sn=[string]`

    - 同一批序號可以賦予一個 unique string ，例如同一天發的 / 同一系列的 / 同一批生產的，可作為日後查詢分析使用


  **範例**

  ```json
  {
    encryptedData: "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"
  }

  解密後:
  {
    "user_id": "1234567890",
    "ecoupons": [
        {
            "ecoupon_sn_string": "eventid_productid_003",
            "sn_type": "NO_CODE",
            "partner_prefix": "tw_fetnet",
            "prod_images_ratio1x1": "https://prodrateplanplatform.blob.core.windows.net/public/product_RPP_Product201021110627750/productPic1.jpeg",
            "start_date": "2022-07-01",
            "end_date": "2022-12-31",
            "ecoupon_name": "10/10活動-快樂水",
            "display_label": "兌換卷",
            "foot_note": "申辦本專案合約生效後，申辦者可得：星巴克即享券32杯咖啡組合。商品服務將於次月底前，依申辦時登記個人資訊而配送，若對星巴克即享券使用上有疑問，可洽宜睿之客服電話 (02)6639-1012 或email（ticketxpress-cs-tw@edenred.com）查詢。商品服務將以簡訊通知兌換序號。票券有效期：宜睿智慧即享券產出後六個月。本商品電子兌換憑證係由星巴克提供服務。本商品電子兌換憑證可於指定兌換期限內至限定星巴克門市兌換，除部份公告不適用門市外，恕不得更換現金或其他商品，禁止轉讓、轉售與退換貨，不適用於外送外賣及預訂服務。公告不適用門市列表連結：https://www.edenred.com.tw/STARBUCKS/store.html折扣、優惠、兌換星禮程回饋與優惠、各行銷活動恕不合併使用，兌換品項依各門市現貨為準。若有憑證兌換問題，可撥打服務專線02-66391012。本商品電子兌換憑證每次交易可兌換5張。若於兌換前查詢或取消使用，序號將被鎖定10分鐘，請於10分鐘之後再進行兌換。本商品電子兌換憑證可兌換券上所載之指定商品 ，兌換時不開立發票。本商品電子兌換憑證僅限兌換一次，不得重複使用，因商品電子兌換憑證為不記名，任何人持有皆可兌換，請自行妥善保管，如遭他人盜用，不再補發。本商品電子兌換憑證，請勿擅自偽造、變造以免受罰。",
            "activity_url": "",
            "description": "活動當天，請由現場人員進行核銷後才可取水。",
            "batch_sn":"auto-dispatcher-xx01",
            "transationId": "20221027XXXXX"
        }
    ]
  }
  ```

encryptedData = CryptoJS.AES.encrypt(data, CryptoJS.enc.Utf8.parse(apiKey),{
    "iv": CryptoJS.enc.Utf8.parse(apiKey),
    "mode": CryptoJS.mode.CBC,
    "padding": CryptoJS.pad.Pkcs7
}).toString();

  
### 失敗範例

  ```json
  {
    "errCode": "101",
    "errMsg": "Invalid request",
    "errDetail": ""
  }
  ```

---
# Appendix. 錯誤碼列表

  | errCode  | errMsg      | errDetail  |
  | -------- | --------    | --------   |
  | 00       |             |            |
  | 101      | Invalid request |        |
  | 102      | Internal server error |  |
  | 124      | Serial number not found | |
  | 104      | Duplicate coupon prefix and sn | |
  | 105      | Wrong parameter | |

