df3c72e927
1. 刷卡機共用判定：信用卡(1)、電子票證(2)、手機支付(10) 走同一台實體刷卡機，以交易結果維護燈號（刷卡機無斷線心跳）。 2. ProcessTransactionFinalized 新增 syncCardTerminalStatus：成功交易自動消除該機台未解決的 card_terminal 警告；失敗交易解析 payment_response 的 "| code=XXXX" 回應碼，寫一筆 type='card_terminal' 的 warning 日誌（warning 級不觸發 Discord）。 3. MachineService 新增 CARD_TERMINAL_CODE_MAP（NCCC/聯卡中心回應碼對照，值為英文翻譯鍵）；MachineLog 依 card_code 重組多語可讀失敗原因。 4. Machine 模型新增 card_terminal_status 與 latest_card_terminal_log_time 取值器；MachineController 列表以 withCount + 相關子查詢預載彙總，避免 N+1。 5. 機台列表頁新增「刷卡機」狀態燈號（綠/琥珀/紅 + 最近異常時間）與「刷卡機日誌」分頁。 6. 文件更新：config/api-docs.php 與 api-technical-specs SKILL.md 補充 payment_type 說明（2/10 與 1 共用同一台刷卡機、補列 42 取物單與 100 遠端出貨）。 7. 既有 migration change_products_spec_to_text 加 sqlite 守衛，讓測試環境可跑（VARCHAR/TEXT 在 sqlite 等價且不支援 MODIFY）。 8. 新增 CardTerminalStatusTest 功能測試（18 斷言通過，涵蓋成功消警、失敗寫日誌、掃碼排除、多語訊息、N+1 預載路徑）。 9. 新增 25 組三語系 key（刷卡機狀態與回應碼），zh_TW/en/ja 對齊並 ksort 排序。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
441 lines
23 KiB
Markdown
441 lines
23 KiB
Markdown
---
|
||
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 |
|
||
| identity | String | **登入者身分**：`system` 系統登入者 / `company` 公司帳號 / `staff` 一般人員。僅驗證成功時回傳 | system |
|
||
| 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 | 商品名稱（預設語系 zh_TW） | 可口可樂 330ml |
|
||
| t060v01_en | String | 英文名稱（**既有欄位，保留相容**） | Coca Cola |
|
||
| t060v01_jp | String | 日文名稱（**既有欄位，保留相容**） | コカコーラ |
|
||
| t060v01_i18n | Object | **【新增】名稱多語系 map**（locale → 名稱），key 集合 = 公司機台語系聯集；缺翻譯回退 zh_TW | {"zh_TW":"可口可樂","en":"Coca Cola","ja":"コカコーラ"} |
|
||
| t060v03 | String | 商品規格/簡述（預設語系 zh_TW） | Cold Drink |
|
||
| t060v03_i18n | Object | **【新增】規格多語系 map**（locale → 規格），同 `t060v01_i18n` 邏輯 | {"zh_TW":"330ml","en":"330ml","ja":"330ml"} |
|
||
| 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 |
|
||
|
||
> **多語系 (i18n) 說明**：
|
||
> - **向下相容鐵則**：`t060v01` / `t060v01_en` / `t060v01_jp` / `t060v03` 等既有欄位一律**保留**，本次僅**新增** `t060v01_i18n`、`t060v03_i18n` 兩個 map。線上舊 App 忽略新欄位、照舊運作。
|
||
> - **`*_i18n` 的 key 集合 = 公司所有機台已開語系的聯集**（後台於機台系統設定勾選，最多 5 種／台；可選池子見 `config/locales.php`）。缺翻譯時回退 zh_TW，不下發空字串。
|
||
> - **App 改版方向**：新版 App 改讀 `t060v01_i18n`/`t060v03_i18n` 以支援多語切換，並依 B014 的 `LangSet` 決定要顯示哪些語系。改版前現行 App 僅顯示 zh_TW/en/ja。
|
||
> - 完整設計見 [商品多語系與機台顯示語系技術規範](file:///home/mama/projects/star-cloud/docs/API/product_multilingual_spec.md)。
|
||
|
||
---
|
||
|
||
### 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 |
|
||
|
||
- **資料來源**: 所有金流密鑰與電子發票設定，均取自機台關聯的「金流配置 (`payment_configs.settings`)」巢狀結構；機台須先在後台關聯一組金流配置 (`machines.payment_config_id`)，未設值欄位回傳空字串 `""`。
|
||
- **Response Body (Success 200 - Object):**
|
||
|
||
| 欄位 (Key) | 說明 | 來源 (payment_configs.settings) |
|
||
| :--- | :--- | :--- |
|
||
| **t050v01** | 機台序號 | machines.serial_no |
|
||
| **api_token** | **機台正式 Token** | machines.api_token（初始化後存本地，後續認證用）|
|
||
| **t050v41** | 玉山特店編號 | `esun_scan.store_id` |
|
||
| **t050v42** | 玉山終端編號 | `esun_scan.term_id` |
|
||
| **t050v43** | 玉山 Hash Key | `esun_scan.key` |
|
||
| **t050v34** | 發票特店 ID | `ecpay_invoice.store_id` |
|
||
| **t050v35** | 發票 Hash Key | `ecpay_invoice.hash_key` |
|
||
| **t050v36** | 發票 Hash IV | `ecpay_invoice.hash_iv` |
|
||
| **t050v38** | 發票通知 Email | `ecpay_invoice.email` |
|
||
| **TP_APP_ID** | 趨勢/TapPay AppID | `tappay.app_id` |
|
||
| **TP_APP_KEY** | 趨勢/TapPay Key | `tappay.app_key` |
|
||
| **TP_PARTNER_KEY** | TapPay Partner Key | `tappay.partner_key` |
|
||
| **TP_LINE_MERCHANT_ID** | LINE Pay 特店 ID | `tappay.line_merchant_id` |
|
||
| **TP_JKO_MERCHANT_ID** | 街口支付 特店 ID | `tappay.jko_merchant_id` |
|
||
| **TP_PI_MERCHANT_ID** | Pi 拍錢包 特店 ID | `tappay.pi_merchant_id` |
|
||
| **TP_PS_MERCHANT_ID** | 全盈+Pay 特店 ID | `tappay.ps_merchant_id` |
|
||
| **TP_EASY_MERCHANT_ID** | 悠遊付 特店 ID | `tappay.easy_merchant_id` |
|
||
| **DevSet** | 支付旗標物件（命名沿用機台 `DevSetStructure`）| 機台既有：`ShoppingCar`(shopping_cart_enabled)/`Invoice`(tax_invoice_enabled)/`DevNFCPay`(card_terminal_enabled)/`DevEsunPay`(scan_pay_esun_enabled)/`DevTapPay`(scan_pay_tappay_enabled)/`DevCash`(cash_module_enabled)/`DevLinePay`(scan_pay_linepay_enabled LINE Pay 官方直連)/`TapPay30`(tappay_linepay TapPay 底下 LINE Pay)/`TapPay31`(tappay_jkopay 街口)/`TapPay32`(tappay_easywallet 悠遊付)/`TapPay33`(tappay_pipay)/`TapPay34`(tappay_pluspay 全盈+)。**新定義**(機台待新增欄位)：`DevCreditCard`(credit_card_enabled)/`DevMobilePay`(mobile_pay_enabled)/`DevCardPay`(card_pay_enabled)/`DevScanPay`(scan_pay_enabled)。`VMC`/`Electic` 雲端不下發。註：LINE Pay 有兩條路線 —— `DevLinePay`=官方直連、`TapPay30`=經 TapPay，兩者來源不同|
|
||
| **CashSet** | 現金面額旗標物件（對齊 `CashSetStructure`）| machines.settings → `BillF1000`/`BillE500`/`BillD100`/`CoinF50`/`CoinE10`/`CoinD5`/`CoinC1` |
|
||
| **FunctionSet** | 非支付功能模組旗標物件（**新定義**，機台待實作）| machines.settings → `PickupModule`(pickup_module_enabled)/`PickupCode`(pickup_code_enabled)/`PassCode`(pass_code_enabled)/`WelcomeGift`(welcome_gift_enabled)/`MemberSystem`(member_system_enabled)/`AmbientTemp`(ambient_temp_monitoring_enabled) |
|
||
| **ShoppingMode** | 購物方式（字串，**新定義**）| machines.settings.shopping_mode：`basic` / `employee_card` / `pickup_sheet` |
|
||
| **LangSet** | 機台顯示語系（**新定義**，最多 5 種）| machines.settings.languages → `Languages`(有序語系陣列，如 `["zh_TW","en","ja"]`，順序即切換順序)／`Default`(預設語系=清單第一個)。未設定時退化為 `[fallback]`。機台據此渲染語系切換 UI。可選語系池子見 `config/locales.php` |
|
||
| **OperationSet** | 運作參數（**新定義**，來源 machines 實體欄位）| `CardReaderSeconds`(card_reader_seconds 整數)/`PaymentBufferSeconds`(payment_buffer_seconds 整數)/`CheckoutTime1`(card_reader_checkout_time_1 時間字串)/`CheckoutTime2`(card_reader_checkout_time_2)/`HeatingStartTime`(heating_start_time)/`HeatingEndTime`(heating_end_time) |
|
||
| **HardwareSet** | 硬體與貨道（**新定義**，來源 machines 實體欄位）| `CardReaderNo`(card_reader_no 字串)/`SpringSlot1_10`~`SpringSlot51_60`(is_spring_slot_* 布林，true=彈簧 / false=履帶) |
|
||
|
||
> 註：
|
||
> - 金流密鑰／發票來源已由「公司設定 (companies.settings)」改為「金流配置 (payment_configs.settings)」，並新增 `t050v38` 發票通知 Email。
|
||
> - 機台系統設定全部以機台端 `*Set` + PascalCase 風格下發（`DevSet`/`CashSet`/`FunctionSet`/`ShoppingMode`/`OperationSet`/`HardwareSet`），不再有原始 key 雜燴物件。`DevSet`/`CashSet` 對齊機台既有結構；其餘（含 `DevCreditCard/DevMobilePay/DevCardPay/DevScanPay`、`FunctionSet`、`ShoppingMode`、`OperationSet`、`HardwareSet`）為新定義，機台 App 端需另案新增對應結構與消費邏輯。旗標/設定來源為 `machines.settings`，運作參數與硬體貨道來源為 machines 實體欄位。
|
||
|
||
---
|
||
|
||
### 3.8 B016: 機台系統設定回寫 (Settings Write-back)
|
||
機台主控台由**系統方**設定硬體貨道類型後，將貨道開關狀態回寫雲端。為 B014 下載的反向操作。
|
||
|
||
- **URL**: PATCH /api/v1/app/machine/setting/B016
|
||
- **Authentication**: **User Token (Sanctum)** — 帶入 B000 核發之 `Authorization: Bearer <user_token>`，且**僅系統管理員 (`identity=system`)** 可操作；非系統方一律 403。
|
||
- **Headers**:
|
||
- `Content-Type: application/json`
|
||
- `Authorization: Bearer <user_token>`
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| machine | String | 是 | 機台序號 (serial_no) | SN202604130001 |
|
||
| settings | Object | 是 | 貨道類型鍵值物件，鍵名採**後端原始 snake_case**。只覆寫有送來的鍵，其餘保留 | {"is_spring_slot_1_10": true} |
|
||
|
||
> [!IMPORTANT]
|
||
> **僅硬體貨道**：機台端 B016 現在**只回寫硬體貨道類型** (`is_spring_slot_*`)。支付旗標、現金面額、功能模組等系統設定純由**後台單向決定**，B016 **不再接收**，未列入下列白名單者一律忽略。
|
||
|
||
- **可回寫鍵（settings 之下，皆為布林）：**
|
||
- 貨道類型（machines 實體欄位）：`is_spring_slot_1_10`、`is_spring_slot_11_20`、`is_spring_slot_21_30`、`is_spring_slot_31_40`、`is_spring_slot_41_50`、`is_spring_slot_51_60`（true=彈簧 / false=履帶）
|
||
|
||
- **Response Body (Success 200):**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 是否成功 | true |
|
||
| code | Integer | 業務狀態碼 | 200 |
|
||
| message | String | 回應訊息 | Settings updated successfully. |
|
||
|
||
- **錯誤回應：**
|
||
|
||
| HTTP | 情境 | message |
|
||
| :--- | :--- | :--- |
|
||
| 403 | 非系統管理員 / 未登入 | Forbidden |
|
||
| 404 | 查無該序號機台 | Machine not found |
|
||
| 422 | `settings` 非物件/陣列，或未含任何有效貨道鍵 | Invalid settings payload |
|
||
|
||
> 註：寫回時更新 `is_spring_slot_*` 實體欄位並記錄 `updater_id`。為 system-admin 專用，套用 `withoutGlobalScopes` 跨租戶定位機台。
|
||
|
||
---
|
||
|
||
### 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 |
|
||
|
||
**Response (Failed 400 — 格式錯誤):**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否成功 | false |
|
||
| message | String | 失敗原因 (code 非 8 位數) | Invalid format |
|
||
| code | Integer | 業務狀態碼 | 400 |
|
||
|
||
**Response (Failed 429 — 已鎖定):**
|
||
|
||
連續錯誤達 5 次後，該機台於鎖定期間 (60 秒) 內的所有驗證請求皆回傳此回應。
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否成功 | false |
|
||
| message | String | 失敗原因 | Too many attempts. Locked. |
|
||
| code | Integer | 業務狀態碼 | 429 |
|
||
|
||
- **消耗機制**: 出貨完成後，由機台發送 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` | 電子票證 | 包含悠遊卡、一卡通、iCash 等（與信用卡、手機支付共用同一台實體刷卡機）|
|
||
| `3` | 掃碼支付 | 一般掃碼支付 |
|
||
| `4` | 投幣機支付 | 實體紙鈔機 |
|
||
| `5` | 通行碼 | 現場維護人員測試使用 |
|
||
| `6` | 取貨碼 | 包含 8 位數取貨碼與 0 元贈品碼 |
|
||
| `7` | 來店禮 | |
|
||
| `8` | 問卷 | |
|
||
| `9` | 零錢 | 硬幣投幣機 |
|
||
| `10` | 手機支付 | NFC 手機感應（行動支付，走信用卡軌道，依使用者按鈕分類） |
|
||
| `21` ~ `25` | 線下付款 + X | `21`=線下+1, `22`=線下+2... `25`=線下+9 |
|
||
| `30` | TapPay - LINE Pay | TapPay 底下的 LINE Pay |
|
||
| `31` | TapPay - 街口支付 | |
|
||
| `32` | TapPay - 悠遊付 | |
|
||
| `33` | TapPay - Pi 拍錢包 | |
|
||
| `34` | TapPay - 全盈+PAY | |
|
||
| `40` | 會員驗證取貨商品 | |
|
||
| `41` | 員工卡 | RFID / NFC 刷卡 |
|
||
| `42` | 取物單 | |
|
||
| `50` ~ `54` | 線下付款 + TapPay | `50`=線下+30, `51`=線下+31... `54`=線下+34 |
|
||
| `70` | LINE Pay（官方直連） | LINE Pay 官方直連，非 TapPay 底下的 `30` |
|
||
| `60` | 點數 / 優惠卷全額折抵 | 點數全額折抵出貨 或 優惠卷全額折抵出貨 |
|
||
| `61` ~ `69` | 會員 + X | `61`=會員+1, `62`=會員+2... `69`=會員+9 |
|
||
| `90` ~ `94` | 會員 + TapPay | `90`=會員+30, `91`=會員+31... `94`=會員+34 |
|
||
| `100` | 遠端出貨 | 後台遠端觸發出貨 |
|