terrylee/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
d0f84eb82b
star-cloud/docs/api/iot-spec.md
sky121113 d0f84eb82b [REFACTOR] 廢棄 B010 HTTP API 並整合 MQTT 心跳回報流程 
1. 移除 routes/api.php 中的 B010 心跳上報路由。
2. 刪除 MachineController.php 中的 heartbeat 方法與相關過期邏輯。
3. 刪除 docs/b010_technical_spec.md 並更新相關技術規格文件。
4. 修改 ListenMqttQueue.php，移除獨立的溫度與版本號處理，統一由 heartbeat 任務分發。
5. 更新 MQTT 通訊規範，廢棄獨立的屬性 Topic (temperature, firmware_version)。
2026-04-21 15:48:49 +08:00

2.7 KiB
Raw Blame History

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",
            "...": "..."
        }
    ]
}

🔵 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 產生紀錄
  • 結果: 準備中...