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 (登入)。
• 方式：使用 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。
• 完整設計見 商品多語系與機台顯示語系技術規範。

---

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

Warning

此 REST API 已廢棄並移除。機台異常上報已全面遷移至 MQTT 即時通訊架構。 詳細錯誤代碼請參閱：MQTT 通訊規範 - 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 通訊規範。

原 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
[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