# 會員獎品兌換紀錄管理
Custos-EnterpriseAPP-API-019
V1.0
2023-11-06

Custos 企業會員 APP 使用者瀏覽獎品頁面後，可透過 APP 進行兌換，並呼叫此 API 針對兌換紀錄進行查詢/新增/修改/刪除。

[toc]
## 作業啟動
1. 以傳入之使用者 token 取得使用者流水編號 #emp_data_id
2. 記錄 SystemLog：#emp_data_id|獎品兌換紀錄管理，獎品序號為 #item_id，執行動作為 #action|作業啟動

## API 作業啟動
1. 以 #emp_data_id 取得使用者個人資料
2. 傳入執行動作 #action，C 為新增、U 為更新、D 為刪除
3. #action 為 C：傳入收件人、收件地址、偏好收件日期、時間、以及備註等欄位，將資料寫入 corp_fm_rewards_exchange_records 資料表，狀態為 To Ship (待寄送)，並將兌換所用的樹從 corp_ls_emp_carbon_records.trees_accum 扣除
4. #action 為 U：傳入獎品兌換紀錄流水號 #data_id、收件人、收件地址、偏好收件日期、時間、以及備註等欄位，更新 corp_fm_rewards_exchange_records 資料表。只有狀態在 To Ship 才能更新資料
5. #action 為 D：：傳入獎品兌換紀錄流水號 #data_id，查詢corp_fm_rewards_exchange_records 資料表，並將資料刪除。只有狀態在 To Ship 才能刪除資料，刪除時需將兌換所使用之樹退還 (corp_ls_emp_carbon_records.trees_accum)

## 作業結束
記錄 SystemLog：#emp_data_id|獎品兌換紀錄管理，獎品序號為 #item_id，執行動作為 #action|作業結束

## 例外處理
若執行中有發生異常，將攔截到的 exception 訊息記錄 ErrorLog：[YYYYMMDDHHMMSS] EnterpriseAPP-API-019 發生異常：【#攔截到的 exception 訊息】

## 規格及範例
|API No|EnterpriseAPP-API-019|
|-|-|
|API Name|mgtRedeemRewards|
|URL|${url}/APP/setData/mgtRedeemRewards|
|Purpose|會員獎品兌換紀錄管理|
|Description|透過 API 進行會員獎品兌換紀錄管理|
|Protocol|JSON over HTTP POST|
|Content-Type|application/json|

**Request**
|參數|型態|必填|長度|說明|
|-|-|:-:|:-:|-|
|action|String|Y|1|C：新增、U：修改、D：刪除|
|token|String|Y||使用者驗證字串|
|item_id|INT|N||action 為 C 時才傳，獎品流水號，非必填|
|recipient_name|String|N|45|action 為 C、U 時才傳，收件人姓名，非必填|
|address|String|N|200|action 為 C、U 時才傳，收件地址，非必填|
|email|String|N|50|action 為 C、U 時才傳，非必填|
|preferred_delivery_date|Datetime|N||action 為 C、U 時才傳，偏好收件日期，非必填|
|preferred_delivery_time|String|N|20|action 為 C、U 時才傳，偏好收件時間，非必填|
|remarks|String|N|200|action 為 C、U 時才傳，備註，非必填|
|data_id|INT|N||action 為 U、D 時才傳，獎品兌換紀錄流水號，非必填|
|modify_oper|String|Y|10|手機平台，iOS 或 Android|

**Response**
|參數|型態|必回|說明|
|-|-|:-:|-|
|result|String|Y|API 執行結果，Y：成功，N：失敗|
|message|String|N|API 執行失敗的訊息說明|

**Request Sample (action = 'C')**

var input = {
    "action": "C",
    "token": "...",
    "item_id": 35,
    "recipient_name": "王小明",
    "address": "台北市xxxxx",
    "email": "[e-mail]",
    "preferred_delivery_date": "2023-12-08",
    "preferred_delivery_time": "16:00-18:00",
    "remarks": "...",
    "modify_oper": "iOS"
}

**Response Sample (action = 'C')**

{
    "result": "Y",	   //API 結果，Result = Y 時才會有 data 資料
    "message": "..."	   //API 訊息，Ex："執行失敗，原因：XXXXXXXXX"
}