TWKC 2026（17 屆）WordPress 串接說明

① 外掛下載

TWKC Lottery WordPress 外掛（含本屆富翁戰況速報短碼）。後台「外掛 → 安裝外掛 → 上傳外掛」直接上傳此 zip。

⬇ 下載 twkc-lottery-plugin.zip

檔名 twkc-lottery-plugin.zip
對應後端 main commit 5f9fc501
SHA-256 66d5c61d…0af7ce27

安裝後必做：到外掛設定頁填「API 連線位置 / REST API Url」指向本屆 API （正式站網域 + /api/v1）與 token，前台短碼與得獎名單才抓得到資料。

本外掛同時負責各獎項得獎名單 shortcode與富翁戰況速報。本頁僅說明「富翁戰況速報」與「分享集點 API」兩項新串接；得獎名單 shortcode 沿用既往用法。

② 富翁戰況速報短碼

在頁面輸出一段 JSON（不渲染畫面），由前端 JS 讀取後自行套版。內含各券商「實動戶數榜」與「財富累積榜」前三名。

👑 實動戶數榜 active_accounts

① 元大證券219 戶

② 群益金鼎證券211 戶

③ 永豐金證券207 戶

👑 財富累積榜 wealth

① 凱基證券4,227,299,800

② 永豐金證券3,489,002,060

③ 元大證券3,111,528,100

短碼

// 預設（script id = twkc-firms-status）
[twkc-lottery-firms-status]

// 自訂 script 標籤 id
[twkc-lottery-firms-status id="自訂id"]

輸出 HTML

<script type="application/json" id="twkc-firms-status">
{
  "updated_at": "2026-07-25 06:00:12",
  "active_accounts": [
    { "rank":1, "firm":"元大證券",     "value":219 },
    { "rank":2, "firm":"群益金鼎證券", "value":211 },
    { "rank":3, "firm":"永豐金證券",   "value":207 }
  ],
  "wealth": [
    { "rank":1, "firm":"凱基證券",   "value":4227299800 },
    { "rank":2, "firm":"永豐金證券", "value":3489002060 },
    { "rank":3, "firm":"元大證券",   "value":3111528100 }
  ]
}
</script>

註：上方數字為示意（16 屆真實彙總）；正式環境輸出本屆 cache。資料空時 active_accounts / wealth 為空陣列。

欄位

欄位	說明
`updated_at`	cache 產生時間
`active_accounts[]`	實動戶數榜（紅框）。`{rank, firm, value}`，`value` = 實動戶數
`wealth[]`	財富累積榜（藍框）。`{rank, firm, value}`，`value` = 總買入金額（元）

前端 JS 取用

const data = JSON.parse(
  document.getElementById('twkc-firms-status').textContent
);
data.active_accounts.forEach(r => {
  // r.rank, r.firm, r.value → 渲染實動戶數榜
});
data.wealth.forEach(r => {
  // r.rank, r.firm, r.value → 渲染財富累積榜
});

資料由後台「設定 → 富翁戰況速報 Cache → 券商排行」每日刷新；前台讀 cache，不即時打 DB。

③ 分享集點 API（遊戲分享 / 下載）

前台遊戲分享流程的集章端點。分享章需「分享 share」+「下載 download」兩個動作都完成才計 1 點，順序不限。

端點

動作	方法	路徑
分享	POST	`/api/v1/members/collect-stamp/share`
下載	POST	`/api/v1/members/collect-stamp/download`

公開端點，無需登入 / token。正式站把網域換成對應環境（路徑固定 /api/v1/members/collect-stamp/{share|download}）。

請求

// Content-Type: application/json
{ "id_number": "A123456789" }

id_number（必填）：身分證字號 / 居留證號，需通過格式驗證、且該人已完成報名，否則回 422。

回傳

// 成功 200
{ "data": [] }

// 驗證失敗 422
{ "error": { "errors": { "id_number": ["無此報名資料、報名失敗，或尚未完成報名"] } } }

// 缺欄位 422
{ "error": { "errors": { "id_number": ["身分證字號為必填欄位"] } } }

前端注意：

分享流程要分別打 share 與 download 兩支；兩者齊備才會 +1 點。
冪等：同一動作重複打不重複計（記錄首次完成時間）。
成功一律回 {"data":[]}，不能靠回傳判斷是否已計點；查點數請打 POST /api/v1/members/query/stamp。

curl 範例

curl -X POST https://<網域>/api/v1/members/collect-stamp/share \
  -H "Content-Type: application/json" -d '{"id_number":"A123456789"}'

curl -X POST https://<網域>/api/v1/members/collect-stamp/download \
  -H "Content-Type: application/json" -d '{"id_number":"A123456789"}'

④ 富翁戰況速報原始 API

短碼背後的資料來源端點（一般情況前端用短碼即可；此處供需要直接串接者參考）。

端點

GET /api/v1/lottery/winner/firms-status ＜公開＞

可選參數 ?top=N（每榜取前 N 名，預設 3）。
實動戶數＝單一帳號累計總買入 ≥ 2000 計為一戶（與券商獎口徑一致）；財富累積＝該券商所有帳號總買入金額加總。
僅納入本屆參賽券商。

回傳

{
  "meta": { "top":3, "total":8, "created":"2026-07-25 06:00:12" },
  "active_accounts": [ { "rank":1, "firm":"元大證券", "value":219 }, … ],
  "wealth":          [ { "rank":1, "firm":"凱基證券", "value":4227299800 }, … ]
}

短碼輸出 = 此回傳的 active_accounts / wealth ＋ updated_at（取自 meta.created）。