---
name: API 技術規格與通訊協議規範
description: 本技能規範定義了 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 (登入)。
- **方式**：使用 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 需帶入機台 API Token 進行認證。

- **URL**: POST /api/v1/app/admin/login/B000
- **Authentication**: Bearer Token (Header)
- **Headers**:
    - `Content-Type: application/json`
    - `Authorization: Bearer <api_token>`
- **Request Body:**

| 參數 | 類型 | 必填 | 說明 | 範例 |
| :--- | :--- | :--- | :--- | :--- |
| Su_Account | String | 是 | 系統管理員或公司管理員帳號 | admin |
| Su_Password | String | 是 | 密碼 | password123 |
| ip | String | 否 | 機台本地 IP | 192.168.1.100 |

- **Response Body:**

| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| success | Boolean | 請求是否成功 | true |
| code | Integer | 業務狀態碼 | 200 |
| message | String | 驗證結果 (Success 或 Failed) | Success |
| token | String | **臨時身份認證 Token** (可選，供未來擴充使用) | 1\|abcdefg... |

---

### 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:**

| 參數 | 類型 | 必填 | 說明 | 範例 |
| :--- | :--- | :--- | :--- | :--- |
| account | String | 是 | 執行補貨的人員帳號 (Username 或 Email)，用於權限驗證 | admin |
| data | Array/Object | 是 | 貨道數據陣列 (若傳單一物件會自動相容為陣列) | [{"tid": "1", "t060v00": "1", "num": 10, "type": 1}] |

- **data 陣列內部欄位：**

| 欄位 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| tid | String | 貨道編號 (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 |

- **Response Body (Failed 403 - 權限不足):**

| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| success | Boolean | 請求是否成功 | false |
| code | Integer | HTTP 狀態碼 | 403 |
| message | String | 失敗原因 | Unauthorized: Account not found |

---


### 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 硬體代碼對照表](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#32-異常與錯誤上報-b013)

### 3.7 B014: 機台參數與金鑰下載 (Config Download)
用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。

- **URL**: GET /api/v1/app/machine/setting/B014
- **Authentication**: None (由 Query String 帶入 `machine` 參數識別)
- **Request Body:** 無

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

- **Response Body (Success 200 - Object):**

| 欄位 (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 |

---

### 3.9 B660: 取貨碼驗證 (Pickup Code)
處理機台端的 8 位數代碼取貨流程。

- **URL**: POST /api/v1/app/machine/pickup/verify/B660
- **Authentication**: Bearer Token (Header)
- **運作模式**:
    - **POST (驗證)**: 提交 `code` 驗證。成功後回傳 `pickup_code_id` 與建議 `slot_no`。
    - **消耗機制**: 出貨完成後，由機台發送 MQTT `finalize` 訊息，並在 `payment_type` 帶入 `6` (取貨碼) 完成扣減。

| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| code | String | 8 位數取貨碼 | "12345678" |

---

### 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"。

---

### 3.11 B680: 員工卡身分驗證 (Staff Card Verification)
機台端感應員工卡 (RFID/NFC) 後驗證卡片 UID。

- **URL**: POST /api/v1/app/machine/staff/verify/B680
- **Authentication**: Bearer Token (Header)
- **Request Body:**

| 參數 | 類型 | 必填 | 說明 | 範例 |
| :--- | :--- | :--- | :--- | :--- |
| code | String | 是 | 卡片 UID 碼 | "A1B2C3D4" |

**Response (Success 200):**
- `name`: 員工姓名。
- `code_id`: 員工卡 ID (用於 MQTT 交易關聯)。
- `status`: "active"。

> [!WARNING]
> **鎖定機制**：B660, B670, B680 與 B690 若連續錯誤 5 次，該機台將被鎖定驗證功能 1 分鐘。

---

### 3.12 B690: 來店禮驗證 (Welcome Gift Verify)
處理機台端的 8 位數來店禮代碼驗證。成功後回傳折扣資訊供機台端套用折扣。

- **URL**: POST /api/v1/app/machine/welcome-gift/verify/B690
- **Authentication**: Bearer Token (Header)
- **Request Body:**

| 參數 | 類型 | 必填 | 說明 | 範例 |
| :--- | :--- | :--- | :--- | :--- |
| code | String | 是 | 8 位數來店禮代碼 | "12345678" |

**Response (Success 200):**

| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| success | Boolean | 請求是否成功 | true |
| code | Integer | 業務狀態碼 | 200 |
| data.name | String | 來店禮名稱 | 新客八五折 |
| data.code_id | Integer | 來店禮 ID (用於 MQTT 交易關聯) | 12 |
| data.discount_type | String | 折扣類型 (percentage / amount) | percentage |
| data.discount_value | Integer | 折扣趴數 (如 15 代表 15% off) 或折扣金額 | 15 |
| data.discount_label | String | 台灣中文折數標籤 (如「八五折」、「折 50 元」) | 八五折 |
| data.usage_type | String | 使用類型 (once / unlimited) | once |
| data.status | String | 狀態 | active |

**Response (Failed 404):**

| 參數 | 類型 | 說明 | 範例 |
| :--- | :--- | :--- | :--- |
| success | Boolean | 請求是否成功 | false |
| message | String | 失敗原因 | Invalid or expired code |
| code | Integer | 業務狀態碼 | 404 |
| remaining_attempts | Integer | 剩餘嘗試次數 | 3 |

- **消耗機制**: 出貨完成後，由機台發送 MQTT `finalize` 訊息，並在 `payment_type` 帶入 `7` (來店禮) 完成扣減。

---

### 3.14 B027: 贈品碼/優惠券驗證 (Free Gift Verify)
用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。

- **URL**: POST /api/v1/app/sell/free-gift/B027
- **Authentication**: Bearer Token (Header)
- **運作模式**:
    - **POST**: 提交 `passCode` 驗證。成功後雲端會回傳對應活動 ID 與商品配置。
    - **消耗機制**: 出貨完成後，由機台發送 MQTT `finalize` 訊息進行消耗。

---

### 3.15 B650: 會員身分驗證 (Member Verification)
機台端掃碼後驗證會員身分。

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

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




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

以下端點的 HTTP REST API 已廢棄，改為透過 MQTT 即時通訊架構處理。詳細的 Payload 定義請參閱 [MQTT 通訊規範](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md)。

| 原 API 代碼 | 名稱 | MQTT Topic | 備註 |
| :--- | :--- | :--- | :--- |
| B010 | 心跳上報 | `machine/{serial_no}/heartbeat` | [已遷移](#312-b010-deprecated--removed-心跳上報與狀態同步) |
| B013 | 異常上報 | `machine/{serial_no}/error` | [已遷移](#36-b013-deprecated--removed-機台故障與異常狀態上報) |
| 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` |
| [New] | 商品同步指令 | `machine/{serial_no}/command` | `command: update_products` |
| B055 (PUT) | 遠端出貨回報 | `machine/{serial_no}/command/ack` | GET 查詢路由保留 |

---

## 附錄 (Appendix)

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

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

| 代碼 | 支付方式 | 備註 / 說明 |
| :--- | :--- | :--- |
| `1` | 信用卡 | 一般實體信用卡刷卡 |
| `2` | 電子票證 | 包含悠遊卡、一卡通等 |
| `3` | 掃碼支付 | 一般掃碼支付 |
| `4` | 投幣機支付 | 實體紙鈔機 |
| `5` | 通行碼 | 現場維護人員測試使用 |
| `6` | 取貨碼 | 包含 8 位數取貨碼與 0 元贈品碼 |
| `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` | 會員驗證取貨商品 | |
| `41` | 員工卡 | RFID / NFC 刷卡 |
| `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 |
