# 票券 --- API 清單 - 票券管理[WEB] - [取得票券點數兌換基準](#取得票券點數兌換基準) - 平台管理員 - [取得待新增票券租戶列表](#取得待新增票券租戶列表) - [取得票券發行廠商管理列表](#取得票券發行廠商管理列表) - [取得票券發行廠商明細](#取得票券發行廠商明細) - [新增票券發行廠商](#新增票券發行廠商) - [編輯票券發行廠商](#編輯票券發行廠商) - [刪除票券發行廠商](#刪除票券發行廠商) - [取得票券發行額度管理列表](#取得票券發行額度管理列表) - [新增票券購買額度](#新增票券購買額度) - [編輯票券購買額度](#編輯票券購買額度) - [取得票券統計列表](#取得票券統計列表) - [票券統計(平台管理員)](#票券統計平台管理員) - 租戶管理員 - [取得票券管理Summary](#取得票券管理Summary) - [票券管理列表](#票券管理列表) - [取得票券管理明細](#取得票券管理明細) - [取得上傳網址](#取得上傳網址) - [新增票券](#新增票券) - [編輯票券](#編輯票券) - [編輯票券上下架狀態](#編輯票券上下架狀態) - [刪除票券](#刪除票券) - [票券統計(租戶管理員)](#票券統計租戶管理員) - [匯入折扣碼優惠劵excel](#匯入折扣碼優惠劵excel) - [下載健檢錯誤資料檔](#下載健檢錯誤資料檔) - 票券[APP] - [我的票券摘要](#我的票券摘要) - [取得票券列表](#取得票券列表) - [取得票券明細](#取得票券明細) - [兌換票券](#兌換票券) - [使用(核銷)票券](#使用核銷票券) - [我的票券列表](#我的票券列表) - [取得我的票券明細](#取得我的票券明細) - [票券觸及(曝光)](#票券觸及曝光) - [票券點擊](#票券點擊) --- ## 取得票券點數兌換基準 ```url GET voucher-mgmt/unit-points-rate ``` * 限平台管理員、租戶管理員叫用 #### Request-取得票券點數兌換基準 ```javascript ``` #### Response-取得票券點數兌換基準 欄位 | 型態 | 說明 --- | --- | --- unitPoints | int | 折抵1元需多少點數 ```javascript { "httpCode": 200, "result": { "data": { "unitPoints": 30 } } } ``` ## 取得待新增票券租戶列表 ```url GET /voucher-mgmt/vendor/tenant-list ``` * 限平台管理員叫用 #### Request-取得待新增票券租戶列表 #### Response-取得待新增票券租戶列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 租戶id name | string | 租戶名稱 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "name": "緯緯醫學", "tenantType": "DEALER", "industryTypeList": [] }, { "id": "1af0a4c2-ef73-4385-aa8e-8e7ae8afe155", "name": "小港醫院", "tenantType": "HOSPITAL", "industryTypeList": [] }, { "id": "68f2bc3d-7afa-46f6-89b2-8b6a04d55010", "name": "緯創醫學", "tenantType": "WMT", "industryTypeList": [] }, ... ] } } ``` ## 取得票券發行廠商管理列表 ```url POST /voucher-mgmt/vendor/list ``` #### Request-取得票券發行廠商管理列表 ##### Request-取得票券發行廠商管理列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- name | string | | | 關鍵字, 查詢組織名稱 ##### Request-取得票券發行廠商管理列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-取得票券發行廠商管理列表-sorter(排序json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | updateTime | 排序欄位,可排序欄位有 vendorName, deposit, withdraw, quota, updateTime order | string | | asc | 升序或降序 ```javascript { "query": { "name": null } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "vendorName", "order": "asc" } } ``` #### Response-取得票券發行廠商管理列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券發行機構id tenantId | string | 租戶id vendorName | string | 租戶名稱 deposit | long | 總累計購買額度(點) withdraw | long | 已使用額度(點) quota | long | 可使用額度(點) updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "7d6e2c12-efee-4bb4-b546-c6b98e5d8b92", "tenantId": "1af0a4c2-ef73-4385-aa8e-8e7ae8afe155", "vendorName": "小港醫院", "updateTime": 1645513185498 }, { "id": "3b4f34d8-eb62-4f42-9809-499ee323e7d0", "tenantId": "68f2bc3d-7afa-46f6-89b2-8b6a04d55010", "vendorName": "緯創醫學", "deposit": 15000, "withdraw": 0, "quota": 15000, "updateTime": 1645501162150 } ], "pagination": { "current": 1, "pageSize": 10, "total": 3 }, "sorter": { "field": "updateTime", "order": "desc" }, "total": 3 } } ``` ## 取得票券發行廠商明細 ```url POST /voucher-mgmt/vendor/info ``` * 此API可由平台管理員及租戶管理員叫用 #### Request-取得票券發行廠商明細 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 租戶id, 平台管理員呼叫此API必填, 租戶管理員呼叫此API時不用填,會由userToken取得 ```javascript { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc" } ``` #### Response-取得票券發行廠商明細 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券發行機構id tenantId | string | 租戶id deposit | long | 總累計購買額度(點) withdraw | long | 已使用額度(點) quota | long | 可使用額度(點) updateTime | timestamp | 最後更新時間 vendorNo | srring | 發行機構代碼 ```javascript { "httpCode": 200, "result": { "data": { "id": "b3dd29bd-bef1-4fc2-9cc2-630ac39bf620", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "deposit": 11000000, "withdraw": 44100, "quota": 10955900, "updateTime": 1646115071566, "vendorNo": "W00001" } } } ``` ## 新增票券發行廠商 ```url POST /voucher-mgmt/vendor/add ``` #### Request-新增票券發行廠商 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 租戶id ```javascript { "tenantId": "1af0a4c2-ef73-4385-aa8e-8e7ae8afe155" } ``` #### Error-新增票券發行廠商 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_VENDOR_EXIST | 票券發行機構已存在 #### Response-新增票券發行廠商 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券發行機構id tenantId | string | 租戶id vendorNo | string | 機構識別碼,1碼大寫英文+5碼流水號, 共6碼, 會用來組成票券號碼 updateTime | timestamp | 最後更新時間 * vendorNo 機構識別碼編碼規則: 為1碼大寫英文+5碼流水號所組成 <br />新增發行機構時,隨機取一碼英文字母, 流水號為該英文字母下的流水號,由00001開始編起 ```javascript { "httpCode": 200, "result": { "data": { "id": "d3c17d39-401e-478e-87b5-6a732d5dd849", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "updateTime": 1645531365358, "vendorNo": "V00002" } } } ``` ## 編輯票券發行廠商 ```url POST /voucher-mgmt/vendor/update ``` * 票券發行機構尚未新增額度時才允許編輯 #### Request-編輯票券發行廠商 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券發行機構id tenantId | string | Y | | 要變更的新租戶id ```javascript { "id": "27237d9c-e48c-4e98-9237-d91d1b1445f3", "tenantId": "1af0a4c2-ef73-4385-aa8e-8e7ae8afe155" } ``` #### Error-編輯票券發行廠商 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_VENDOR_UPDATE_NOT_ALLOWED | 已有設定額度,不允許編輯 422 | SERVICE_ERROR.VOUCHER_VENDOR_EXIST | 票券發行機構已存在 #### Response-編輯票券發行廠商 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券發行機構id tenantId | string | 租戶id vendorNo | string | 機構識別碼,1碼大寫英文+5碼流水號, 共6碼, 會用來組成票券號碼 updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": { "id": "d3c17d39-401e-478e-87b5-6a732d5dd849", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "updateTime": 1645531365358, "vendorNo": "V00002" } } } ``` ## 刪除票券發行廠商 ```url POST /voucher-mgmt/vendor/delete ``` * 票券發行機構尚未新增額度時才允許刪除 #### Request-刪除票券發行廠商 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券發行機構id ```javascript { "id": "215c5ded-7eea-4818-b197-3faa210224ca" } ``` #### Error-刪除票券發行廠商 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_VENDOR_DELETE_NOT_ALLOWED | 已有設定額度,不允許刪除 #### Response-刪除票券發行廠商 欄位 | 型態 | 說明 --- | --- | --- count | int | 刪除筆數,若刪除成功,筆數應為1 ```javascript { "httpCode": 200, "result": { "data": { "count": 1 } } } ``` ## 取得票券發行額度管理列表 ```url POST /voucher-mgmt/quota/list ``` * 此API可由平台管理員及租戶管理員叫用 #### Request-取得票券發行額度管理列表 ##### Request-取得票券發行額度管理列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 租戶id, 平台管理員呼叫此API時必填,租戶管理員呼叫時不用填,會由userToken取得 ##### Request-取得票券發行額度管理列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-取得票券發行額度管理列表-sorter(排序json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | txDate | 排序欄位,可排序欄位有 txDate, points, amount, updateTime order | string | | desc | 升序或降序 ```javascript { "query": { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc" } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "txDate", "order": "desc" } } ``` #### Response-取得票券發行額度管理列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券額度id tenantId | string | 租戶id txDate | timestamp | 購買日期 points | int | 購買額度(點) amount | double | 購買金額 remark | string | 備註 updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "f1eafbab-5e51-49ae-bd6f-33aea62358e0", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "txDate": 1645459200000, "points": 4500, "amount": 2250, "remark": "change 3rd quota-3,000 to quota-4500", "updateTime": 1645514109735 }, { "id": "29948d7d-7075-4377-a470-832f9f041f22", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "txDate": 1645459200000, "points": 5000, "amount": 2500, "remark": "add second quota-5,000", "updateTime": 1645501243586 }, ... ], "pagination": { "current": 1, "pageSize": 10, "total": 3 }, "sorter": { "field": "updateTime", "order": "desc" }, "total": 3 } } ``` ## 新增票券購買額度 ```url POST /voucher-mgmt/quota/add ``` #### Request-新增票券購買額度 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 租戶id txDate | timestamp | Y | | 購買日期 points | int | Y | | 購買額度(點),需 >= 0 amount | double | Y | | 購買金額,需 >= 0 remark | string | N | | 備註, maxLength=500 ```javascript { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "txDate": 1645488000000, "points": 5000000, "amount": 150000, "remark": "add 4rd quota-5,000,000" } ``` #### Error-新增票券購買額度 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_VENDOR_NOT_EXIST | 票券發行機構不存在 #### Response-新增票券購買額度 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券額度id tenantId | string | 租戶id txDate | timestamp | 購買日期 points | int | 購買額度(點) amount | double | 購買金額 remark | string | 備註 updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": { "id": "48a4d6bc-fb95-4c00-a82e-56a7f1ec460e", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "txDate": 1645488000000, "points": 5000000, "amount": 150000, "remark": "add 4rd quota-5,000,000", "updateTime": 1645530158443 } } } ``` ## 編輯票券購買額度 ```url POST /voucher-mgmt/quota/update ``` * 編輯購買額度時,只允許編輯最新一筆的購買額度 #### Request-編輯票券購買額度 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券額度id txDate | timestamp | Y | | 購買日期 points | int | Y | | 購買額度(點),需 >= 0 amount | double | Y | | 購買金額,需 >= 0 remark | string | N | | 備註, maxLength=500 ```javascript { "id": "ff0fd7b8-b97b-4a8f-826d-a0326cfaf97d", "txDate": 1645459200000, "points": 5000000, "amount": 150000, "remark": "change 4rd quota-1,000,000 to quota-5,000,000" } ``` #### Error-編輯票券購買額度 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_QUOTA_UPDATE_NOT_LATEST | 非最新一筆購買額度,不允許編輯 422 | SERVICE_ERROR.VOUCHER_QUOTA_UPDATE_UNDER_ZERO | 修改後額度小於可用額度, 不可修改 #### Response-編輯票券購買額度 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券額度id tenantId | string | 租戶id txDate | timestamp | 購買日期 points | int | 購買額度(點) amount | double | 購買金額 remark | string | 備註 updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": { "id": "ff0fd7b8-b97b-4a8f-826d-a0326cfaf97d", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "txDate": 1645459200000, "points": 5000000, "amount": 150000, "remark": "change 4rd quota-1,000,000 to quota-5,000,000", "updateTime": 1645530158443 } } } ``` ## 取得票券統計列表 ```url POST /voucher-mgmt/statistics/list ``` #### Request-取得票券統計列表 ##### Request-取得票券統計列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- startDate | string | | | 票券上架日期查詢起日, 格式為YYYY-MM-DD endDate | string | | | 票券上架日期查詢迄日, 格式為YYYY-MM-DD voucherType | string | | | 票券類別,未填值表示查詢所有類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 name | string | | | 關鍵字, 查詢票券機構名稱 ##### Request-取得票券統計列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-取得票券統計列表-sorter(排序json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | tenantName | 排序欄位,可排序欄位有 tenantName, volume, reachCount, reachTimes, clickCount, clickTimes, clickRate, redeemCount, redeemRate, usedCount, usedRate, usedAmount order | string | | asc | 升序或降序 ```javascript { "query": { "startDate": null, "endDate": null, "voucherType": null, "name": null } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "tenantName", "order": "asc" } } ``` #### Response-取得票券統計列表 欄位 | 型態 | 說明 --- | --- | --- tenantId | string | 租戶id tenantName | string | 租戶名稱 volume | long | 已發行票券(張) redeemCount | long | 已兌換票券(張) redeemRate | double | 兌換率 usedCount | long | 已使用票券(張) usedAmount | double | 總計已使用金額 usedRate | double | 使用率 reachCount | long | 票券曝光(人數) reachTimes | long | 票券曝光(人次) clickCount | long | 票券點擊(人數) clickTimes | long | 票券點擊(人次) clickRate | double | 點擊率 ```javascript { "httpCode": 200, "result": { "data": [ { "tenantId": "1af0a4c2-ef73-4385-aa8e-8e7ae8afe155", "tenantName": "小港醫院" }, { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "tenantName": "緯緯醫學", "volume": 588, "redeemCount": 11, "redeemRate": 1.9, "usedCount": 4, "usedAmount": 6.00, "usedRate": 36.4, "reachCount": 2, "reachTimes": 26, "clickCount": 1, "clickTimes": 3, "clickRate": 50.0 } ], "pagination": { "current": 1, "pageSize": 10, "total": 4 }, "sorter": { "field": "tenantName", "order": "asc" }, "total": 4 } } ``` ## 票券統計(平台管理員) ```url POST /voucher-mgmt/voucher/statistics ``` * 票券統計API, 平台及租戶管理員是用叫同一支API,但傳入參數不同, 回傳的結果, 平台管理員會多回傳一個summaryInfo #### Request-票券統計(平台管理員) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 租戶id voucherType | string | | | 票券類別,未填值表示查詢所有類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 ```javascript { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherType": null } ``` #### Response-票券統計(平台管理員) 欄位 | 型態 | 說明 --- | --- | --- summaryInfo | json | 租戶票券統計摘要json redeemInfo | json | 票券兌換分析json usedInfo | json | 票券使用分析json reachInfo | json | 票券曝光分析json clickInfo | json | 票券點擊分析json ##### Response-票券統計(平台管理員)-summaryInfo(租戶票券統計摘要json) 欄位 | 型態 | 說明 --- | --- | --- tenantId | string | 租戶id tenantName | string | 租戶名稱 deposit | long | 累計購買額度(點) withdraw | long | 已使用額度(點) quota | long | 票券可使用額度-總計可使用(點) totalVolume | long | 已發行票券-票券張數 totalPoints | long | 已發行票券-票券點數 totalAmount | double | 已發行票券-票券金額 totalUnRedeemCount | long | 尚未兌換票券-票券張數 totalUnRedeemPoints | long | 尚未兌換票券-票券點數 totalRedeemCount | long | 已兌換票券-票券張數 totalRedeemPoints | long | 已兌換票券-票券點數 totalRedeemAmount | double | 已兌換票券-票券金額 totalUsedCount | long | 已使用票券-票券張數 totalUsedAmount | double | 已使用票券-總計已使用金額 quotaAvailRate | double | 票券可使用額度-可用量 redeemRate | double | 已兌換票券-兌換率 usedRate | double | 已使用票券-使用率 clickRate | double | 點擊率 ##### Response-票券統計(平台管理員)-redeemInfo(票券兌換分析json) 欄位 | 型態 | 說明 --- | --- | --- totalRedeemCount | long | 已兌換量-票券張數 totalRedeemAmount | double | 總計已兌換金額 totalRedeemRate | double | 總兌換率, 兌換率=已兌換量/票券發行數量 totalCount | int | 總 兌換/使用 張數 totalAmount | int | 總 兌換/使用 金額 totalMaleCount | int | 男性 兌換/使用 張數 totalFemaleCount | int | 女性 兌換/使用 張數 totalMaleRate | double | 男性 兌換/使用 率 totalFemaleRate | double | 女性 兌換/使用 率 details | json array | 年齡統計 json array ##### Response-票券統計(平台管理員)-usedInfo(票券使用分析json) 欄位 | 型態 | 說明 --- | --- | --- totalUsedRate | double | 總使用率, 使用率=已使用量/已兌換量 totalCount | int | 總 兌換/使用 張數 totalAmount | int | 總 兌換/使用 金額 totalMaleCount | int | 男性 兌換/使用 張數 totalFemaleCount | int | 女性 兌換/使用 張數 totalMaleRate | double | 男性 兌換/使用 率 totalFemaleRate | double | 女性 兌換/使用 率 details | json array | 年齡統計 json array ##### Response-票券統計(平台管理員)-details(json array of redeemInfo, usedInfo) 欄位 | 型態 | 說明 --- | --- | --- ageLevel | string | 年齡level label | string | 年齡區間顯示(標X軸) maleCount | int | 男性人數 femaleCount | int | 女性人數 ##### Response-票券統計(平台管理員)-reachInfo(票券曝光分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總曝光人數 totalTimes | int | 總曝光人次 totalMaleCount | int | 總男性曝光人數 totalFemaleCount | int | 總女性曝光人數 totalMaleTimes | int | 總男性曝光人次 totalFemaleTimes | int | 總女性曝光人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 details | json array | 年齡統計 json array ##### Response-票券統計(平台管理員)-clickInfo(票券點擊分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總點擊人數 totalTimes | int | 總點擊人次 totalMaleCount | int | 總男性點擊人數 totalFemaleCount | int | 總女性點擊人數 totalMaleTimes | int | 總男性點擊人次 totalFemaleTimes | int | 總女性點擊人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 clickRate | double | 點擊率, 點擊率 = 點擊人數/曝光人數 details | json array | 年齡統計 json array ##### Response-票券統計(平台管理員)-details(json array of reachInfo, clickInfo) 欄位 | 型態 | 說明 --- | --- | --- ageLevel | string | 年齡level label | string | 年齡區間顯示(標X軸) maleCount | int | 男性人數 femaleCount | int | 女性人數 maleTimes | int | 男性人次 femaleTimes | int | 女性人次 ```javascript { "httpCode": 200, "result": { "data": { "summaryInfo": { "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "tenantName": "緯緯醫學", "deposit": 11000000, "withdraw": 250020, "quota": 10749980, "totalVolume": 588, "totalPoints": 250020, "totalAmount": 8334, "totalUnRedeemCount": 577, "totalUnRedeemPoints": 249450, "totalRedeemCount": 11, "totalRedeemPoints": 570, "totalRedeemAmount": 19, "totalUsedCount": 4, "totalUsedAmount": 6, "quotaAvailRate": 97.7, "redeemRate": 1.9, "usedRate": 36.4, "clickRate": 50 }, "redeemInfo": { "totalRedeemCount": 11, "totalRedeemAmount": 19, "totalRedeemRate": 0, "totalCount": 11, "totalAmount": 19, "totalMaleCount": 11, "totalFemaleCount": 0, "totalMaleRate": 100, "totalFemaleRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 5, "femaleCount": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 6, "femaleCount": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0 } ] }, "usedInfo": { "totalUsedRate": 36.4, "totalCount": 4, "totalAmount": 6, "totalMaleCount": 4, "totalFemaleCount": 0, "totalMaleRate": 100, "totalFemaleRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 2, "femaleCount": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 2, "femaleCount": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0 } ] }, "reachInfo": { "totalCount": 2, "totalTimes": 26, "totalMaleCount": 2, "totalFemaleCount": 0, "totalMaleTimes": 26, "totalFemaleTimes": 0, "totalMaleCountRate": 100, "totalFemaleCountRate": 0, "totalMaleTimesRate": 100, "totalFemaleTimesRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 1, "femaleCount": 0, "maleTimes": 5, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 1, "femaleCount": 0, "maleTimes": 21, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] }, "clickInfo": { "totalCount": 1, "totalTimes": 3, "totalMaleCount": 1, "totalFemaleCount": 0, "totalMaleTimes": 3, "totalFemaleTimes": 0, "totalMaleCountRate": 100, "totalFemaleCountRate": 0, "totalMaleTimesRate": 100, "totalFemaleTimesRate": 0, "clickRate": 50, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 1, "femaleCount": 0, "maleTimes": 3, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] } } } } ``` ## 取得票券管理Summary ```url POST /voucher-mgmt/voucher/summary ``` #### Request-取得票券管理Summary 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | N | | 租戶id, 由UserToken取得帶入 ```javascript ``` #### Response-取得票券管理Summary 欄位 | 型態 | 說明 --- | --- | --- quota | long | 票券可使用額度-總計可使用(點) totalVolume | long | 已發行票券-票券張數 totalPoints | long | 已發行票券-票券點數 totalAmount | double | 已發行票券-票券金額 totalUnRedeemCount | long | 尚未兌換票券-票券張數 totalUnRedeemPoints | long | 尚未兌換票券-票券點數 totalRedeemCount | long | 已兌換票券-票券張數 totalRedeemPoints | long | 已兌換票券-票券點數 totalRedeemAmount | double | 已兌換票券-票券金額 totalUsedCount | long | 已使用票券-票券張數 totalUsedAmount | double | 已使用票券-總計已兌換金額 quotaAvailRate | double | 票券可使用額度-可用量 redeemRate | double | 已兌換票券-兌換率 usedRate | double | 已使用票券-使用率 ```javascript { "httpCode": 200, "result": { "data": { "deposit": 11000000, "withdraw": 250020, "quota": 10749980, "totalVolume": 588, "totalPoints": 250020, "totalAmount": 8334.00, "totalUnRedeemCount": 577, "totalUnRedeemPoints": 249450, "totalRedeemCount": 11, "totalRedeemPoints": 570, "totalRedeemAmount": 19.00, "totalUsedCount": 4, "totalUsedAmount": 6, "quotaAvailRate": 97.7, "redeemRate": 1.9, "usedRate": 36.4 } } } ``` ## 票券管理列表 ```url POST /voucher-mgmt/voucher/list ``` #### Request-票券管理列表 ##### Request-票券管理列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | | | 租戶id,會有userToken自動帶入 queryDateType | string | | | 查詢日期類別, ID:建立日期, OD:上架日期, RS:兌換日期(起), RE:兌換日期(迄), US:有效日期(起), UE:有效日期(迄) startDate | string | | | 查詢起日, 格式為YYYY-MM-DD endDate | string | | | 查詢迄日, 格式為YYYY-MM-DD voucherType | string | | | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 status | string | | | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 name | string | | | 關鍵字, 查詢票券標題 ##### Request-票券管理列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-票券管理列表-sorter(排序json), 預設是用更新時間降序排列 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | voucherNo | 排序欄位,可排序欄位有 voucherNo, title, targetType, voucherType, volume, price, redeem_points, redeemCount, redeemStartDate, redeemEndDate, useStartDate, useEndDate, status, updateTime order | string | | desc | 升序或降序 ```javascript { "query": { "tenantId": null, "queryDateType": null, "startDate": null, "endDate": null, "voucherType": null, "status": null, "name": null } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "updateTime", "order": "desc" } } ``` #### Response-票券管理列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 targetType | string | 使用對象, ALL:全平台, MEMBER:租戶會員 price | double | 票券金額 volume | int | 票券發行數量 redeemStartDate | timestamp | 兌換日期(起) redeemEndDate | timestamp | 兌換日期(迄) useStartDate | timestamp | 使用日期(起) useEndDate | timestamp | 使用日期(迄) status | string | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 redeemPoints | int | 兌換點數(張) redeemCount | int | 已兌換張數 thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 useType | string | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 issueDate | timestamp | 建立日期 onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) ```javascript { "httpCode": 200, "result": { "data": [ { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "voucherNo": "M000010120220222001", "voucherType": "01", "useType": "SELF", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "targetType": "ALL", "price": 5.00, "volume": 1000, "issueDate": 1645459200000, "redeemStartDate": 1645545600000, "redeemEndDate": 1645977600000, "useStartDate": 1645545600000, "useEndDate": 1648656000000, "onStartDate": 1645545600000, "onEndDate": 1646409600000, "status": "ON", "redeemPoints": 150, "updateTime": 1645605720038, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "thumbnailUrl": "http://content-service/swift/v1/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "redeemCount": 1 } ], "pagination": { "current": 1, "pageSize": 10, "total": 1 }, "sorter": { "field": "voucherNo", "order": "desc" }, "total": 1 } } ``` ## 取得票券管理明細 ```url POST /voucher-mgmt/voucher/info ``` #### Request-取得票券管理明細 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id ```javascript { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c" } ``` #### Error-取得票券管理明細 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 #### Response-取得票券管理明細 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 targetType | string | 使用對象, ALL:全平台, MEMBER:租戶會員 price | double | 票券金額 volume | int | 票券發行數量 redeemStartDate | timestamp | 兌換日期(起) redeemEndDate | timestamp | 兌換日期(迄) useStartDate | timestamp | 使用日期(起) useEndDate | timestamp | 使用日期(迄) onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) redeemLimit | int | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | 使用說明 notice | string | 注意事項 status | string | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 redeemPoints | int | 兌換點數(張) thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 useType | string | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 issueDate | timestamp | 建立日期 ```javascript { "httpCode": 200, "result": { "data": { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherNo": "M000010120220222001", "voucherType": "01", "useType": "SELF", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "targetType": "ALL", "price": 5, "volume": 1000, "issueDate": 1645459200000, "redeemStartDate": 1645545600000, "redeemEndDate": 1645977600000, "useStartDate": 1645545600000, "useEndDate": 1648656000000, "onStartDate": 1645545600000, "onEndDate": 1646409600000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "status": "ON", "redeemPoints": 150, "updateTime": 1645605720038, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "thumbnailUrl": "http://content-service/swift/v1/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } ``` ## 取得上傳網址 ```url POST /voucher-mgmt/voucher/get-upload-url ``` * 新增/編輯票券時用來上傳縮圖 #### Request-取得上傳網址 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- isMultipart | boolean | Y | false | 是否使用分段上傳 isThumbnail | boolean | Y | false | 上傳的是否為縮圖, 建議帶true fileName | String | Y | | 檔名，不包含副檔名，限制最多50字 fileType | String | Y | | 副檔名, 限制最多10字 totalPart | int | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 總分塊數量，不可小於2 parts | Array [...part] | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | part 資訊 ##### Request-取得上傳網址-part(Object) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- chunkSize | int | Y | | 該 chunk 的大小, bytes md5 | string | Y | | 該 part 的 md5 part | int | Y | | part number, 第幾塊 chunk ```javascript // 單檔 { "isMultipart": false, "isThumbnail": true, "fileName": "cofee_time", "fileType": "png" } // 分塊上傳 { "isMultipart": true, "isThumbnail": false, "fileName": "giphy (7)", "fileType": "mp4", "totalPart": 2, "parts": [ { "chunkSize": 5242880, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 1 }, { "chunkSize": 3145728, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 2 } ] } ``` #### Error-取得上傳網址 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.UPLOAD_FILE_TYPE_NOT_ALLOWED | 上傳的檔案類型不允許 #### Response-取得上傳網址 欄位 | 型態 | 說明 --- | --- | --- objectKey | string | storage 中的 objectKey, **unique** uploadId | string | 識別該次上傳的 uploadId fileName | string | 名稱 fileType | string | 副檔名 url | string | 單檔上傳的時候，才會回傳該 url, 時效 3600 秒 parts | [...part] | multipart上傳各part的url ##### Response-取得上傳網址-part(Object) 欄位 | 型態 | 說明 --- | --- | --- chunkSize | int | 該 chunk 的大小, bytes md5 | string | 該 part 的 md5 part | int | part number, 第幾塊 chunk url | string | 可上傳的 url, 時效 3600 秒 ```javascript // 單檔 { "httpCode": 200, "result": { "data": { "objectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "uploadId": "dd9177f7-3ca8-4296-b587-6d6334643eea", "fileName": "cofee_time", "fileType": "png", "url": "http://swift-storage/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } // 分塊上傳 { "httpCode": 200, "result": { "data": { "objectKey": "voucher/f76adf26-1e22-4b18-980d-b9a68efc5171.mp4", "uploadId": "53fde368-43d9-455f-a610-62091fc30be6", "fileName": "giphy (7)", "fileType": "mp4", "parts": [ { "chunkSize": 5242880, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 1, "url": "http://192.168.100.239:12345/v1/AUTH_test/kmuh_segments/voucher%2Ff76adf26-1e22-4b18-980d-b9a68efc5171.mp4%2F1?temp_url_sig=796c52b00f75b62be658533b2fadbc7f14381e36&temp_url_expires=1554263771" }, { "chunkSize": 3145728, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 2, "url": "http://192.168.100.239:12345/v1/AUTH_test/kmuh_segments/voucher%2Ff76adf26-1e22-4b18-980d-b9a68efc5171.mp4%2F2?temp_url_sig=ad71de81dfbcd94bce4a091f2630c6f1373ff3cd&temp_url_expires=1554263771" } ] } } } ``` ## 新增票券 ```url POST /voucher-mgmt/voucher/add ``` * 新增票券時，由後端自動產生票券號碼, 編碼規則如下: 機構ID(隨機1碼英文字母+5碼流水號)＋票券種類ID(2碼流水號)+票券發行日期YYYYMMDD+發行3碼流水號，共計19碼 ex: M000010120220217001 * 票券金額需檢查 > 0 * 票券發行數量需檢查 > 0, 及 <= 99999 * 票券中的不同「日期」欄位需要檢查及判斷的邏輯 * 「兌換日期」：為允許用戶使用點數兌換該票券的日期。 - 檢查條件1：「兌換日期」的期間需 早於或等於「使用日期」的期間，且不可 晚於「使用日期」的截止日。 * 「使用日期」：用於檢查「票券核銷」期間。 - 檢查條件1：「使用日期」的前間可 晚於或等於「兌換日期」的期間，但不可 早於「兌換日期」的起始日。 - 檢查條件2： 允許已被兌換「已下架」或「已過期」狀態的票券於「使用日期」期間內進行核銷。 * 「上下架日期」：用於顯示於前端APP商品列表的判斷。 - 檢查條件1：「上架日期」需 早於或等於「兌換日期」的截止日，且不可 晚於「兌換日期」的截止日。 - 檢查條件2：「上架中」票券的「兌換日期」已到期，則不允許用點數進行兌換且狀態為「上架中」。 - 檢查條件3：「上架中」票券的「使用日期」已到期，則不允許票券核銷且狀態須變更為「已過期」。 * 「上下架日期」可由管理者自行決定上架及下架日期，且下架後不得再上架(可使用「複製」新上架票券)。 * 票券的總計兌換點數計算方式為: 票券點數兌換基準(預設為30點折抵1元) x 票券金額 x 票券發行數量 #### Request-新增票券 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- title | string | Y | | 票券標題, 限制最多50字 thumbnailObjectKey | string | | | 縮圖objectKey, 先取得縮圖上傳網址並上傳成功，取其 objectKey。 targetType | string | Y | | 兌換對象, ALL:全平台, MEMBER:租戶會員 voucherType | string | Y | | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動, 06: 折價卷 price | double | Y | | 票券金額, 需 > 0 volume | int | Y | | 票券發行數量, 需 > 0>0, 及 <= 99999 redeemStartDate | timestamp | Y | | 票券兌換日期(起) redeemEndDate | timestamp | Y | | 票券兌換日期(迄) useStartDate | timestamp | Y | | 票券使用日期(起) useEndDate | timestamp | Y | | 票券使用日期(迄) onStartDate | timestamp | Y | | 票券上架日期(起) onEndDate | timestamp | Y | | 票券上架日期(迄) redeemLimit | int | Y | | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | | | 使用說明,最多500字 notice | string | | | 注意事項,最多500字 isThumbnailMultipart | boolean | N | | 縮圖上傳時是否分塊上傳，預設為 false thumbnailTotalPart | int | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 縮圖上傳的總分塊數量，不可小於2 thumbnailUploadId | string | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 從 /voucher-mgmt/voucher/get-upload-url 取得的 uploadId useType | string | Y | | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 couponList | json array | **N** (voucherType!='06')<br>**Y** (voucherType=='06') | | 折價卷列表, 列表數量必須和volume相同 ##### Request-新增票券-couponList 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- title | string | Y | | 折價券標題, 限制最多500字 description | string | Y | | 票券標題, 限制最多1000字 url | string | Y | | 票券標題, 限制最多2000字 ```javascript // voucherType != "06" { "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "targetType": "ALL", "voucherType": "01", "useType": "SELF", "price": 45, "volume": 1000, "redeemStartDate": 1645574400000, "redeemEndDate": 1646006400000, "useStartDate": 1645574400000, "useEndDate": 1648684800000, "onStartDate": 1645574400000, "onEndDate": 1646438400000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "isThumbnailMultipart": false, "thumbnailTotalPart": null, "thumbnailUploadId": null } // voucherType == "06" { "voucherType": "06", "useType": "SELF", "productId": "", "title": "超商折價卷25元", "price": "1", "redeemStartDate": 1667354394025, "redeemEndDate": 1667872794025, "useStartDate": 1667354394026, "useEndDate": 1667872794026, "onStartDate": 1667354394029, "onEndDate": 1667872794029, "redeemLimitValue": "1", "targetType": "MEMBER", "quota": 49790, "volume": "1", "redeemLimit": 1, "description": "使用期限內可於全省門市兌換", "notice": "使用期限內可於全省門市兌換", "thumbnailObjectKey": "voucher/08218348-f5e4-4609-8478-646d05584677.jpg", "objectKey": "voucher/08218348-f5e4-4609-8478-646d05584677.jpg", "couponList": [ { "title": "折扣碼優惠券", "description": "感謝您參加Health 365平台舉辦的活動，以下是您的贈品，7-ELEVEN 25元即享券，請於2022.12.31前開啟下方網址取得完整券樣(密碼5020)至櫃台掃碼兌換，或至ibon機台 好康/紅利->好康活動->i禮贈->輸入序號SET4PUUCH5V->持單結帳。", "url": "http://t.txp.tw/v/APyG3ivQ43" } ] } ``` #### Error-新增票券 httpCode | 錯誤碼 | 說明 --- | --- | --- 422 | SERVICE_ERROR.VOUCHER_VENDOR_NOT_EXIST | 票券發行機構不存在 422 | SERVICE_ERROR.VOUCHER_VENDOR_NOT_ADD_QUOTA | 發行票券時,機構尚未設定額度 422 | SERVICE_ERROR.VOUCHER_INSUFFICIENT_QUOTA | 發行票券時,點數餘額不足 422 | SERVICE_ERROR.VOUCHER_QUOTA_NOT_BALANCE | 發行票券時,帳目計算不平等 422 | SERVICE_ERROR.VOUCHER_USE_TYPE_NOT_ALLOWED | 核銷方式不允許 422 | SERVICE_ERROR.VOUCHER_NEED_COUPON_LIST | 票劵需綁定折價卷 422 | SERVICE_ERROR.VOUCHER_COUPON_REDEEM_NOT_MATCH | 折價卷數量與兌換數量不相同 422 | SERVICE_ERROR.VOUCHER_NEED_PRODUCT_ID | 票劵需綁定商品ID #### Response-新增票券 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 targetType | string | 使用對象, ALL:全平台, MEMBER:租戶會員 price | double | 票券金額 volume | int | 票券發行數量 redeemStartDate | timestamp | 兌換日期(起) redeemEndDate | timestamp | 兌換日期(迄) useStartDate | timestamp | 使用日期(起) useEndDate | timestamp | 使用日期(迄) onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) redeemLimit | int | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | 使用說明 notice | string | 注意事項 status | string | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 redeemPoints | int | 兌換點數(張) thumbnailObjectKey | string | storage中的縮圖objectKey updateTime | timestamp | 最後更新時間 useType | string | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 issueDate | timestamp | 建立日期 ```javascript { "httpCode": 200, "result": { "data": { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherNo": "M000010120220222001", "voucherType": "01", "useType": "SELF", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "targetType": "ALL", "price": 45, "volume": 1000, "issueDate": 1646755200000, "redeemStartDate": 1646064000000, "redeemEndDate": 1646496000000, "useStartDate": 1646064000000, "useEndDate": 1647014400000, "onStartDate": 1646064000000, "onEndDate": 1647014400000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "status": "NONE", "redeemPoints": 1350, "updateTime": 1645530937599, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } ``` ## 編輯票券 * 只允許未上架票券或上架後再切換成下架且未到期的票券可以編輯 * 已下架(未結束)的票券, 開放可以編輯票券名稱, 票券圖檔, 兌換期限, 使用期限, 使用說明, 注意事項, 上下架日期等欄位 ```url POST /voucher-mgmt/voucher/update ``` #### Request-編輯票券 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id title | string | Y | | 票券標題, 限制最多50字 thumbnailObjectKey | string | | | 縮圖objectKey, 先取得縮圖上傳網址並上傳成功，取其 objectKey。 targetType | string | Y | | 兌換對象, ALL:全平台, MEMBER:租戶會員 voucherType | string | Y | | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動, 06: 折價卷 price | double | Y | | 票券金額, 需 > 0 volume | int | Y | | 票券發行數量, 需 > 0 redeemStartDate | timestamp | Y | | 票券兌換日期(起) redeemEndDate | timestamp | Y | | 票券兌換日期(迄) useStartDate | timestamp | Y | | 票券使用日期(起) useEndDate | timestamp | Y | | 票券使用日期(迄) onStartDate | timestamp | Y | | 票券上架日期(起) onEndDate | timestamp | Y | | 票券上架日期(迄) redeemLimit | int | Y | | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | | | 使用說明,最多500字 notice | string | | | 注意事項,最多500字 isThumbnailMultipart | boolean | N | | 縮圖上傳時是否分塊上傳，預設為 false thumbnailTotalPart | int | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 縮圖上傳的總分塊數量，不可小於2 thumbnailUploadId | string | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 從 /voucher-mgmt/voucher/get-upload-url 取得的 uploadId useType | string | Y | | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 couponList | json array | **N** (voucherType!='06')<br>**Y** (voucherType=='06') | | 折價卷列表, 列表數量必須和volume相同 ##### Request-編輯票券-couponList 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- title | string | Y | | 折價券標題, 限制最多500字 description | string | Y | | 票券標題, 限制最多1000字 url | string | Y | | 票券標題, 限制最多2000字 ```javascript { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "targetType": "ALL", "voucherType": "01", "useType": "SELF", "price": 5, "volume": 1000, "redeemStartDate": 1645545600000, "redeemEndDate": 1645977600000, "useStartDate": 1645545600000, "useEndDate": 1648656000000, "onStartDate": 1645545600000, "onEndDate": 1646409600000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "isThumbnailMultipart": false, "thumbnailTotalPart": null, "thumbnailUploadId": null } ``` #### Error-編輯票券 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 422 | SERVICE_ERROR.VOUCHER_UPDATE_NOT_NONE_STATUS | 不可修改已上架或下架的票券 422 | SERVICE_ERROR.VOUCHER_INSUFFICIENT_QUOTA | 發行票券時,點數餘額不足 422 | SERVICE_ERROR.VOUCHER_QUOTA_NOT_BALANCE | 發行票券時,帳目計算不平等 422 | SERVICE_ERROR.VOUCHER_NEED_COUPON_LIST | 票劵需綁定折價卷 422 | SERVICE_ERROR.VOUCHER_COUPON_REDEEM_NOT_MATCH | 折價卷數量與兌換數量不相同 422 | SERVICE_ERROR.VOUCHER_NEED_PRODUCT_ID | 票劵需綁定商品ID 422 | SERVICE_ERROR.VOUCHER_UPDATE_OFF_VOUCHER_NOT_ALLOWED | 不允許修改已下架(已結束)的票券 #### Response-編輯票券 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 targetType | string | 使用對象, ALL:全平台, MEMBER:租戶會員 price | double | 票券金額 volume | int | 票券發行數量 redeemStartDate | timestamp | 兌換日期(起) redeemEndDate | timestamp | 兌換日期(迄) useStartDate | timestamp | 使用日期(起) useEndDate | timestamp | 使用日期(迄) onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) redeemLimit | int | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | 使用說明 notice | string | 注意事項 status | string | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 redeemPoints | int | 兌換點數(張) thumbnailObjectKey | string | storage中的縮圖objectKey updateTime | timestamp | 最後更新時間 useType | string | 核銷方式, SELF:自主核銷, MERCHANT:商城折抵 issueDate | timestamp | 建立日期 onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) ```javascript { "httpCode": 200, "result": { "data": { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherNo": "M000010120220222001", "voucherType": "01", "useType": "SELF", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "targetType": "ALL", "price": 5, "volume": 1000, "issueDate": 1646755200000, "redeemStartDate": 1646064000000, "redeemEndDate": 1646496000000, "useStartDate": 1646064000000, "useEndDate": 1647014400000, "onStartDate": 1646064000000, "onEndDate": 1647014400000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "status": "NONE", "redeemPoints": 150, "updateTime": 1645605720038, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } ``` ## 編輯票券上下架狀態 ```url POST /voucher-mgmt/voucher/update-status ``` * 只允許未上架票券變更為上架, 或已上架票券變更為下架 * 已下架未到期的票券可再切換為上架 * 目前票券上架改為手動上架, 排程只執行自動下架的部分 #### Request-編輯票券上下架狀態 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id status | string | Y | | 票券發佈狀態, NONE:未上架, ON:上架, OFF:下架 ```javascript { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "status": "OFF" } ``` #### Error-編輯票券上下架狀態 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 422 | SERVICE_ERROR.VOUCHER_UPDATE_STATUS_NOT_ALLOWED | 票券不允許變更狀態 #### Response-編輯票券上下架狀態 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 targetType | string | 使用對象, ALL:全平台, MEMBER:租戶會員 price | double | 票券金額 volume | int | 票券發行數量 redeemStartDate | timestamp | 兌換日期(起) redeemEndDate | timestamp | 兌換日期(迄) useStartDate | timestamp | 使用日期(起) useEndDate | timestamp | 使用日期(迄) onStartDate | timestamp | 上架日期(起) onEndDate | timestamp | 上架日期(迄) redeemLimit | int | 兌換限制,0表示無限制,>0表示一人限兌換張數 description | string | 使用說明 notice | string | 注意事項 status | string | 票券狀態, NONE:未上架, ON:上架, OFF: 已下架 redeemPoints | int | 兌換點數(張) thumbnailObjectKey | string | storage中的縮圖objectKey updateTime | timestamp | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherNo": "M000010120220222001", "voucherType": "01", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "targetType": "ALL", "price": 5, "volume": 1000, "redeemStartDate": 1645545600000, "redeemEndDate": 1645977600000, "useStartDate": 1645545600000, "useEndDate": 1648656000000, "redeemLimit": 1, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "status": "NONE", "redeemPoints": 150, "updateTime": 1645605720038, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } ``` ## 刪除票券 ```url POST /voucher-mgmt/voucher/delete ``` * 未上架票券才允許刪除 #### Request-刪除票券 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id ```javascript { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c" } ``` #### Error-刪除票券 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 422 | SERVICE_ERROR.VOUCHER_DELETE_NOT_ALLOWED | 不允許刪除已上架或下架的票券 422 | SERVICE_ERROR.VOUCHER_QUOTA_NOT_BALANCE | 刪除票券回補扣除點數時,帳目計算不平等 #### Response-刪除票券 欄位 | 型態 | 說明 --- | --- | --- count | int | 刪除筆數, > 0 表示成功刪除 ```javascript { "httpCode": 200, "result": { "data": { "count": 1 } } } ``` ## 票券統計(租戶管理員) ```url POST /voucher-mgmt/voucher/statistics ``` * 票券統計API, 平台及租戶管理員是用叫同一支API,但傳入參數不同, 回傳的結果, 平台管理員會多回傳一個summaryInfo #### Request-票券統計(租戶管理員) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- voucherId | string | Y | | 票券id ```javascript { "voucherId": "f14d33c4-38b1-4611-a6d1-11a1b202305d" } ``` #### Response-票券統計(租戶管理員) 欄位 | 型態 | 說明 --- | --- | --- redeemInfo | json | 票券兌換分析json usedInfo | json | 票券使用分析json reachInfo | json | 票券曝光分析json clickInfo | json | 票券點擊分析json #### Response-票券統計(租戶管理員)-redeemInfo(票券兌換分析json) 欄位 | 型態 | 說明 --- | --- | --- totalRedeemCount | long | 已兌換量-票券張數 totalRedeemAmount | double | 總計已兌換金額 totalRedeemRate | double | 總兌換率, 兌換率=已兌換量/票券發行數量 totalCount | int | 總 兌換/使用 張數 totalAmount | int | 總 兌換/使用 金額 totalMaleCount | int | 男性 兌換/使用 張數 totalFemaleCount | int | 女性 兌換/使用 張數 totalMaleRate | double | 男性 兌換/使用 率 totalFemaleRate | double | 女性 兌換/使用 率 details | json array | 年齡統計 json array #### Response-票券統計(租戶管理員)-usedInfo(票券使用分析json) 欄位 | 型態 | 說明 --- | --- | --- totalUsedRate | double | 總使用率, 使用率=已使用量/已兌換量 totalCount | int | 總 兌換/使用 張數 totalAmount | int | 總 兌換/使用 金額 totalMaleCount | int | 男性 兌換/使用 張數 totalFemaleCount | int | 女性 兌換/使用 張數 totalMaleRate | double | 男性 兌換/使用 率 totalFemaleRate | double | 女性 兌換/使用 率 details | json array | 年齡統計 json array #### Response-票券統計(租戶管理員)-details(json array of redeemInfo, usedInfo) 欄位 | 型態 | 說明 --- | --- | --- ageLevel | string | 年齡level label | string | 年齡區間顯示(標X軸) maleCount | int | 男性人數 femaleCount | int | 女性人數 #### Response-票券統計(租戶管理員)-reachInfo(票券曝光分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總曝光人數 totalTimes | int | 總曝光人次 totalMaleCount | int | 總男性曝光人數 totalFemaleCount | int | 總女性曝光人數 totalMaleTimes | int | 總男性曝光人次 totalFemaleTimes | int | 總女性曝光人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 details | json array | 年齡統計 json array #### Response-票券統計(租戶管理員)-clickInfo(票券點擊分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總點擊人數 totalTimes | int | 總點擊人次 totalMaleCount | int | 總男性點擊人數 totalFemaleCount | int | 總女性點擊人數 totalMaleTimes | int | 總男性點擊人次 totalFemaleTimes | int | 總女性點擊人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 clickRate | double | 點擊率, 點擊率 = 點擊人數/曝光人數 details | json array | 年齡統計 json array #### Response-票券統計(租戶管理員)-details(json array of reachInfo, clickInfo) 欄位 | 型態 | 說明 --- | --- | --- ageLevel | string | 年齡level label | string | 年齡區間顯示(標X軸) maleCount | int | 男性人數 femaleCount | int | 女性人數 maleTimes | int | 男性人次 femaleTimes | int | 女性人次 ```javascript { "httpCode": 200, "result": { "data": { "redeemInfo": { "totalRedeemCount": 3, "totalRedeemAmount": 3, "totalRedeemRate": 0, "totalCount": 3, "totalAmount": 3, "totalMaleCount": 3, "totalFemaleCount": 0, "totalMaleRate": 100, "totalFemaleRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 1, "femaleCount": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 2, "femaleCount": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0 } ] }, "usedInfo": { "totalUsedRate": 0, "totalCount": 0, "totalAmount": 0, "totalMaleCount": 0, "totalFemaleCount": 0, "totalMaleRate": 0, "totalFemaleRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0 } ] }, "reachInfo": { "totalCount": 1, "totalTimes": 3, "totalMaleCount": 1, "totalFemaleCount": 0, "totalMaleTimes": 3, "totalFemaleTimes": 0, "totalMaleCountRate": 100, "totalFemaleCountRate": 0, "totalMaleTimesRate": 100, "totalFemaleTimesRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 1, "femaleCount": 0, "maleTimes": 3, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] }, "clickInfo": { "totalCount": 0, "totalTimes": 0, "totalMaleCount": 0, "totalFemaleCount": 0, "totalMaleTimes": 0, "totalFemaleTimes": 0, "totalMaleCountRate": 0, "totalFemaleCountRate": 0, "totalMaleTimesRate": 0, "totalFemaleTimesRate": 0, "clickRate": 0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] } } } } ``` ## 匯入折扣碼優惠劵excel 匯入資料格式: [參見附檔](https://nssi2.atlassian.net/browse/HV-2157) ```url POST /voucher-mgmt/voucher/parse-coupon-list ``` * 解析折扣碼優惠excel, 會回傳折扣碼清單, 票劵的兌換數量必須和清單數量一致. #### Request-匯入折扣碼優惠劵excel * request body format: form-data | 欄位 | 型態 | 必填 | 預設 | 說明 | |---|---|---|---|---| | file | File | Y | | 匯入的excel檔案 | #### Response-匯入折扣碼優惠劵excel 欄位 | 型態 | 說明 --- | --- | --- | totalCount | int | 匯入處理筆數 | | successCount | int | 匯入成功筆數 | | failCount | int | 匯入失敗筆數 | | failuresId | string | 匯入失敗檔案下載id | | couponList | json array | 折價劵清單 | ##### Response-匯入折扣碼優惠劵excel-couponList(折價卷json) 欄位 | 型態 | 說明 --- | --- | --- title | String | 折價劵標題 description | String | 折價劵描述 url | String | 折價劵兌換url ```javascript { "httpCode": 200, "result": { "data": { "totalCount": 2, "successCount": 1, "failCount": 1, "failuresId": "f14d33c4-38b1-4611-a6d1-11a1b202305d" "couponList": [ { "title": "折扣碼優惠券", "description": "感謝您參加Health 365平台舉辦的活動，以下是您的贈品，7-ELEVEN 25元即享券，請於2022.12.31前開啟下方網址取得完整券樣(密碼5020)至櫃台掃碼兌換，或至ibon機台 好康/紅利->好康活動->i禮贈->輸入序號SET4PUUCH5V->持單結帳。", "url": "http://t.txp.tw/v/APyG3ivQ43" } ] } } } ``` ## 下載健檢錯誤資料檔 ```url= POST /voucher-mgmt/coupon/export-failures ``` #### Request-下載健檢錯誤資料檔 | 欄位 | 型態 | 必填 | 預設 | 說明 | |---|---|---|---|---| | failuresId | string | | 匯入失敗檔案下載id | ```javascript { "failuresId": "18982a76-7062-44cd-a27e-d132da550b52" } ``` #### Response-下載健檢錯誤資料檔 * httpCode 400 - [errorMsg](https://gitlab.devpack.cc/Wei_Chang/wicc-kmuh/wikis/Type-Definition#service_error) | errorMsg | desc | | --------- |-------- | |RESOURCE_NOT_EXISTS| 資料檔不存在 | * httpCode 200 -Download file ``` File name: 檢驗檢查錯誤資料檔.xlsx ``` ## 我的票券摘要 ```url GET /voucher/my-summary ``` * 只會列出尚未超過使用期限的未使用票券數目 #### Request-我的票券摘要 #### Response-我的票券摘要 欄位 | 型態 | 說明 --- | --- | --- myVoucherCount | int | 我的票券數量 ```javascript { "httpCode": 200, "result": { "data": { "myVoucherCount": 1 } } } ``` ## 取得票券列表 ```url POST /voucher/list ``` #### Request-取得票券列表 ##### Request-取得票券列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- voucherType | string | N | | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 <BR/>未填則查詢全部 ##### Request-取得票券列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-取得票券列表-sorter(排序json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | onStartDate | 排序欄位,可排序欄位有onStartDate order | string | | desc | 升序或降序 ```javascript { "query": { "voucherType": null } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "onStartDate", "order": "desc" } } ``` #### Response-取得票券列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id voucherNo | string | 票券號碼 title | string | 票券標題 redeemPoints | int | 兌換票券所需點數 thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 volume | int | 票券發行數量 stocks | int | 庫存量 safetyStock | int | 安全庫存量 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "voucherNo": "M000010120220222001", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "redeemPoints": 1350, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "thumbnailUrl": "http://content-service/swift/v1/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "volume": 10, "stocks": 8, "safetyStock": 3 } ], "pagination": { "current": 1, "pageSize": 10, "total": 1 }, "sorter": { "field": "onStartDate", "order": "desc" }, "total": 1 } } ``` ## 取得票券明細 ```url POST /voucher/info ``` * App User call 此API時, 已包含票券點擊計算, 不需再call /voucher/click API #### Request-取得票券明細 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id ```javascript { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c" } ``` #### Error-取得票券明細 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 #### Response-取得票券明細 欄位 | 型態 | 說明 --- | --- | --- id | string | 票券id tenantId | string | 租戶id vendorName | string | 租戶名稱 voucherNo | string | 票券號碼 voucherType | string | 票券類別, 01:0元換購, 02:全平台優惠券, 03:商品優惠, 04:方案優惠, 05:限量活動 title | string | 票券標題 price | double | 折抵金額 redeemStartDate | timestamp | 票券兌換開始日期 redeemEndDate | timestamp | 票券兌換結束日期 useStartDate | timestamp | 票券使用開始日期 useEndDate | timestamp | 票券使用結束日期 description | string | 使用說明 notice | string | 注意事項 status | string | 票券狀態, NONE:未上架, ON:已上架, OFF: 已下架 redeemPoints | int | 兌換票券所需點數 thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 volume | int | 票券發行數量 stocks | int | 庫存量 safetyStock | int | 安全庫存量 ```javascript { "httpCode": 200, "result": { "data": { "id": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "vendorName": "緯緯醫學", "voucherNo": "M000010120220222001", "voucherType": "01", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "price": 45.00, "redeemStartDate": 1645545600000, "redeemEndDate": 1645977600000, "useStartDate": 1645545600000, "useEndDate": 1648656000000, "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "status": "ON", "redeemPoints": 1350, "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "thumbnailUrl": "http://content-service/swift/v1/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "volume": 10, "stocks": 8, "safetyStock": 3 } } } ``` ## 兌換票券 ```url POST /voucher/redeem ``` #### Request-兌換票券 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- voucherId | string | Y | | 票券id ```javascript { "voucherId": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c" } ``` #### Error-兌換票券 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 422 | SERVICE_ERROR.VOUCHER_REDEEM_NOT_ON_STATUS | 不可兌換非上架票券 422 | SERVICE_ERROR.VOUCHER_REDEEM_NOT_IN_REDEEM_DATE | 非兌換期間 422 | SERVICE_ERROR.VOUCHER_REDEEM_OVER_VOLUME | 已達兌換張數 422 | SERVICE_ERROR.VOUCHER_REDEEM_OVER_LIMIT | 已達兌換限制 422 | SERVICE_ERROR.VOUCHER_REDEEM_INSUFFICIENT_POINTS | 兌換點數不足 #### Response-兌換票券 欄位 | 型態 | 說明 --- | --- | --- id | string | 我的票券id householdMemberId | string | householdMemberId voucherId | string | 票券id seq | int | 此票券兌換的流水號 userVoucherNo | string | 我的票券號碼 redeemTime | timestamp | 兌換時間 redeemPoints | int | 兌換票券所需點數 status | string | 我的票券狀態, VALID:有效, USED:已使用 ```javascript { "httpCode": 200, "result": { "data": { "id": "e78f0201-3e0f-4ec6-b6f6-dfa4ec23d07c", "householdMemberId": "8a9e980a-c612-4f87-af07-a97a5f0fbed5", "voucherId": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "seq": 1, "userVoucherNo": "M00001012022022200100001", "redeemTime": 1645605920912, "redeemPoints": 150, "status": "VALID", "createTime": 1645605920866, "updateTime": 1645605920866 } } } ``` ## 使用(核銷)票券 ```url POST /voucher/use ``` #### Request-使用(核銷)票券 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 我的票券id ```javascript { "id": "e78f0201-3e0f-4ec6-b6f6-dfa4ec23d07c" } ``` #### Error-兌換票券 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 422 | SERVICE_ERROR.VOUCHER_USE_EXPIRED | 使用票券日期已過期 422 | SERVICE_ERROR.VOUCHER_USE_HAD_USED | 票券已使用 #### Response-使用(核銷)票券 欄位 | 型態 | 說明 --- | --- | --- id | string | 我的票券id householdMemberId | string | householdMemberId voucherId | string | 票券id seq | int | 此票券兌換的流水號 userVoucherNo | string | 我的票券號碼 redeemTime | timestamp | 兌換時間 redeemPoints | int | 兌換票券所需點數 usedTime | timestamp | 我的票券使用(核銷)時間 status | string | 我的票券狀態, VALID:有效, USED:已使用 ```javascript { "httpCode": 200, "result": { "data": { "id": "e78f0201-3e0f-4ec6-b6f6-dfa4ec23d07c", "householdMemberId": "8a9e980a-c612-4f87-af07-a97a5f0fbed5", "voucherId": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "seq": 1, "userVoucherNo": "M00001012022022200100001", "redeemTime": 1645605920912, "redeemPoints": 150, "usedTime": 1645608469033, "status": "USED", "createTime": 1645605920866, "updateTime": 1645608469033 } } } ``` ## 我的票券列表 ```url POST /voucher/my-list ``` #### Request-我的票券列表 ##### Request-我的票券列表-query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- status | string | N | | 我的票券狀態, VALID:有效, USED:已使用 <BR/>未填則查詢全部 isExpired | boolean | N | | 查詢已過期的票券 productId | string | N | | 查詢該商品綁定的票劵, 長川提供的商品ID. 有填寫的話查詢結果會包含通用票劵+該商品綁定票劵 productPrice | boolean | N | | 過濾商品價格, 列出優惠價格小於商品價格的票劵 ##### Request-我的票券列表-pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 ##### Request-我的票券列表-sorter(排序json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | onEndDate | 排序欄位,可排序欄位有 onEndDate, updateTime order | string | | asc | 升序或降序 ```javascript { "query": { "status": null, "isExpired": null } , "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "onEndDate", "order": "asc" } } ``` #### Response-我的票券列表 欄位 | 型態 | 說明 --- | --- | --- id | string | 我的票券id voucherId | string | 票券id title | string | 票券標題 price | string | 票劵面額 status | string | 我的票券狀態, VALID:有效, USED:已使用 useEndDate | timestamp | 票券使用結束日期 redeemTime | timestamp | 兌換時間 usedTime | timestamp | 我的票券使用(核銷)時間 isExpired | boolean | 票券是否已過使用期限 thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "c92526c2-3601-49d9-bdcf-ffcfa581136b", "voucherId": "f14d33c4-38b1-4611-a6d1-11a1b202305d", "title": "【免費】重乳草莓霜淇淋回歸", "price": 1.00, "useEndDate": 1661961599000, "thumbnailObjectKey": "voucher/thumbnail/77aeb9ea-6451-4f0a-aed3-9a4cdda5966f.jpg", "thumbnailUrl": "http://10.31.104.23/swift/v1/AUTH_test/kmuh/voucher/thumbnail/77aeb9ea-6451-4f0a-aed3-9a4cdda5966f.jpg?temp_url_sig=5c90e22356b797e2dde065d33fa325ae711a41fb&temp_url_expires=1660135360", "status": "VALID", "redeemTime": 1646891243145, "isExpired": false }, ], "pagination": { "current": 1, "pageSize": 10, "total": 1 }, "sorter": { "field": "onEndDate", "order": "asc" }, "total": 1 } } ``` ## 取得我的票券明細 ```url POST /voucher/my-voucher-info ``` #### Request-取得我的票券明細 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id ```javascript { "id": "e78f0201-3e0f-4ec6-b6f6-dfa4ec23d07c" } ``` #### Error-取得我的票券明細 httpCode | 錯誤碼 | 說明 --- | --- | --- 400 | API_ERROR.NOT_EXIST | 資料不存在 #### Response-取得我的票券明細 欄位 | 型態 | 說明 --- | --- | --- id | string | 我的票券id voucherId | string | 票券id userVoucherNo | string | 我的票券號碼 title | string | 票券標題 description | string | 使用說明 notice | string | 注意事項 useStartDate | timestamp | 票券使用開始日期 useEndDate | timestamp | 票券使用結束日期 status | string | 我的票券狀態, VALID:有效, USED:已使用 redeemPoints | int | 兌換票券所需點數 redeemTime | timestamp | 兌換時間 usedTime | timestamp | 我的票券使用(核銷)時間 isExpired | boolean | 票券是否已過使用期限 qrCodePayload | string | 用來在App端產生核銷的QRCode payload thumbnailObjectKey | string | storage中的縮圖objectKey thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 ```javascript { "httpCode": 200, "result": { "data": { "id": "e78f0201-3e0f-4ec6-b6f6-dfa4ec23d07c", "voucherId": "c4ede7cd-8602-43fe-9f72-cfe5146d8a3c", "userVoucherNo": "M00001012022022200100001", "title": "【免費】CITY CAFE 中杯拿鐵或大杯美式一杯", "description": "使用期限內可於全省門市兌換CITY CAFE 中杯拿鐵或大杯美式一杯", "notice": "．本券於兌換/購買成功後，商品將以電子票券儲存於Health 365 App 商城「我的票券」，請於門市現場開啟票券折抵。\n．使用時須符合本券載明之優惠內容項目。商品兌換後，無法提供退貨及換貨。", "useStartDate": 1645545600000, "useEndDate": 1648656000000, "status": "VALID", "redeemPoints": 150, "redeemTime": 1645605920912, "usedTime": 1645608469033, "updateTime": 1645605920866, "isExpired": false, "qrCodePayload": "health365://user-voucher?userVoucherNo=M00001012022022200100001", "thumbnailObjectKey": "voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png", "thumbnailUrl": "http://content-service/swift/v1/voucher/thumbnail/275dce23-8ff5-4def-a780-007a50be1bca.png" } } } ``` ## 票券觸及(曝光) ```url POST /voucher/reach ``` * App 端控制將票券已在畫面呈現給User時, call 此API計算票券的觸及 #### Request-票券觸及(曝光) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- voucherList | string array | Y | | 票券id List, 最多傳入50組票券id, 票券id不可重覆 ```javascript { "voucherList": [ "b02d3f3a-e55f-4f50-a557-55930111a4ae", "f14d33c4-38b1-4611-a6d1-11a1b202305d", "62e120c0-a3e6-4e6c-bdc0-65b3a5fb03d1", "5f09ee60-4ada-4b96-afd3-78c41c005a46" ] } ``` #### Response-票券觸及(曝光) 欄位 | 型態 | 說明 --- | --- | --- count | int | 已計入的數量 ```javascript // HttpStatus:200 { "httpCode": 200, "result": { "data": { "count": 4 } } } ``` ## 票券點擊 ```url POST /voucher/click ``` * 目前情境下, App端不需特地call 此API, 因已在 /voucher/info 這支API裡計算 #### Request-票券點擊 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 票券id ```javascript { "id": "b02d3f3a-e55f-4f50-a557-55930111a4ae" } ``` #### Response-票券點擊 欄位 | 型態 | 說明 --- | --- | --- count | int | 已計入的數量 ```javascript // HttpStatus:200 { "httpCode": 200, "result": { "data": { "count": 1 } } } ```