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

### 3.12 B010: [DEPRECATED / REMOVED] 心跳上報與狀態同步
> [!WARNING]
> **此 REST API 已廢棄並移除**。機台心跳上報與指令下發已全面遷移至 **MQTT** 架構。
> (註：溫度數據已標準化為 **Integer**，且雲端採「變動即記錄」規則)。
> 詳細格式請參閱：[MQTT 通訊規範 - B010 心跳上報](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#31-心跳上報-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 通訊規範](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` |
| 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 |