Yico 前台 API 規格說明
- Base URL(實測):
https://webdev.yico.tw:8088 + 前綴 /api
- 本地對應:
http://127.0.0.1:8083/api(.env APP_URL)
- 全部為
GET,免認證;節流 throttle:api(預設 60 次/分鐘);實測回 Access-Control-Allow-Origin: *
- 回應皆 JSON;中文以
\uXXXX 跳脫;圖片 URL 實測含雙斜線(...tw:8088//storage/...,前端可正常讀取)
- 語系路徑參數
{locale}:僅 tw|en(tw 對應 zh_TW);其他值回 404
- 範例取自 staging 實測(2026-10-13),長字串以
... 節錄
端點總覽
| 方法 |
路徑 |
說明 |
| GET |
/api/{locale}/news |
置頂消息+年份清單+SEO meta |
| GET |
/api/{locale}/news/list |
消息列表(分頁/年月過濾) |
| GET |
/api/{locale}/news/detail/{id} |
消息內文(含段落、前後篇) |
| GET |
/api/{locale}/esg |
ESG 主視覺+頁籤清單 |
| GET |
/api/{locale}/esg/{key} |
ESG 單頁內容(key 需 URL 編碼) |
1. 置頂消息 GET /api/{locale}/news
- Query:無(
categoryId 已於 2026-10-13 移除,舊版傳入亦無效)。
200 {"data": {"meta": {...}, "yearList": [...], "top": {...}}};若無置頂資料回 [](空陣列,注意非物件)。
{
"data": {
"meta": {
"meta_title": "秦嘉鴻回憶錄全新出版",
"meta_keyword": "秦嘉鴻 回憶錄 油品大亨 ...",
"meta_description": "透過秦嘉鴻董事長的回憶錄,得以領略為人處...",
"img_pc": null
},
"yearList": ["2026/07", "2026/01", "2025/04"],
"top": {
"id": 49,
"categoryId": 1,
"category": "最新公告",
"postDate": "2025/04/24",
"title": "益州董事長秦嘉鴻 出版回憶錄",
"img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JW5GAC910DRBH2ZZPEKVG.webp",
"img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9GRA0EBP8NPE3BH1ZWY.webp",
"written": "黃全興",
"description": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..."
}
}
}
yearList:有文章的年月(YYYY/MM,倒序,取自全部可見文章,不分語系)。
- 日期格式此端為
Y/m/d(與 list 的 Y.m.d 不同,見 §7)。
2. 消息列表 GET /api/{locale}/news/list
- Query:
page(預設 1)、per_page(預設 15;-1 取全部不分頁)、year、month。
- 過濾:僅
visible=1 且在 start_date/end_date 有效期內;year+month 並用取該月,僅 year 取該年,僅 month 不過濾;排序 order DESC、post_date DESC。
200 {"data": {"pagination": {...}, "list": [...]}};空資料時 total: 0、total_page: 1(非 0)、list: []。
{
"data": {
"pagination": { "page": 1, "per_page": "2", "total": 32, "total_page": 16 },
"list": [
{
"id": 2,
"categoryId": 1,
"category": "最新公告",
"postDate": "2015.05.06",
"title": "秦嘉鴻:要4贏,不要4輸",
"img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
"img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
"written": "記者黃全興/中時電子報",
"description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,..."
}
]
}
}
- 注意:
pagination.page/per_page 回傳為字串;postDate 此端為 Y.m.d。
3. 消息內文 GET /api/{locale}/news/detail/{id}
{id} 限數字(非數字 404);?preview=1 可 bypass 可見性與有效期(免認證,見 §7 安全注意)。
- 成功
200 {"data": {...}};不存在/未上架 404 {"message": "news not found"}。
paragraphs 依 order 排序,型別:text(content 為 HTML,含 <br>),image(images: [{img_url, alt}]),video(video_img_url、is_yt、video_url、content 為 alt/說明)。
otherNews.previous=前一篇(較新)、next=下一篇;無則缺鍵。
{
"data": {
"categoryId": 1,
"category": "最新公告",
"postDate": "2015/05/06",
"title": "秦嘉鴻:要4贏,不要4輸",
"description": "5月1日立法院院會3讀通過「加薪四法」中的《公司法》修正案,...",
"written": "記者黃全興/中時電子報",
"img_pc": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6JS0HMAF4XMWQ7X67SB.jpg",
"img_mobile": "https://webdev.yico.tw:8088//storage/news/01KJ9JE6KWVA0V1WY9HMZ3T9SJ.jpg",
"metaTitle": "測試SEO",
"metaKeyword": "",
"metaDesc": "",
"metaImg": null,
"paragraphs": [
{ "type": "text", "content": "<h4 class=\"lexical__h4\" dir=\"ltr\"><span ...>5月1日...</span></h4>" },
{ "type": "image", "images": [{ "img_url": "https://webdev.yico.tw:8088//storage/news/extraPhoto/01KJ9BK7695DZX6QRDNVSW2FFN.jpg", "alt": "中華民國工業區廠商聯合總會理事長秦嘉鴻。圖/黃全興" }] }
],
"otherNews": {
"next": { "id": 30, "categoryId": 1, "category": "最新公告", "postDate": "2022/07/27", "title": "國策顧問捐贈台大醫院雲林分院N95口罩用行動力挺醫護", "...": "..." }
}
}
}
4. ESG 主視覺 GET /api/{locale}/esg
200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}};尚無 ESG 資料時缺 tab_list 鍵。
{
"data": {
"meta": { "meta_title": "", "meta_keyword": "", "meta_description": "", "og_img": null },
"img_pc": null,
"img_mobile": null,
"title": "經營者的話",
"description": "面對全球經濟變動與氣候挑戰,企業責任不僅在於追求經濟成長,更...",
"tab_list": [
{ "text": "永續經營", "key": "永續經營" },
{ "text": "公司治理", "key": "公司治理" },
{ "text": "創新研發", "key": "創新研發" },
{ "text": "綠色承諾", "key": "綠色承諾" },
{ "text": "社會共融", "key": "社會共融" }
]
}
}
5. ESG 單頁 GET /api/{locale}/esg/{key}
{key} 為頁籤 keyword(中文需 URL 編碼,如 %E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F)。
- 成功
200 {"data": {"banner": {...}, "paragraphs": [...]}};查無資料時維持 200 {"status": "fail", "message": "查無資料"}(刻意保留舊前端相容,勿改判 404)。
- 段落型別:
text(content HTML)、grid(columns+content[] 文字塊)、table(is_card、header[{align,text}]、body 二維陣列)、image(images[{image_url, alt}])、video(is_yt: true、video_img_url、video_url、content)。align 為數字碼;cell 文字含 HTML。
{
"data": {
"banner": {
"img_pc": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH4Q989Z7AQ4AMVDTSR8.jpg",
"img_mobile": "https://webdev.yico.tw:8088//storage/esg/01KKE6AH53W3HWH61CXXBKNFZD.jpg",
"img_alt": "永續經營",
"text": "邁向百年企業的根基..."
},
"paragraphs": [
{ "type": "text", "content": "永續經營一、永續治理組織為傳承企業經營理念並確立長達發展方針..." },
{ "type": "grid", "columns": 2, "content": [{ "type": "text", "content": "家族理事會家族最高治理單位..." }] },
{ "type": "table", "is_card": false,
"header": [{ "align": 1, "text": "公(協)會組織" }, { "align": 1, "text": "參與資格 " }],
"body": { "align": 1, "text": "<p...>..." }, { "align": 1, "text": "<p...>..." } }
]
}
}
6. 已移除:GET /api/user
- 原 Sanctum 範例路由;Sanctum 未安裝,實測恆 500,已於 2026-10-13 移除。
7. 檢查記錄(實測佐證)
本次(2026-10-13)檢查+修復:
| # |
項目 |
結果 |
| 1 |
語系參數綁定 |
✅ 正常。Laravel 以位置綁定非型別參數,{locale} 正確傳入;staging en 回英文、tw 回中文已證實。最初「被忽略」為誤判(已讀框架源碼+實測推翻)。 |
| 2 |
esgContent 參數名 |
✅ 正常。同上,位置綁定 cover;Esg::getContentByKeyword() 經 __callStatic 轉實例呼叫有效,staging 有資料回 200 已證實。 |
| 3 |
路由 locale 约束失效 |
🔧 已修。->group(...)->whereIn(...) 掛在 group 之後,對已註冊路由無效(RouteRegistrar::group() 回傳自身,__call spread 又把字串 where 形狀搞壞,直接 500)。現改為 `prefix('{locale}')->where(['locale' => 'tw |
| 4 |
getTop 的 categoryId |
🔧 已修(刪 dead code)。實測 ?categoryId=999 與不帶結果相同,確認未生效;該讀值行已刪除,行為零變更。 |
| 5 |
Sanctum /user |
🔧 已修(刪除)。未安裝 Sanctum,實測 500 且吐 debug HTML;無客戶端可依賴,移除。 |
| 6 |
ESG 查無資料回 200 |
➖ 保留。{"status":"fail","message":"查無資料"} 配 HTTP 200,舊前端已依此相容,刻意不改,文件載明。 |
| 7 |
detail ?preview=1 免認證看隱藏文 |
⚠️ 現況載明,未改。若需上鎖請另起任務(加 auth 或簽章)。 |
| 8 |
日期格式不一致 |
➖ 載明:getTop/detail 用 Y/m/d,list 用 Y.m.d。前端已相容,不改。 |
| 9 |
pagination.page/per_page 回字串、空列表 total_page: 1、per_page=-1 全取、僅 month 不過濾 |
➖ 現況載明,不改。 |
| 10 |
無置頂時 GET news 回 [](非物件) |
➖ 現況載明,前端判空陣列處理。 |
| 11 |
圖片雙斜線 //storage/ |
➖ staging APP_URL 尾斜線所致,前端可讀;要修改 staging .env(非本 repo)。 |
| 12 |
Staging APP_DEBUG 疑似開 |
⚠️ /api/user 500 回整頁 debug HTML,建議 staging 關閉(伺服器 env,非本 repo)。 |
| 13 |
死碼 |
➖ 載明未動:AccessIpMiddleware(accessIp alias 無路由使用)、App\Supports\Response、App\Http\Helper(僅 import)、ContactRequest/RegistEPaperRequest(無路由使用)。 |
| 14 |
效能 |
➖ list/detail 逐筆取 newsCategory/paragraphs.photos(N+1),資料量小可接受,量大再加 with()。 |
| 15 |
圖片欄位命名不一致 |
🔧 已修(2026-10-21)。News API 的 imgPC/imgMobile 改名為 img_pc/img_mobile,與 ESG API 一致;不保留舊鍵,前端需同步改用新欄位。 |
8. 對應原始碼
routes/api.php、app/Http/Controllers/Api/NewsController.php、app/Http/Controllers/Api/EsgController.php
- 模型:
News(newsCategory、paragraphs、news_img_pc_url 等)、NewsParagraph(contentType: 1=image、2=text、3=video)、Esg(getContentByKeyword)、EsgMain
- 機器格式見
openapi.yaml(同目錄)。