[DOCS] 補齊 B024, B027, B055 API 技術規格與文檔定義

1. 更新技術手冊 (SKILL.md) 與 API 規格文件 (api-docs.php)，補齊 B024, B027, B055 之定義。
2. 修正文件序號跳號問題，確保 B017 序號正確銜接。
3. 詳細說明 B055 之指令 ID 遠端出貨運作機制。

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

@@ -265,12 +265,9 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 用於機台端獲取目前所有貨道的最新庫存、效期與狀態。通常由 B010 回應 `status: 49` 觸發。
 
 - **URL**: GET /api/v1/app/machine/reload_msg/B017
-- **Authentication**: Bearer Token (Header) 或 API Key (Body/Query)
+- **Authentication**: Bearer Token (Header)
 - **Request Body:** 無 (由 Token 自動識別機台)
 
-| 參數 | 類型 | 必填 | 說明 | 範例 |
-| :--- | :--- | :--- | :--- | :--- |
-
 - **Response Body:**
 
 | 參數 | 類型 | 說明 | 範例 |
@@ -293,3 +290,67 @@ description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與
 
 > [!IMPORTANT]
 > **同步機制**：B017 為全量同步。App 收到回應後應更新本地資料庫對應貨道的數值。成功請求後，雲端會自動將相關的 `reload_stock` 指令標記為 `success`。
+
+---
+
+### 3.9 B024: 取貨碼/通行碼驗證與消耗回報 (Access Code Verify & Report)
+用於處理機台端的代碼取貨流程。包含驗證代碼有效性（驗證階段）與確認出貨完成後的狀態消耗（回報階段）。
+
+- **URL**: POST|PUT /api/v1/app/sell/access-code/B024
+- **Authentication**: Bearer Token (Header)
+- **Request Body (POST - 驗證階段):**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| passCode | String | 是 | 使用者輸入的取貨碼/通行碼 | "12345678" |
+
+- **Response Body (POST - 驗證成功 200):**
+雲端將回傳該碼對應的權限或待出貨商品資訊。
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| res1 | String | 該代碼在雲端的關聯 ID | "99" |
+| res2 | String | 操作模式 (1: 出貨, 2: 僅驗證) | "1" |
+| res3 | String | 預計出貨商品 ID | "5" |
+| res4 | String | 折扣金額或活動標籤 | "0.0" |
+
+- **Request Body (PUT - 回報階段):**
+當機台端確認實體出貨成功後，必須發送此請求以耗刷該代碼。
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| accessCodeId | String | 是 | 驗證階段取得的 res1 (ID) | "99" |
+| status | String | 是 | 出貨結果 (1: 成功, 0: 失敗) | "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 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。
+
+> [!NOTE]
+> B027 與 B024 的邏輯具備高度對稱性，區別在於 B027 通常綁定的是特定的行銷活動 (Campaign) 與 0 元出貨邏輯。
+
+---
+
+### 3.11 B055: 遠端指令出貨控制 (Remote Dispense / Force Open)
+用於遠端手動驅動機台出貨。通常用於補償使用者、測試機台或客服協助開門的情景。
+
+- **URL**: POST|PUT /api/v1/app/machine/dispense/B055
+- **Authentication**: Bearer Token (Header)
+- **運作模式**:
+    - **POST (查詢)**: 當 B010 收到 `status: 85` 時呼叫。雲端會回傳待執行的貨道編號與指令 ID。
+    - **PUT (回報)**: 實體出貨完成後回報結果，以便雲端將該指令標記為「已執行」。
+
+- **Request Body (PUT - 回報階段):**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| id | String | 是 | 雲端下發的指令 ID | "20260414001" |
+| type | String | 是 | 出貨類型代碼 (通常為 0) | "0" |
+| stock | String | 是 | 出貨後的貨道剩餘數量 | "9" |