查詢任務列表 API | Cube Rewards Tool

查詢任務列表 API.md

245 additions, 73 deletions

...	...	@@ -2,15 +2,16 @@
2		- \| 1.0 \| 初版 \| 2026/01/16 \| Hanna \|
	2	+ \| 1.0 \| 初版 \| 2026/01/27 \| Hanna \|
3		- 說明
	3	+ ## 說明
	4	+
4		- curl GET {EndPoint}/mds/ups/vip/benefit
	5	+ curl GET {EndPoint}/mds/mbps/mission/list?entryPoint=HOME
	6	+## REQUEST URL PARAMETER
	7	+
	8	+\| Level \| Key \| Data type \| Required \| Field name \| Description / Example \|
	9	+\| ---\| ---\| ---\| ---\| ---\| --- \|
	10	+\| 1 \| entryPoint \| String \| true \| 進入點 \| 擇一傳入<br><br>不同進入點決定：<br><br><br><br>`HOME`: 首頁（回傳封測與正式的未達標、已達標未領獎的任務）<br><br>`AVAILABLE_LIST`: 任務牆列表-最新任務（回傳封測與正式的尚未開始、未達標、已達標未領獎的任務）<br><br>`HISTORY_LIST`: 任務牆列表-任務紀錄（回傳封測與正式的已領獎、已額滿、已逾期的任務） \|
	11	+
5		- \| level \| key \| type \| required \| field name \| example \|
	12	+ \| Level \| Parameters \| Data type \| Required field \| Field name \| Description / example \|
6		-\| 1 \| success \| boolean \| true \| 是否成功 \| true \|
7		-\| 1 \| errorCode \| String \| false \| 錯誤代碼 \| null \|
8		-\| 1 \| message \| String \| false \| 錯誤訊息 \| null \|
9		-\| 1 \| values \| Object \| true \| \| \|
10		-\| 2 \| benefits \| array<obj> \| true \| 禮遇列表 \| \|
11		-\| 3 \| id \| String \| true \| 禮遇 id \| 1 \|
12		-\| 3 \| title \| String \| true \| 專區名稱 \| VIP生日禮 \|
13		-\| 3 \| content \| String \| false \| 禮遇內容 \| 精選日式餐廳 \|
14		-\| 3 \| imageUrl \| String \| false \| 圖片 URL \| [http://sss.ggg.www.com/2.png](http://sss.ggg.www.com/2.png) \|
15		-\| 3 \| tagCodes \| array<String> \| false \| 標籤代碼 \| ["FAST_FOOD", "TRANSPORT_TRAVEL"] \|
16		-\| 3 \| linkUrl \| String \| false \| 連結 URL \| mmo://webview?type=4 \|
17		-\| 3 \| contentType \| String \| false \| 內容類型 \| PUBLIC \|
18		-\| 3 \| startTime \| ISO 8601 \| false \| 開始時間 \| 2025-07-12T14:20:50+08:00 \|
19		-\| 3 \| endTime \| ISO 8601 \| false \| 結束時間 \| 2025-07-12T14:20:50+08:00 \|
20		-\| 3 \| isGoldenStyle \| boolean \| true \| 是否套用金色樣式 \| true / false \|
21		-\| 3 \| goldenTitle \| String \| false \| 金色標題 \| 獨家禮遇 \|
22		-\| 3 \| goldenButton \| String \| false \| 金色按鈕 \| 前往預定 \|
23		-\| 3 \| goldenContent \| String \| false \| 金色內容 \| 登龍門頂級饗宴 \|
24		-\| 3 \| goldenStartTime \| ISO 8601 \| false \| 金色開始時間 \| 2025-07-12T14:20:50+08:00 \|
25		-\| 3 \| goldenEndTime \| ISO 8601 \| false \| 金色結束時間 \| 2025-07-12T14:20:50+08:00 \|
26		-\| 2 \| tagList \| array<obj> \| true \| 標籤清單 \| \|
27		-\| 3 \| tagName \| String \| true \| 標籤名稱 \| 速食快餐 \|
28		- \| 3 \| tagCode \| String \| true \| 標籤代碼 \| FAST_FOOD \|
	13	+ \| 1 \| success \| Boolean \| true \| 是否成功 \| \|
	14	+\| 1 \| errorCode \| String \| false \| 錯誤代碼 \| \|
	15	+\| 1 \| message \| String \| false \| 錯誤訊息 \| \|
	16	+\| 1 \| values \| JsonObject \| true \| 成功 response 內容 \| \|
	17	+\| 2 \| missions<br> \| Array<`Mission`> \| true \| 任務清單 \| 請參考下方 Mission 區塊 \|
29		-## RESPONSEBODY - JSON Format
30		- Success format:
	18	+ ## Mission
31		- ```cs
	19	+ \| Level \| Parameters \| Data type \| Required field \| Field name \| Description / example \|
	20	+\| ---\| ---\| ---\| ---\| ---\| --- \|
	21	+\| 3 \| id \| String \| true \| 任務 ID \| FOOBAR123 \|
	22	+\| 3 \| name \| String \| true \| 任務名稱 \| 1212限定Ｉ甜蜜共享 \|
	23	+\| 3 \| description \| String \| true \| 任務簡述 \| 兌換專區內指定任三張票券 \|
	24	+\| 3 \| category \| String \| true \| 任務類型 \| `ASSIGNED` : 指定型<br>`MILESTONE` : 多門檻型<br>`SEQUENTIAL` : 關聯型 \|
	25	+\| 3 \| status \| String \| true \| 任務狀態 \| `UNSTARTED` : 尚未開始<br>`STARTED` : 已開始未達標<br>`UNREDEEMED` : 已達標未領獎<br>`REDEEMED` : 已領獎<br>`FULL` : 已額滿<br>`OVERDUE` : 已逾期 \|
	26	+\| 3 \| progress \| String \| false \| 任務完成進度 \| "0.65"<br><br>當進入點是首頁 && 遇到限流 && redis 無該 us_er 進度資料時，會回傳 null_ \|
	27	+\| 3 \| remainingTime \| Integer \| true \| 任務剩餘時間（秒） \| 259200 \|
	28	+\| 3 \| remainingQuota \| Integer \| false \| 任務剩餘名額 \| 1000<br>當進入點是首頁時可能回傳 null \|
	29	+\| 3 \| startDate \| String \| true \| 任務開始日 \| ISO8601 格式2026-01-01T00:00:00+08:00 \|
	30	+\| 3 \| endDate \| String \| true \| 任務截止日 \| ISO8601 格式<br>2026-12-31T23:59:59+08:00 \|
	31	+\| 3 \| awardType \| String \| true \| 獎項類型 \| `POINT` : 小樹點<br>`VOUCHER` : 票券 \|
	32	+\| 3 \| awardContent \| String \| true \| 獎項內容 \| 星巴克拿鐵票券乙張<br>30 \|
	33	+\| 3 \| isBulkheadRejected \| boolean \| true \| 是否遇到限流 \| 當進入點是首頁 && 遇到限流 && redis 無該 user 進度資料時，會回傳 true \|
	34	+
	35	+## RESPONSE BODY - json format
	36	+
	37	+* 首頁（回傳未達標、已達標未領獎的任務）
	38	+
	39	+ ```json
32	40	"success": true,
33	41	"errorCode": null,
34	42	"message": null,
35	43	"values": {
36		- "benefits": [
	44	+ "missions": [
37	45	{
38		- "id": "1",
39		- "title": "VIP生日禮",
40		- "content": "精選日式餐廳",
41		- "imageUrl": "http://sss.ggg.www.com/2.png",
42		- "tagCodes": ["FAST_FOOD","TRANSPORT_TRAVEL"],
43		- "linkUrl": "mmo://webview?type=4",
44		- "contentType": "PUBLIC",
45		- "startTime": "2025-07-12T14:20:50+08:00",
46		- "endTime": "2025-07-12T14:20:50+08:00",
47		- "isGoldenStyle": true,
48		- "goldenTitle": "獨家禮遇",
49		- "goldenButton": "前往預定",
50		- "goldenContent": "登龍門頂級饗宴",
51		- "goldenStartTime": "2025-07-12T14:20:50+08:00",
52		- "goldenEndTime": "2025-07-12T14:20:50+08:00"
	46	+ "id": "FOOBAR456",
	47	+ "name": "1212限定Ｉ成雙成對甜蜜共享",
	48	+ "description": "兌換專區內指定任兩張票券",
	49	+ "category": "ASSIGNED",
	50	+ "status": "UNREDEEMED",
	51	+ "progress": "1.00",
	52	+ "remainingTime": 259200,
	53	+ "remainingQuota": 80,
	54	+ "startDate": "2026-01-01T00:00:00+08:00",
	55	+ "endDate": "2026-12-31T23:59:59+08:00",
	56	+ "awardType": "VOUCHER",
	57	+ "awardContent": "星巴克拿鐵票券乙張",
	58	+ "isBulkheadRejected": false
53	59	},
54	60	{
55		- "id": "2",
56		- "title": "VIP生日禮",
57		- "content": "精選日式餐廳",
58		- "imageUrl": "http://sss.ggg.www.com/2.png",
59		- "tagCodes": ["FAST_FOOD","TRANSPORT_TRAVEL"],
60		- "linkUrl": "mmo://webview?type=4",
61		- "contentType": "PUBLIC",
62		- "startTime": "2025-07-12T14:20:50+08:00",
63		- "endTime": "2025-07-12T14:20:50+08:00",
64		- "isGoldenStyle": false,
65		- "goldenTitle": null,
66		- "goldenButton": null,
67		- "goldenContent": null,
68		- "goldenStartTime": null,
69		- "goldenEndTime": null
	61	+ "id": "FOOBAR123",
	62	+ "name": "1212限定Ｉ甜蜜共享",
	63	+ "description": "兌換專區內指定任三張票券",
	64	+ "category": "ASSIGNED",
	65	+ "status": "STARTED",
	66	+ "progress": "0.00",
	67	+ "remainingTime": 36000,
	68	+ "remainingQuota": 1000,
	69	+ "startDate": "2026-01-01T00:00:00+08:00",
	70	+ "endDate": "2026-12-31T23:59:59+08:00",
	71	+ "awardType": "POINT",
	72	+ "awardContent": "30",
	73	+ "isBulkheadRejected": false
70	74	}
71		- ],
72		- "tagList": [
	75	+ ]
	76	+ }
	77	+ }
	78	+ ```
	79	+
	80	+
	81	+* 任務牆列表-最新任務（回傳尚未開始、未達標、已達標未領獎的任務）
	82	+
	83	+ ```json
73	84	{
74		- "tagName": "速食快餐",
75		- "tagCode": "FAST_FOOD"
	85	+ "success": true,
	86	+ "errorCode": null,
	87	+ "message": null,
	88	+ "values": {
	89	+ "missions": [
	90	+ {
	91	+ "id": "FOOBAR456",
	92	+ "name": "1212限定Ｉ成雙成對甜蜜共享",
	93	+ "description": "兌換專區內指定任兩張票券",
	94	+ "category": "ASSIGNED",
	95	+ "status": "UNREDEEMED",
	96	+ "progress": "1.00",
	97	+ "remainingTime": 259200,
	98	+ "remainingQuota": 80,
	99	+ "startDate": "2026-01-01T00:00:00+08:00",
	100	+ "endDate": "2026-12-31T23:59:59+08:00",
	101	+ "awardType": "VOUCHER",
	102	+ "awardContent": "星巴克拿鐵票券乙張",
	103	+ "isBulkheadRejected": false
76	104	},
77	105	{
78		- "tagName": "交通旅遊",
79		- "tagCode": "TRANSPORT_TRAVEL"
	106	+ "id": "FOOBAR123",
	107	+ "name": "1212限定Ｉ甜蜜共享",
	108	+ "description": "兌換專區內指定任三張票券",
	109	+ "category": "ASSIGNED",
	110	+ "status": "STARTED",
	111	+ "progress": "0.00",
	112	+ "remainingTime": 36000,
	113	+ "remainingQuota": 1000,
	114	+ "startDate": "2026-01-01T00:00:00+08:00",
	115	+ "endDate": "2026-12-31T23:59:59+08:00",
	116	+ "awardType": "POINT",
	117	+ "awardContent": "30",
	118	+ "isBulkheadRejected": false
	119	+ },
	120	+ {
	121	+ "id": "FOOBAR5566",
	122	+ "name": "1212限定Ｉ甜蜜共享",
	123	+ "description": "兌換專區內指定任一張票券",
	124	+ "category": "ASSIGNED",
	125	+ "status": "UNSTARTED",
	126	+ "progress": "0.00",
	127	+ "remainingTime": 259200,
	128	+ "remainingQuota": 1000,
	129	+ "startDate": "2026-12-01T00:00:00+08:00",
	130	+ "endDate": "2026-12-31T23:59:59+08:00",
	131	+ "awardType": "POINT",
	132	+ "awardContent": "10",
	133	+ "isBulkheadRejected": false
80	134	}
81	135	]
82	136	}
	137	+ ```
83		- #查無禮遇:
	138	+ * 任務牆列表-任務紀錄（回傳已領獎、已額滿、已逾期的任務）
	139	+
	140	+ ```json
84	141	"success": true,
85	142	"errorCode": null,
86	143	"message": null,
87	144	"values": {
88		- "benefits": [],
89		- "tagList": []
	145	+ "missions": [
	146	+ {
	147	+ "id": "FOOBAR456",
	148	+ "name": "1212限定Ｉ成雙成對甜蜜共享",
	149	+ "description": "兌換專區內指定任兩張票券",
	150	+ "category": "ASSIGNED",
	151	+ "status": "REDEEMED",
	152	+ "progress": "1.00",
	153	+ "remainingTime": 259200,
	154	+ "remainingQuota": 80,
	155	+ "startDate": "2026-01-01T00:00:00+08:00",
	156	+ "endDate": "2026-12-31T23:59:59+08:00",
	157	+ "awardType": "VOUCHER",
	158	+ "awardContent": "星巴克拿鐵票券乙張",
	159	+ "isBulkheadRejected": false
	160	+ },
	161	+ {
	162	+ "id": "FOOBAR123",
	163	+ "name": "1212限定Ｉ甜蜜共享",
	164	+ "description": "兌換專區內指定任三張票券",
	165	+ "category": "ASSIGNED",
	166	+ "status": "OVERDUE",
	167	+ "progress": "0.78",
	168	+ "remainingTime": 0,
	169	+ "remainingQuota": 1000,
	170	+ "startDate": "2026-01-02T00:00:00+08:00",
	171	+ "endDate": "2026-01-03T23:59:59+08:00",
	172	+ "awardType": "POINT",
	173	+ "awardContent": "30",
	174	+ "isBulkheadRejected": false
	175	+ },
	176	+ {
	177	+ "id": "FOOBAR5566",
	178	+ "name": "1212限定Ｉ甜蜜共享",
	179	+ "description": "兌換專區內指定任一張票券",
	180	+ "category": "ASSIGNED",
	181	+ "status": "FULL",
	182	+ "progress": "0.25",
	183	+ "remainingTime": 259200,
	184	+ "remainingQuota": 1000,
	185	+ "startDate": "2026-01-01T00:00:00+08:00",
	186	+ "endDate": "2026-12-31T23:59:59+08:00",
	187	+ "awardType": "POINT",
	188	+ "awardContent": "10",
	189	+ "isBulkheadRejected": false
90	190	}
	191	+ ]
	192	+ }
	193	+ ```
	194	+* 首頁 && 遇到限流 && redis 無該 user 進度資料
	195	+
	196	+ ```json
	197	+ {
	198	+ "success": true,
	199	+ "errorCode": null,
	200	+ "message": null,
	201	+ "values": {
	202	+ "missions": [
	203	+ {
	204	+ "id": "FOOBAR456",
	205	+ "name": "1212限定Ｉ成雙成對甜蜜共享",
	206	+ "description": "兌換專區內指定任兩張票券",
	207	+ "category": "ASSIGNED",
	208	+ "status": "UNREDEEMED",
	209	+ "progress": null,
	210	+ "remainingTime": 259200,
	211	+ "remainingQuota": 80,
	212	+ "startDate": "2026-01-01T00:00:00+08:00",
	213	+ "endDate": "2026-12-31T23:59:59+08:00",
	214	+ "awardType": "VOUCHER",
	215	+ "awardContent": "星巴克拿鐵票券乙張",
	216	+ "isBulkheadRejected": true
	217	+ },
	218	+ {
	219	+ "id": "FOOBAR123",
	220	+ "name": "1212限定Ｉ甜蜜共享",
	221	+ "description": "兌換專區內指定任三張票券",
	222	+ "category": "ASSIGNED",
	223	+ "status": "STARTED",
	224	+ "progress": "0.00",
	225	+ "remainingTime": 36000,
	226	+ "remainingQuota": 1000,
	227	+ "startDate": "2026-01-01T00:00:00+08:00",
	228	+ "endDate": "2026-12-31T23:59:59+08:00",
	229	+ "awardType": "POINT",
	230	+ "awardContent": "30",
	231	+ "isBulkheadRejected": false
	232	+ }
	233	+ ]
	234	+ }
	235	+ }
91		-## Error code
92		- \| B2E錯誤代碼 \| B2E內部錯誤訊息 \| APP 錯誤代碼 \| APP 錯誤訊息 \|
	236	+ * 無資料
	237	+
	238	+ ```json
	239	+ {
	240	+ "success": true,
	241	+ "errorCode": null,
	242	+ "message": null,
	243	+ "values": {
	244	+ "missions": []
	245	+ }
	246	+ }
	247	+ ```
	248	+
	249	+
	250	+* API 錯誤
	251	+
	252	+ ```cs
	253	+ {
	254	+ "success": false,
	255	+ "errorCode": {error_code},
	256	+ "message": {error_message},
	257	+ "values": null
	258	+ }
	259	+ ```
	260	+
	261	+
	262	+\| B2E內部錯誤訊息 \| B2E錯誤代碼 \| App錯誤訊息 \| App錯誤代碼 \|
93		- \| UPS_UNKNOWN_ERROR \| 系統忙碌中，請稍後再試 \| UPS0000 \| 系統忙碌中，請稍後再試 \|
	263	+ \| \| \| \| \|
	264	+\| \| \| \| \|
	265	+\| \| \| \| \|