star-cloud/.agents/skills/api-technical-specs/SKILL.md

name	description
API 技術規格與通訊協議規範	本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與後端 (Cloud) 通訊的 API 細節、參數命名規則、狀態代碼對照與認證機制，作為系統開發的唯一規格來源。

API 技術規格與通訊協議規範 (API Technical Specs)

本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。

1. 核心命名原則

• 語意化優先：捨棄舊版 M_ 前綴，統一使用 snake_case (如 firmware_version)。
• 類型嚴格：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。

2. 身份認證 (Authentication)

本系統採用兩階段認證模式：

2.1 維運人員認證 (User Authentication)

• 核發端點：B000 (登入)。
• 使用端點：B014 (參數下載)。
• 方式：使用 Laravel Sanctum 核發之 User Token。
• Header：Authorization: Bearer <user_token>。

2.2 機台通訊認證 (Machine Authentication)

• 適用 API：B012, B009 等後續通訊。
• 方式：使用機台專屬之 api_token。
• Header：Authorization: Bearer <api_token>。

---

3. 機台核心 API (IoT Endpoints)

3.1 B000: 機台本地管理員同步登入

用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。

• URL: POST /api/v1/app/admin/login/B000
• Request Body:

參數	類型	必填	說明	範例
machine	String	是	機台編號 (serial_no)	M-001
Su_Account	String	是	系統管理員或公司管理員帳號	admin
Su_Password	String	是	密碼	password123
ip	String	否	用戶端 IP (相容舊版)	192.168.1.100
type	String	否	裝置類型代碼 (相容舊版)	2

• Response Body:

Important

為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 Success。

參數	類型	說明	範例
message	String	驗證結果 (Success 或 Failed)	Success
token	String	臨時身份認證 Token (用於 B014)	1

---

3.2 B005: 廣告清單同步

用於機台端獲取目前應播放的廣告檔案 URL 清單。

• URL: GET /api/v1/app/machine/ad/B005

• Request Body: 無 (GET 請求)

• Response Body:

參數	類型	說明	範例
success	Boolean	請求是否成功	true
code	Integer	內部業務狀態碼	200
data	Array	廣告物件陣列	[{"t070v04": "https://..."}]

data 陣列內部欄位：

• t070v01: 廣告名稱 (Name)
• t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
• t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
• t070v04: 廣告 URL。
• t070v05: 播放順位 (Sort Order)。

---

3.3 B009: 貨道庫存即時回報 (Supplementary Report)

當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。

• URL: PUT /api/v1/app/products/supplementary/B009
• Authentication: Bearer Token (Header)
• Request Body: 無 (由 Token 自動識別機台)

參數	類型	必填	說明	範例
data	Array	是	貨道數據陣列	[{"tid":"1", "t060v00":"1", "num":"10"}]

• data 陣列內部欄位：

欄位	類型	說明	範例
tid	Integer	貨道編號 (Slot No)	1
t060v00	String	商品資料庫 ID (或是 Barcode)	"1"
num	Integer	實體剩餘庫存數量	10
type	Integer	貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。	1

Tip

自動化上限同步邏輯： 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。

• Response Body (Success 200):

參數	類型	說明	範例
success	Boolean	同步是否成功	true
code	Integer	內部業務狀態碼	200
message	String	回應訊息	Slot report synchronized success
status	String	固定回傳 49 代表同步完成	"49"

---

3.5 B012: 商品配置與商品主檔同步 (Unified Sync)

用於機台端獲取目前所有可販售商品的詳細配置。

• URL: GET /api/v1/app/machine/products/B012
• Authentication: Bearer Token (Header)
• Request Body: 無 (由 Token 自動識別機台)

運作邏輯 (Client-side Logic):

• GET：執行 全量同步。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
• PATCH：執行 增量更新。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。

欄位	型別	說明	範例
t060v00	String	商品資料庫 ID	"1"
t060v01	String	商品名稱	可口可樂 330ml
t060v01_en	String	英文名稱	Coca Cola
t060v01_jp	String	日文名稱	コカコーラ
t060v03	String	商品規格/簡述	Cold Drink
t060v06	String	圖片 URL	https://.../coke.png
t060v09	Float	標準零售價	25.0
t060v11	Integer	貨道庫存上限 (預設履帶)	10
t060v30	Float	會員價	20.0
t063v03	Float	本機銷售價格 (同定價)	25.0
t060v40	String	行銷計畫 (Marketing Plan)	Buy 1 Get 1
t060v41	String	物料編碼 (Material Code)	SKU-001
spring_limit	Integer	彈簧貨道上限 (建議使用此欄位)	10
track_limit	Integer	履帶貨道上限 (建議使用此欄位)	15

---

3.6 B013: [DEPRECATED / REMOVED] 機台故障與異常狀態上報

Warning

此 REST API 已廢棄並移除。機台異常上報已全面遷移至 MQTT 即時通訊架構。 詳細錯誤代碼請參閱：MQTT 通訊規範 - B013 硬體代碼對照表

3.12 B010: [DEPRECATED / REMOVED] 心跳上報與狀態同步

Warning

此 REST API 已廢棄並移除。機台心跳上報與指令下發已全面遷移至 MQTT 架構。 (註：溫度數據已標準化為 Integer，且雲端採「變動即記錄」規則)。 詳細格式請參閱：MQTT 通訊規範 - B010 心跳上報

---

3.7 B014: 機台參數與金鑰下載 (Config Download)

用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。

• URL: GET /api/v1/app/machine/setting/B014
• Authentication: User Token (Sanctum Header)
• Request Body: 無 (由 Query String 帶入 machine 參數)

參數	類型	必填	說明	範例
machine	String	是	機台編號 (serial_no)	M-001

• Response Body (Success 200):

欄位 (Key)	說明	備註
t050v01	機台序號	即 machine_id
api_token	機台正式 Token	初始化後應存於本地，後續 API 認證用
t050v41	玉山特店編號	ESUN Merchant ID
t050v42	玉山終端編號	ESUN Terminal ID
t050v43	玉山 Hash Key	ESUN Hash
t050v34	發票特店 ID	Invoice Merchant ID
t050v35	發票 Hash Key	Invoice Key
t050v36	發票 Hash IV	Invoice IV
TP_APP_ID	趨勢支付 AppID	TrendPay ID
TP_APP_KEY	趨勢支付 Key	TrendPay Key

Caution

安全性規範：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。

---

3.8 B017: 貨道庫存同步 (Slot Synchronization)

用於機台端主動向遠端後台拉取目前所有貨道的最新庫存、效期與配置狀態。通常發生於機台開機初始化、補貨/維護模式結束，或是機台需要確保本地端庫存資料與雲端一致時主動請求。

• URL: GET /api/v1/app/machine/reload_msg/B017

• Authentication: Bearer Token (Header)

• Request Body: 無 (由 Token 自動識別機台)

• Response Body:

參數	類型	說明	範例
success	Boolean	請求是否成功	true
code	Integer	200	200
data	Array	貨道數據陣列 (依 slot_no 排序)	見下表

data 陣列內部欄位：

欄位	類型	說明	範例
tid	String	貨道編號	"1"
num	Integer	當前庫存數量	10
expiry_date	String	商品效期	"2026-12-31"
batch_no	String	批號	"B202604"
product_id	Integer	商品 ID	1
capacity	Integer	貨道容量上限	15
status	String	貨道狀態 ("1": 啟用, "0": 停用)	"1"

---

3.9 B660: 取貨碼驗證與消耗 (Pickup Code)

處理機台端的代碼取貨流程。採用兩階段流程以確保庫存準確性。

[B660] 取貨碼驗證與消耗 (兩階段)

• Path: /api/v1/app/machine/pickup/verify/B660
• Method: POST (驗證) / PUT (消耗)
• Description: 驗證 8 位數取貨碼，並於出貨完成後回報消耗以扣除庫存。

[B670] 通行碼驗證 (維護專用)

• Path: /api/v1/app/machine/passcode/verify/B670
• Method: POST
• Description: 工程人員現場測試專用通行碼，不涉及庫存消耗。

參數	類型	必填	說明	範例
code	String	是	使用者輸入的 8 位數取貨碼	"12345678"

Response (Success 200):

• pickup_code_id: 代碼內部 ID，供第二階段 PUT 使用。
• slot_no: 建議出貨貨道。

B. 消耗階段 (PUT)

當機台確認出貨成功後發送，雲端此時才正式執行 decrement 庫存與標記代碼已使用。

參數	類型	必填	說明	範例
pickup_code_id	Integer	是	驗證階段取得的 ID	45
status	Integer	是	出貨結果 (1: 成功, 0: 失敗)	1

---

3.10 B670: 通行碼驗證 (Pass Code)

專供維修或工程人員現場測試使用的通行碼。

• URL: POST /api/v1/app/machine/passcode/verify/B670
• Authentication: Bearer Token (Header)
• Request Body:

參數	類型	必填	說明	範例
code	String	是	8 位數通行碼	"88888888"

Response (Success 200):

• name: 持有者姓名 (如：維護部 A 員)。
• status: "active"。

Warning

鎖定機制：B660 與 B670 若連續錯誤 5 次，該機台將被鎖定驗證功能 1 分鐘，以防暴力破解。

---

3.10 B027: 贈品碼/優惠券驗證與消耗回報 (Free Gift Verify & Report)

用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。

• URL: POST|PUT /api/v1/app/sell/free-gift/B027
• Authentication: Bearer Token (Header)
• 運作模式:
  • POST: 提交 passCode 驗證該贈品券是否有效。成功後雲端會回傳對應活動 ID 與商品配置。
  • PUT: 當該贈品（0 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。

---

3.11 B650: 會員身分驗證 (Member Verification)

機台端掃碼後驗證會員身分。

• URL: POST /api/v1/app/machine/member/verify/B650
• Authentication: Bearer Token (Header)
• Request Body:

參數	類型	必填	說明	範例
code	String	是	會員代碼	"MEMBER12345"

---

3.12 B710: 機台時間同步 (Timer Sync)

校準機台 RTC 時間。

• URL: POST /api/v1/app/machine/timer/B710
• Authentication: Bearer Token (Header)
• Response: 回傳當前伺服器 Unix Timestamp。

4. 已遷移至 MQTT 的端點索引

以下端點的 HTTP REST API 已廢棄，改為透過 MQTT 即時通訊架構處理。詳細的 Payload 定義請參閱 MQTT 通訊規範。

原 API 代碼	名稱	MQTT Topic	備註
B010	心跳上報	machine/{serial_no}/heartbeat	已廢棄
B013	異常上報	machine/{serial_no}/error	已廢棄
B600	交易建立	machine/{serial_no}/transaction	action: create
B601	發票紀錄	machine/{serial_no}/transaction	action: invoice
B602	出貨結果	machine/{serial_no}/transaction	action: dispense
B600+	交易完成(統整)	machine/{serial_no}/transaction	action: finalize
B055 (PUT)	遠端出貨回報	machine/{serial_no}/command/ack	GET 查詢路由保留

---

附錄 (Appendix)

Appendix A: B600 支付類型對照表 (payment_type)

此對照表依據機台 B600 規格定義，用於解析 order.payment_type：

代碼	支付方式	備註 / 說明
1	信用卡	一般實體信用卡刷卡
2	電子票證	包含悠遊卡、一卡通等
3	掃碼支付	一般掃碼支付
4	投幣機支付	實體紙鈔機
5	通關密碼
6	取貨碼
7	來店禮
8	問卷
9	零錢	硬幣投幣機
21 ~ 25	線下付款 + X	21=線下+1, 22=線下+2... 25=線下+9
30	TapPay - LINE Pay
31	TapPay - 街口支付
32	TapPay - 悠遊付
33	TapPay - Pi 拍錢包
34	TapPay - 全盈+PAY
40	會員驗證取貨商品
50 ~ 54	線下付款 + TapPay	50=線下+30, 51=線下+31... 54=線下+34
60	點數 / 優惠卷全額折抵	點數全額折抵出貨 或 優惠卷全額折抵出貨
61 ~ 69	會員 + X	61=會員+1, 62=會員+2... 69=會員+9
90 ~ 94	會員 + TapPay	90=會員+30, 91=會員+31... 94=會員+34