# 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": {...}}}`;若無置頂資料回 `[]`(空陣列,注意非物件)。
```json
{
"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: []`。
```json
{
"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,含 `
`),`image`(`images: [{img_url, alt}]`),`video`(`video_img_url`、`is_yt`、`video_url`、`content` 為 alt/說明)。
- `otherNews.previous`=前一篇(較新)、`next`=下一篇;無則缺鍵。
```json
{
"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": "