star-cloud/docs/api/iot-spec.md

IoT API 測試與對接文件 (IoT API Testing & Documentation)

本文件紀錄 Star Cloud IoT API 的測試紀錄與對接規格，供後續開發與測試追蹤。

---

🔐 B000: 維運人員登入認證 (Technician Login)

機台引導階段 (Provisioning) 的第一步，用於核發臨時身份 Token 以便後續下載敏感設定。

1. API 資訊

• Endpoint: POST /api/v1/app/admin/login/B000
• 認證方式: 無 (需傳入 username, password, machine)
• 回應內容: token (Sanctum Token)

2. 回應範例

{
    "message": "Success",
    "token": "3|abcdef1234567890..."
}

---

🔑 B014: 機台參數與金鑰下載 (Config Download)

下載機台運作所需的支付金鑰、電子發票設定與正式通訊 Token。

1. API 資訊

• Endpoint: POST /api/v1/app/machine/setting/B014
• 認證方式: Bearer Token (需帶上 B000 取得的 Token)
• Header: Authorization: Bearer {token}

2. 請求參數

• machine: 機台序號 (Serial No)

3. 回應規格 (欄位映射)

欄位	說明	來源範例
t050v01	機台序號	SN2026041301
api_token	機台正式 Token	後續 B010/B600 認證用
t050v41	玉山特店編號	ESUN_STORE_ID
t050v43	玉山 Hash Key	ESUN_HASH
t050v34	發票特店 ID	INV_MID
TP_APP_ID	趨勢支付 AppID	TP_APP_ID

4. 回應範例 (JSON)

{
    "success": true,
    "code": 200,
    "data": [
        {
            "t050v01": "SN2026041301",
            "api_token": "mac_token_...",
            "t050v41": "8081234567",
            "t050v42": "9001",
            "t050v43": "password123",
            "t050v34": "2000132",
            "TP_APP_ID": "GREEN_001",
            "...": "..."
        }
    ]
}

---

🟢 B010: 心跳上報與狀態同步 (Heartbeat & Status)

機台定時（建議每 5-10 秒）上送，用於確認連線狀態、溫度及門禁狀態。

1. API 資訊

• Endpoint: POST /api/v1/app/machine/status/B010
• 認證方式: Bearer Token (或 Request Body 帶 key)
• 處理方式: 異步處理 (Redis Queue)，立即回傳 202。

2. 請求範例 (JSON)

{
    "temperature": 5.2,
    "door_status": 0,
    "current_page": "home",
    "firmware_version": "1.0.5",
    "log": "Status heartbeat test",
    "log_level": "info"
}

3. 回應規格

• 成功: 202 Accepted

{
    "success": true,
    "code": 200,
    "message": "OK",
    "status": "49"
}

---

🔵 B600: 交易紀錄上報 (Transaction Record)

當機台端完成交易（收款或扣點成功）後上傳。

1. API 資訊

• Endpoint: POST /api/v1/app/B600
• 認證方式: Bearer Token
• 處理方式: 異步處理 (Redis Queue)。

2. 請求範例 (JSON)

{
    "flow_id": "F123456789",
    "total_amount": 100,
    "pay_amount": 100,
    "payment_type": 1,
    "items": [
        {
            "product_id": 1,
            "product_name": "Test Product",
            "price": 50,
            "quantity": 2
        }
    ]
}

---

📝 測試紀錄 (Test Logs)

2026-03-16: B600 交易功能測試

• 測試機台: SN001
• 測試方式: curl 命令模擬
• 驗證項目:
  • HTTP 回傳 202
  • 資料庫 orders 產生紀錄
  • 資料庫 order_items 產生紀錄
• 結果: 準備中...

2026-03-16: B010 首次演練測試

• 測試機台: SN001
• 測試方式: curl 命令模擬
• 驗證項目:
  • HTTP 回傳 202
  • 資料庫 machines.last_heartbeat_at 更新為台北時間
  • machine_logs 產生對應日誌
• 測試備註: 過程中發現 current_page 為 tinyInteger 導致寫入失敗，已將其修改為 string 以支援彈性的頁面名稱。
• 結果: ✅ 成功 (SUCCESS)。機台狀態已同步為 5.2度，當前頁面「home」。