# 目錄 [[_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 | |