API 文件

透過本地裝置 API（連接埠 5200）與遠端伺服器 API 整合 NodeCoreX。遠端請求需要基於帳號、密碼、機器碼與時間戳產生的 SHA-256 簽名。

本地裝置 API

基礎 URL： http://localhost:5200

GET http://localhost:5200/nodes/count

獲取節點數量

獲取目前裝置上執行中的廣告節點總數。

成功（HTTP 200）：

{
  "success": true,
  "count": 4
}

錯誤（非 200）：

{
  "success": false,
  "message": "Service unavailable"
}

GET http://localhost:5200/nodes/list

獲取節點索引列表

獲取全部節點索引列表，以便後續依索引執行操作。

成功（HTTP 200）：

{
  "success": true,
  "nodeIndexes": [
    0,
    1,
    2,
    3
  ]
}

錯誤（非 200）：

{
  "success": false,
  "message": "Failed to list nodes"
}

GET http://localhost:5200/nodes/status

獲取節點狀態

獲取每個節點的執行狀態（執行中、已停止、錯誤等）。

成功（HTTP 200）：

{
  "success": true,
  "statuses": [
    {
      "index": 0,
      "status": "running",
      "uptime": 3600
    },
    {
      "index": 1,
      "status": "stopped",
      "uptime": 0
    },
    {
      "index": 2,
      "status": "error",
      "message": "Proxy timeout"
    }
  ]
}

錯誤（非 200）：

{
  "success": false,
  "message": "Unable to read node status"
}

POST http://localhost:5200/nodes/{nodeIndex}/start

啟動節點

啟動指定節點索引對應的廣告播放節點。

參數：

nodeIndex (path) — 節點索引（從 0 開始）

成功（HTTP 200）：

{
  "success": true,
  "message": "Node started",
  "index": 0
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid node index or already running"
}

POST http://localhost:5200/nodes/{nodeIndex}/stop

停止節點

停止指定節點索引對應的廣告播放節點。

參數：

nodeIndex (path) — 節點索引（從 0 開始）

成功（HTTP 200）：

{
  "success": true,
  "message": "Node stopped",
  "index": 0
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid node index or already stopped"
}

POST http://localhost:5200/nodes/{nodeIndex}/proxy

為節點設定代理

為指定節點索引設定代理連線（主機、連接埠、驗證等）。

參數：

nodeIndex (path) — 節點索引
ip (body) — 代理位址
port (body) — 代理連接埠
username (body) — 代理使用者名稱（可選）
password (body) — 代理密碼（可選）

請求主體範例：

{
  "ip": "127.0.0.1",
  "port": 7890,
  "username": null,
  "password": null
}

成功（HTTP 200）：

{
  "success": true,
  "message": "Proxy updated",
  "index": 0
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid proxy or connection failed"
}

GET http://localhost:5200/device/info

獲取裝置資訊

獲取裝置基礎資訊，例如機器碼、型號和版本。

成功（HTTP 200）：

{
  "success": true,
  "machineCode": "PM-XXXX-YYYY",
  "model": "Standard",
  "version": "1.0.0",
  "firmware": "1.2.3"
}

錯誤（非 200）：

{
  "success": false,
  "message": "Node info unavailable"
}

GET http://localhost:5200/device/health

裝置健康檢查

檢查本機服務是否正在執行；可用於心跳回報。

成功（HTTP 200）：

{
  "success": true,
  "healthy": true,
  "uptime": 3600,
  "nodesActive": 4
}

錯誤（非 200）：

{
  "success": false,
  "healthy": false,
  "message": "Service unhealthy"
}

遠端伺服器 API

基礎 URL：您的平台 API 主機（環境相關端點請查看應用控制台）。

GET /api/device/ads

獲取廣告任務列表

獲取廣告來源網站、廣告類型、廣告 ID、播放連結及相關內容。

參數：

sign (query) 必填 — 簽名；請見下方簽名演演演算法
machineCode (query) 必填 — 硬體裝置碼
timestamp (query) 必填 — 請求時間戳（秒）

成功（HTTP 200）：

{
  "success": true,
  "data": {
    "ads": [
      {
        "id": "ad-001",
        "adType": "Video",
        "source": "example.com",
        "sourceUrl": "https://example.com/campaign/1",
        "playUrl": "https://cdn.example.com/ad-001",
        "duration": 30,
        "rewardPerView": 0.001
      }
    ]
  }
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid sign or expired timestamp",
  "code": "AUTH_FAILED"
}

GET /api/device/earnings

依節點或裝置獲取收益

根據裝置碼與可選的節點索引獲取收益明細或摘要。

參數：

sign (query) 必填 — 簽名
machineCode (query) 必填 — 裝置碼
timestamp (query) 必填 — 時間戳
nodeIndex (query) — 節點索引；若查詢裝置整體收益可省略
startDate (query) — 開始日期 YYYY-MM-DD
endDate (query) — 結束日期 YYYY-MM-DD

成功（HTTP 200）：

{
  "success": true,
  "data": {
    "totalPoints": 1200,
    "currency": "points",
    "details": [
      {
        "date": "2025-03-01",
        "nodeIndex": 0,
        "points": 300,
        "adCount": 120
      },
      {
        "date": "2025-03-01",
        "nodeIndex": 1,
        "points": 280,
        "adCount": 115
      }
    ]
  }
}

錯誤（非 200）：

{
  "success": false,
  "message": "Node not found or access denied",
  "code": "FORBIDDEN"
}

POST /api/device/heartbeat

裝置心跳

定期回報裝置在線狀態與節點執行狀態。

參數：

sign (query) 必填 — 簽名
machineCode (query) 必填 — 裝置碼
timestamp (query) 必填 — 時間戳

請求主體範例：

{
  "nodeStatuses": [
    {
      "index": 0,
      "status": "running",
      "uptime": 3600
    },
    {
      "index": 1,
      "status": "running",
      "uptime": 3600
    },
    {
      "index": 2,
      "status": "stopped",
      "uptime": 0
    }
  ],
  "deviceHealthy": true
}

成功（HTTP 200）：

{
  "success": true,
  "message": "Heartbeat received",
  "nextReportIn": 60
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid sign or machineCode",
  "code": "AUTH_FAILED"
}

GET /api/device/config

獲取裝置設定

獲取裝置執行設定（例如任務間隔、區域限制）。

參數：

sign (query) 必填 — 簽名
machineCode (query) 必填 — 裝置碼
timestamp (query) 必填 — 時間戳

成功（HTTP 200）：

{
  "success": true,
  "data": {
    "taskInterval": 30,
    "allowedRegions": [
      "US",
      "GB",
      "DE"
    ],
    "maxConcurrentAds": 4,
    "reportInterval": 60
  }
}

錯誤（非 200）：

{
  "success": false,
  "message": "Invalid sign or node",
  "code": "AUTH_FAILED"
}

簽名演演演演演演演演演演演演演演算法

遠端 API 請求需要查詢參數 sign, machineCode, 和 timestamp.

sign = SHA256(account + password + machineCode + timestamp)

建立帳戶說明中心