api-spec-third-party.md 12KB

Yico Website API Specification/前台 API 規格說明

Version/版本:1.1(Verified against staging/已對 staging 實測驗證:2026-10-13;2026-10-21 圖片欄位改名) Machine-readable format/機器格式:see openapi.yaml in the same directory/同目錄 openapi.yaml

1. Overview/總覽

Base URLs:

Environment/環境 Base URL Note/說明
Staging(testable/可測試) https://webdev.yico.tw:8088/api All examples below use this host/以下範例皆用此位址
Production(TBD) https://www.example.com/api Replace with the production domain at launch/上線後替換為正式網域

General rules/通用規則:

  • All endpoints are GET and require no authentication./全部為 GET,免認證。
  • Rate limit: 60 requests/minute (throttle:api)./節流:每分鐘 60 次。
  • Access-Control-Allow-Origin: * is returned./回傳 CORS 全域允許標頭。
  • All responses are JSON. Non-ASCII text is \uXXXX-escaped; decode before display./回應皆 JSON,非 ASCII 以 \uXXXX 跳脫,顯示前請解碼。
  • {locale} path parameter: tw (Traditional Chinese/繁中) or en (English/英文). Any other value returns 404./語系路徑參數僅 tw/en,其餘 404。
  • Long strings in examples are trimmed with ... for readability./範例長字串以 ... 節錄。
  • Image fields use snake_case: img_pc / img_mobile (renamed 2026-10-21; the old imgPC / imgMobile keys are no longer returned)./圖片欄位為 snake_case,舊欄位名稱已不再回傳。

Endpoints/端點一覽:

Method Path/路徑 Description/說明
GET /api/{locale}/news Featured (top) article, year filter list, SEO meta/置頂文章、年份清單、SEO
GET /api/{locale}/news/list Article list with pagination and year/month filter/文章列表(分頁、年月篩選)
GET /api/{locale}/news/detail/{id} Article body, paragraphs, prev/next links/文章內文、段落、前後篇
GET /api/{locale}/esg ESG hero section and tab list/ESG 主視覺與頁籤
GET /api/{locale}/esg/{key} Single ESG page by tab key/單一 ESG 頁面

2. Featured article/置頂文章 GET /api/{locale}/news

No query parameters./無 query 參數。

Response 200 ({data: {meta, yearList, top}}). If no featured article exists, the body is [] (empty array, not an object) — handle both shapes./成功回 {data:{...}};若無置頂資料回 [](空陣列非物件),請相容兩種形狀。

  • yearList: months that contain articles, format YYYY/MM, descending./有文章的年月,YYYY/MM 倒序。
  • top.postDate format: Y/m/d./日期格式 Y/m/d。
{
    "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": "益州集團董事長、前國策顧問、前中華民國工業區廠商聯合總會理事..."
        }
    }
}

3. Article list/文章列表 GET /api/{locale}/news/list

Query parameters/參數:

Name/名稱 Type/型別 Default/預設 Description/說明
page integer 1 Page number/頁碼
per_page integer 15 Items per page; -1 returns all without pagination/每頁筆數;-1 取全部不分頁
year integer — Filter by year/按年篩選
month integer — Must be used together with year (month-only is ignored)/需與 year 並用,單獨傳入無效

Filtering and ordering/過濾與排序:only visible articles within their publish window (start_date/end_date); ordered by order DESC then post_date DESC./僅回可見且在有效期內的文章;依 order 倒序再依發佈日倒序。

Response 200 {"data": {"pagination": {...}, "list": [...]}}./成功回此形狀。

  • pagination.page and per_page are returned as strings./page/per_page 回傳為字串。
  • Empty result: total: 0, total_page: 1 (not 0), list: []./空結果時 total_page 為 1。
  • List item postDate format: Y.m.d (note: different from §2/§4 which use Y/m/d)./此端日期為 Y.m.d(與 §2/§4 的 Y/m/d 不同)。
{
    "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讀通過「加薪四法」中的《公司法》修正案,..."
            }
        ]
    }
}

4. Article detail/文章內文 GET /api/{locale}/news/detail/{id}

  • {id}: numeric article ID (non-numeric → 404)./數字 ID(非數字 404)。
  • ?preview=1: returns the article even if hidden or outside its publish window (for draft preview)./?preview=1 可讀取隱藏/未上架文章(草稿預覽用)。
  • Success 200 {"data": {...}}; missing or unpublished → 404 {"message": "news not found"}./成功 200;不存在或未上架 404。
  • paragraphs are ordered; types: text (content is HTML), image (images: [{img_url, alt}]), video (video_img_url, is_yt, video_url, content as caption)./段落依序排列,型別如列。
  • otherNews.previous = newer article, next = older article; absent when none./前後篇缺則無該鍵。
{
    "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口罩用行動力挺醫護", "...": "..." }
        }
    }
}

5. ESG hero/ESG 主視覺 GET /api/{locale}/esg

Response 200 {"data": {"meta": {...}, "img_pc", "img_mobile", "title", "description", "tab_list": [{text, key}]}}. The tab_list key is absent when no ESG pages exist./成功回此形狀;無 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": "社會共融" }
        ]
    }
}

6. ESG page/ESG 單頁 GET /api/{locale}/esg/{key}

  • {key} is the tab keyword (URL-encode non-ASCII, e.g. %E6%B0%B8%E7%BA%8C%E7%B6%93%E7%87%9F)./{key} 為頁籤 keyword,非 ASCII 請 URL 編碼。
  • Success 200 {"data": {"banner": {...}, "paragraphs": [...]}}./成功回此形狀。
  • Miss returns HTTP 200 (not 404) with {"status": "fail", "message": "查無資料"} — clients MUST check the status field, not only the HTTP code./查無資料時仍回 HTTP 200,body 為上式——請務必判斷 status 欄,不可只看 HTTP 碼。
{
    "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...>..." } }
        ]
    }
}

Paragraph types/段落型別:text (content, HTML) · grid (columns, content[] of text blocks/文字塊陣列) · table (is_card, header[{align, text}], body 2-D array/二維陣列) · image (images[{image_url, alt}]) · video (is_yt: true, video_img_url, video_url, content). Cell align is a numeric code; cell text may contain HTML./align 為數字碼,cell 文字可含 HTML。

Miss example/查無範例(HTTP 200):

{ "status": "fail", "message": "查無資料" }
// Recommended client check/建議判斷方式
const res = await fetch(url).then(r => r.json());
if (res.status === 'fail') { /* no such page/無此頁面 */ }

7. Data models/資料模型

Common article fields/通用文章欄位:

Field/欄位 Type/型別 Description/說明
id integer Article ID/文章 ID
categoryId integer Category ID/分類 ID
category string Localized category name/在地化分類名
postDate string Y.m.d in list (§3), Y/m/d elsewhere/列表 Y.m.d,其餘 Y/m/d
title string Localized title/在地化標題
description string Localized summary/在地化摘要
written string Author/byline/作者
img_pc / img_mobile string|null Desktop/mobile image URLs (may contain //)/桌機/手機圖(或有雙斜線)
metaTitle / metaKeyword / metaDesc / metaImg string|null SEO fields, detail only/SEO 欄位,僅內文

8. Error handling/錯誤處理

HTTP Body When/時機
200 {"status": "fail", "message": "查無資料"} ESG key not found (see §6)/ESG 查無資料
404 {"message": "news not found"} Article missing or unpublished/文章不存在或未上架
404 HTML error page Unknown path, non-tw/en locale, or non-numeric detail id/未知路徑、非 tw/en 語系、非數字 id
429 JSON Over 60 requests/minute/超過節流