開洗分 API 介面規格書 (v2.3)

WAW IoT Universal Signal Standard

遊戲商開洗分 API 介面規格說明書

PC-Based 電腦型聯網機台實體通訊、硬體通道定義與雙軌資料協定
文件版本：v2.3.0
發布日期：2026-09-21
介面節點：signal.tg25.win
正式技術規格書 (公開線上版 · 免登入)
🕹️ Mock 對接測試終端 🔔 前往 Webhook 設定 🎛️ 開啟模擬器測試

一、系統架構與介面職責

本規格適用於 PC-Based 聯網型遊戲機台。機台端分數由遊戲商伺服器全面掌控，WAW-USS 採集卡安裝於機台內部，擔任物理接點至數位網路之通訊中繼器。

電腦型 (PC-Based)適用本規格書

遊戲運行於電腦主機，分數控制權與業務結算 100% 由遊戲商雲端伺服器決定。WAW-USS 採集卡為透明邊緣中繼 (Transparent Relay)，只忠實通報按鍵觸發次數與時間戳，不在硬體端換算或介入遊戲業務邏輯；SignalHub 伺服器可依店主後台設定產生參考請求金額。

傳統機板型 (MCU/ROM Board)不適用本規格

投幣脈衝由機板自體加減分並驅動機械表跳號，完全閉環於本機。此類機台不走 SignalHub 開洗分通道，本規格書所述之 Webhook 派送、points_per_pulse 與 actual_points 結算流程均不適用。

現場訊號用途說明
開分／洗分按鍵 服務員收款後按下按鍵，採集卡上報觸發次數與時間戳。SignalHub 將事件派送給遊戲商；遊戲商回傳 actual_points 作為實際開分或洗分結果。
實體計數表 機台若配備入幣或出幣電磁計數表，可由獨立腳位（例如 UI3、UI4）記錄方波增量，供日結、對帳、防弊與審計使用。
系統節點 角色定位 主要職責說明
實體按鈕 / 採集卡 邊緣通訊中繼 (Relay) 偵測現場服務員按鍵動作，將觸發次數與時間戳即時上報。
SignalHub 平台 派送與重試中心 依後台設定之 Webhook URL 向遊戲商 POST 推送；最多三次派送於 0s、3s、6s 啟動，並支援異步狀態閉環。
遊戲商後端 (Game Server) 業務與點數結算核心 接收開洗分通知，控制遊戲機台增減點數，並回傳實際處理點數 (actual_points)。

二、硬體實體介面規格：4組輸入 (4 In) 與 4組輸出 (4 Out)

WAW-USS 工規通訊卡配備 4 路光耦隔離數位輸入通道 (UI1～UI4) 與 4 路隔離控制輸出通道 (UO1～UO4)。各通道在開洗分與機台對接時之標準功能指派如下：

通道 方向 信號模式 預設功能指派 電氣特性與業務功能說明
UI1 Input Counter (計數累加) 服務員開分按鍵 【開分預設腳位】 光耦硬體 PCNT 計數，精準記錄連續按壓次數，連按 3 下即上報 delta_value: 3。通知遊戲商依比例開分，並於回調中接收實際配發點數 actual_points。
UI2 Input Event (事件通知) 服務員洗分按鍵 【洗分預設腳位】 具備短時間自動防抖去重機制，通知遊戲商清算洗分，並於回調接收 actual_points。
UI3 Input Counter / Event 入幣機械跳表 / 門警報 【選配】 若機台裝有實體電磁計數碼表，採集投幣物理跳表脈衝（防弊對帳）；亦可接錢箱開門防盜開關。
UI4 Input Counter / Event 出幣機械跳表 / 備用 【選配】 採集實體退幣跳表脈衝累積值，作為日結與開洗分數據交叉稽核依據。
UO1～UO4 Output 繼電器開關輸出 / 電磁閥控制 外接設備致能與控制 【4路隔離輸出】 可供遠端控制機台電磁鎖、投幣器致能開關（Enable/Inhibit）、警示蜂鳴器或警示燈號。

三、對接前置作業：設定 Webhook 接收端點 (URL)

在機台正式上線前，遊戲商技術人員需先在 SignalHub 平台完成接收端點設定，系統才能在現場按鈕被按下時，將開洗分訊號即時 POST 至遊戲商伺服器。

設定步驟 後台端點配置流程 (前往頂部導航「🔔 Webhooks」頁面)

  1. 提供接收端點 (Webhook URL)：
    遊戲商需備妥一組公開可存取的 HTTPS 端點（例如：https://api.yourgame.com/v1/waw/callback）。
  2. 填入 SignalHub 平台：
    登入 signal.tg25.win ➔ 點選頂部「🔔 Webhooks」➔ 點擊「+ 新增 Webhook」➔ 將您的端點網址貼入「目標 URL」欄位。
  3. 設定簽名金鑰 (Secret Key，安全規範)：
    可自訂或由系統產生安全密鑰。啟用後，SignalHub 每次派送會在 HTTP Header 帶入安全防護與防重放標頭，遊戲商端點務必進行校驗：
    X-WAW-Signature：格式為 sha256={hmac}（注意包含 sha256= 前綴），以整個 HTTP Request Raw Body 作為內容，使用 Secret Key 進行 HMAC-SHA256 計算所得之簽名。
    X-WAW-Timestamp：發送端 Unix 秒級時間戳（如 1725945120）。接收端若發現與本地伺服器差距超過 300 秒（5 分鐘）應予作廢，防範中間人重放攻擊 (Replay Attack)。
    X-WAW-Delivery：唯一推送單號（如 del_10284），與 Body 內之 delivery_id 一致，做為接收端冪等去重鍵 (Idempotency Key)。
  4. 發送測試信號驗證：
    設定完成後，可在 Webhook 列表點擊「測試推送」，平台將立即向該 URL 發送一筆測試訊號，驗證雙方伺服器連線狀態；或直接使用 Mock 對接測試終端 檢視完整收發流程。

四、現場開洗分通道與業務邏輯

4.1 開分通道 (UI1：計數累加型)

服務員連續按壓開分鍵時（例如快速連按 3 次），採集卡 PCNT 硬體計數器將採集全部次數，並於資料包中帶出 "delta_value": 3。遊戲商接收後，依該機台預設之開分比例進行遠端配分（例：每次開分 100 點，3 次即派發 300 點）。配分完成後，遊戲商必須在 HTTP 回應（或 reply_url 回調）中回傳實際派發點數 actual_points（例如 300 點），以供 WAW 後台精準記錄現場營業入金與拆帳對帳。若未回傳實際點數，後台將無法計入營業額。

4.2 洗分通道 (UI2：事件通知型)

服務員按下洗分按鈕時觸發（短時間內重複按壓自動防抖去重，event_type: "event" 且 delta_value: 1）。遊戲商端點接獲通知後，自其資料庫清算該機台當前剩餘分數並執行歸零，隨後在回應中帶回實際扣除的點數 actual_points。若機台當前無分數（0 點），回傳 actual_points: 0 亦屬合法正常回應。

5. API Data Format and Communication Protocol

5.1 Delivery Payload (SignalHub to Game Vendor Webhook URL)

Method: POST / Content-Type: application/json
Headers HTTP Request Headers and Anti-Replay Signature 
POST /api/v1/waw/callback HTTP/1.1
Host: api.yourgame.com
Content-Type: application/json
User-Agent: WAW-SignalHub/1.0
X-WAW-Event: signal.counter
X-WAW-Delivery: del_10284
X-WAW-Timestamp: 1725945120
X-WAW-Signature: sha256={hmac_sha256_signature}
X-WAW-Signature: Format: sha256={hmac}. Calculate from raw request body.
X-WAW-Timestamp: Unix timestamp in seconds. Reject requests with clock drift over 300 seconds.
X-WAW-Delivery: Unique delivery ID for idempotency and duplicate prevention.
X-WAW-Event: signal.counter (credit in) / signal.event (credit out).
{
  "event_id": "evt_982341",
  "delivery_id": "del_10284",
  "chip_id": "C8F09E010004",
  "profile_id": 21,
  "pin_code": "UI1",
  "pin_label": "Credit In Request",
  "event_type": "counter",
  "raw_value": 1582,
  "delta_value": 3,
  "points_per_pulse": 100,
  "amount": 300,
  "reply_url": "https://signal.tg25.win/api/v9/signal-hub/callback-ack?delivery_id=del_10284&token={signed_callback_token}&expires=1725343200",
  "event_at": "2026-09-10T14:32:00.123+08:00",
  "timestamp": "2026-09-10T14:32:00.123+08:00"
}
  • delivery_id: Unique transaction ID. It stays unchanged across up to three delivery attempts started at 0s, 3s, and 6s. Receiver must use it as an idempotency key.
  • chip_id: Bound acquisition-card hardware ID. It is never a SignalHub profile ID or a generated value such as CHIP-33. Configure the actual card ID from Machine Management.
  • reply_url: Dedicated asynchronous callback URL. Use it to submit final processing result when the synchronous response cannot finish in time.
  • delta_value: Trigger count. UI1 credit-in may contain accumulated repeated presses; UI2 credit-out is normally fixed at 1.
  • points_per_pulse: Machine back-office setting for points per pulse, such as 100. SignalHub uses it with the pin pulse_ratio to calculate the server-side reference amount; this is not a hardware conversion.
  • amount: Reference requested points calculated by SignalHub server from delta_value × pulse_ratio × points_per_pulse. Final credit-in or credit-out amount must follow vendor-returned actual_points.
  • UI2 credit-out note: Credit-out uses event_type: "event" and delta_value: 1. If the machine balance is insufficient, vendor-returned actual_points: 0 is a valid response.

5.2 Settlement Result Return Format (Game Vendor to SignalHub)

The receiver may implement either mode according to its own architecture:

Mode A: Synchronous Response (HTTP 200) 
{
  "status": "ack",
  "delivery_id": "del_10284",
  "action": "credited",
  "actual_points": 300,
  "message": "Credited 300 points"
}

Return this JSON body directly in the same HTTP connection within 3 seconds.

Mode B: Asynchronous Callback (POST reply_url) 
{
  "delivery_id": "del_10284",
  "status": "success",
  "action": "cleared",
  "actual_points": 1580,
  "message": "Cleared 1580 points"
}

After background settlement completes, POST this payload to the reply_url included in the request payload.

5.3 Local USB Serial Output Format (Direct Connection to On-Site Cashier PC)

Baud Rate: 115200 / 8-N-1 / Single-line JSON ending with \n
{"channel":"serial","type":"counter","pin":"UI1","action":"credit_in_pressed","chip_id":"C8F09E010004","delta":3,"raw_value":421,"timestamp":1725339600123}

The on-site cashier PC can read serial data directly. chip_id is the bound acquisition-card hardware ID; it must not be substituted with a profile ID or generated simulator ID. Each record ends with the standard newline character \n, has latency under 1ms, and does not depend on external internet connectivity.

5.4 Vendor-Initiated Notification: Player Exit / Points Cleared to Zero (Session End)

Method: POST / Content-Type: application/json

When machine points are consumed to zero (Game Over) or the player exits voluntarily, the game board or server should call SignalHub to record the current machine session-end state and play duration.

Endpoint: POST https://signal.tg25.win/api/v9/signal-hub/inbound/session-end 
{
  "chip_id": "C8F09E010004",
  "machine_number": "M-01",
  "event": "session_end",
  "reason": "points_cleared_to_zero",
  "last_played_duration_seconds": 1840,
  "occurred_at": "2026-09-10T14:45:00+08:00"
}
Request Header: include X-WAW-Secret: {your_webhook_secret} for authentication.
Field Reference:
  • chip_id (required): ESP32 acquisition-card chip identifier.
  • machine_number (optional): on-site machine number, such as M-01.
  • event (required): fixed value session_end.
  • reason (optional): session-end reason, default points_cleared_to_zero.
  • last_played_duration_seconds (optional): accumulated play duration in seconds for the current session.
  • occurred_at (optional): ISO-8601 event timestamp.
Successful Response Example (HTTP 200):
{"success": true, "code": 200, "message": "Machine session-end state recorded", "recorded_at": "2026-09-10T14:45:01+08:00"}

六、現場爭議判定與審計依據

若現場發生加減分爭議，可依據 SignalHub 後台「派送記錄」之日誌狀態進行責任歸屬判定：

日誌記錄狀態 現象說明 責任判定與處理建議
查無記錄 (No Record) 派送日誌無該時段之記錄。 現場硬體問題。實體按鈕接線未導通或光耦未觸發。
200 ACK (成功) Webhook 已送出，遊戲商回簽 actual_points。 通訊正常。伺服器已處理，請檢查遊戲客戶端渲染顯示。
5xx / Expired (逾時失敗) 三次派送（0s、3s、6s）均未收到有效回應。 服務端或網路問題。遊戲商端點異常或外網連線中斷。第三次派送失敗後標記為 Expired，並觸發系統告警。

七、Owner 與 SignalHub 分工表

「機台主（Owner）」與「SignalHub」為兩個獨立系統、各有明確界線。機台主在 iot.tg25.win 完成營運設定，SignalHub 僅負責信號採集與派送；兩者共用同一組平台帳號，但職責不重疊。

分工項目 Owner（iot.tg25.win · 機台主／營運） SignalHub（signal.tg25.win · 信號中心）
核心定位 營運、帳務與分潤中樞 硬體信號採集與 Webhook 派送中樞
帳號與權限 開立／刪除機台主與技術工程師帳號；設定角色與到期日 沿用同一帳號登入；技術工程師可操作所屬機台主名下設備，但看不到營收
機台／場地 場地建檔、機台歸屬、機台主與裝配商關係 呈現已歸屬之設備清單（pc_game 類別）
分潤與計價 負責：一分多少錢、分潤協議、銀行與訂閱 不涉及：不處理金流、分潤與訂閱計費
硬體設定 不處理 GPIO 細節 負責：GPIO 腳位映射、Webhook 端點、Callback、模擬器
資料所有權 營運資料（營收、分潤、訂閱）之主體 信號事件與派送日誌；寫入時 owner_id 一律落在機台主
界線提醒：技術工程師帳號登入 SignalHub 後可設定機台主名下之 GPIO / Webhook / Callback / 模擬器，但不得檢視營收、分潤、銀行與訂閱資料。系統不會、也不應以 SignalHub 帳號跳轉（SSO）至 Owner 營運介面。
WAW Universal Signal Standard (WAW-USS)
技術文件認證代號：SPEC-20260921-V23