重點摘要
以經銷商的角度，整理了標準 SMM面板 API v2 的請求方式、6 種 action、回應範例、錯誤訊息和請求上限。
SMM面板 API 是從其他面板或自己開發的程式中，自動送出訂單並確認狀態的串接方式。1PANEL PLUS 使用標準 SMM面板 API v2，如果您已有串接其他面板的程式碼，只要換掉網址和金鑰就能立即串接。API 和網站使用相同的服務、相同的每 1,000 個價格，以及同一筆餘額。
誰會使用 SMM面板 API？
- 經銷商：在自己的面板上架服務，自動轉交客戶訂單
- 行銷代理商：在指定時間一次送出多個頻道的訂單
- 開發者：撰寫配合開播或新影片上傳自動下單的腳本
- 營運者：把餘額和訂單狀態整合顯示在自己的管理畫面上
如何取得 API 金鑰？
首筆儲值入帳後，在控制台的 API 金鑰畫面建立。金鑰只會在建立當下顯示一次，請立即複製並存放在安全的地方。建立新金鑰後，舊金鑰會立即無法使用，如果覺得金鑰可能外洩，建立新金鑰替換即可。
如何傳送 API 請求？
所有請求都以 POST 傳送到同一個網址 https://1panelplus.com/api/v2。表單欄位 (application/x-www-form-urlencoded 或 multipart) 或 JSON 本文 (Content-Type: application/json) 擇一使用即可，所有請求都要同時附上 key 和 action。回應全部是 JSON。
請求範例 (表單欄位)：key=YOUR_API_KEY&action=balance
請求範例 (JSON)：{"key": "YOUR_API_KEY", "action": "balance"}
| action | 一併傳送的值 | 回傳的值 |
|---|---|---|
| services | 無 | 服務清單 |
| add | service、link、quantity 或 comments | order (訂單編號) |
| status | 單一 order 或 orders (以逗號分隔，最多 100 筆) | charge、start_count、status、remains、currency |
| refill | order | refill (補量編號) |
| refill_status | refill | status |
| balance | 無 | balance、currency |
- action
- services
- 一併傳送的值
- 無
- 回傳的值
- 服務清單
- action
- add
- 一併傳送的值
- service、link、quantity 或 comments
- 回傳的值
- order (訂單編號)
- action
- status
- 一併傳送的值
- 單一 order 或 orders (以逗號分隔，最多 100 筆)
- 回傳的值
- charge、start_count、status、remains、currency
- action
- refill
- 一併傳送的值
- order
- 回傳的值
- refill (補量編號)
- action
- refill_status
- 一併傳送的值
- refill
- 回傳的值
- status
- action
- balance
- 一併傳送的值
- 無
- 回傳的值
- balance、currency
如何用 services 取得服務清單？
傳送 action=services，會以陣列回傳所有販售中的服務。每項服務都包含 service (服務編號)、name、type、category、rate、min、max、refill、cancel。rate 是每 1,000 個的價格 (USD)，若 type 為 Package，則是 1 組方案的價格。有補量期的服務 refill 為 true，cancel 一律為 false。category 同時寫有平台名稱和分類，可以直接沿用為您自己面板的分類。
回應範例：[{"service": 服務編號, "name": "服務名稱", "type": "Default", "category": "YouTube - 分類名稱", "rate": "每 1,000 個價格", "min": "最低數量", "max": "最高數量", "refill": true, "cancel": false}]
價格和服務可能會變動，經銷商最好定期重新取得 services，讓自己面板的價格和最低、最高數量保持同步。
如何用 add 送出訂單？
向 action=add 一併傳送 service (服務編號)、link (公開連結) 和 quantity (數量)，訂單就會受理，金額立即從餘額扣除。回應中的 order 是訂單編號，請保存這個編號，用於 status 和 refill。首筆儲值已入帳的帳號即可下單。
- 一般服務：傳送 service、link、quantity
- Custom Comments 服務：以 comments 取代 quantity 傳送。每行一則留言，每行最多 500 個字元，行數就是數量
- Package 服務：不需要傳送數量，以一組方案下單
請求範例：key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000
回應範例：{"order": 訂單編號}
如何用 status 確認訂單狀態？
向 action=status 傳送 order (單一訂單編號)，會回傳該訂單的狀態；在 orders 中用逗號串接訂單編號傳送，一次最多可查詢 100 筆。管理多筆訂單時，用 orders 合併查詢可以大幅節省請求次數。
回應範例 (單筆)：{"charge": "付款金額", "start_count": "起始數值", "status": "In progress", "remains": "剩餘數量", "currency": "USD"}
回應範例 (多筆)：{"訂單編號1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "訂單編號2": {"error": "Incorrect order ID"}}
| status 值 | 意思 |
|---|---|
| Pending | 已受理，正在等待開始或轉入處理 |
| In progress | 正在送達 |
| Completed | 已全部送達 |
| Partial | 已送達一部分，剩餘金額已退回餘額 |
| Canceled | 未能處理，全額已退回餘額 |
- status 值
- Pending
- 意思
- 已受理，正在等待開始或轉入處理
- status 值
- In progress
- 意思
- 正在送達
- status 值
- Completed
- 意思
- 已全部送達
- status 值
- Partial
- 意思
- 已送達一部分，剩餘金額已退回餘額
- status 值
- Canceled
- 意思
- 未能處理，全額已退回餘額
charge 是付款金額扣除退款金額後的值，所以部分完成或取消後，實際花費的金額會立即顯示。訂單狀態大約每 1 分鐘自動更新一次，status 也以 1 分鐘左右的間隔查詢就足夠了。
refill 和 refill_status 怎麼用？
向 action=refill 傳送 order，就會申請補量並回傳 refill (補量編號)。對有補量期服務的已完成或部分完成訂單，在訂單結束當天起的補量期內、沒有進行中的補量，且距離上次申請已滿 24 小時時受理。向 action=refill_status 傳送 refill，會以 Pending、In progress、Completed、Rejected 其中之一告知狀態。
回應範例：{"refill": 補量編號} 以及 {"status": "Completed"}
補量規則與網站相同。詳細條件整理在了解補量期中。
如何用 balance 確認餘額？
傳送 action=balance，會回傳目前餘額和幣別 (USD)。經銷商可以在轉交訂單前確認餘額，並設定餘額低於一定金額時發出通知，訂單就能不中斷地持續下去。
回應範例：{"balance": "目前餘額", "currency": "USD"}
API 錯誤訊息代表什麼？
錯誤會以 JSON 回傳，error 欄位中是英文句子。每個句子對應固定的原因，在程式中直接比對處理即可。
| error 值 | 意思 |
|---|---|
| Invalid API key | 金鑰缺少或不正確 |
| Too many requests | 超過每分鐘請求次數，請稍後再傳送 |
| Add funds first | 首筆儲值入帳後才能下單 |
| Incorrect service ID | 不是販售中的服務編號 |
| Incorrect link | 連結格式不正確 |
| Quantity out of range | 數量超出服務的最低、最高範圍 |
| Incorrect comments | 留言行是空的，或某一行超過 500 個字元 |
| Not enough funds on balance | 餘額少於訂單金額 |
| Incorrect order ID | 不是此帳號的訂單編號 |
| Incorrect refill ID | 不是此帳號的補量編號 |
| Incorrect action | action 值不是 6 種之一 |
- error 值
- Invalid API key
- 意思
- 金鑰缺少或不正確
- error 值
- Too many requests
- 意思
- 超過每分鐘請求次數，請稍後再傳送
- error 值
- Add funds first
- 意思
- 首筆儲值入帳後才能下單
- error 值
- Incorrect service ID
- 意思
- 不是販售中的服務編號
- error 值
- Incorrect link
- 意思
- 連結格式不正確
- error 值
- Quantity out of range
- 意思
- 數量超出服務的最低、最高範圍
- error 值
- Incorrect comments
- 意思
- 留言行是空的，或某一行超過 500 個字元
- error 值
- Not enough funds on balance
- 意思
- 餘額少於訂單金額
- error 值
- Incorrect order ID
- 意思
- 不是此帳號的訂單編號
- error 值
- Incorrect refill ID
- 意思
- 不是此帳號的補量編號
- error 值
- Incorrect action
- 意思
- action 值不是 6 種之一
補量申請可能會回傳 Refill is not available for this service (沒有補量期的服務)、Order is not finished yet (尚未結束的訂單)、Refill period has ended (已過補量期的訂單)、Refill already requested, try again later (有進行中的補量，或未滿 24 小時的訂單)。
API 請求最多可以傳送幾次？
每把金鑰每分鐘最多可請求 300 次。狀態查詢用 orders 每 100 筆合併，服務清單只在需要時重新取得，就能寬裕地使用。例如進行中的訂單有 1,000 筆，每分鐘傳送 10 次請求就能全部查詢。
經銷商要怎麼決定售價？
透過 API 取得的 rate 是 1PANEL PLUS 的每 1,000 個價格，您自己面板的售價由經銷商自行決定。例如在 rate 為 $2.00 的服務上加價 25% 販售，每 1,000 個就是 $2.50；客戶訂購 4,000 個時，銷售金額是 $10.00，從 1PANEL PLUS 扣除的金額是 $8.00。這個價格是用來說明計算方式的範例。
API 串接依什麼順序進行比較好？
- 儲值餘額，並在控制台建立 API 金鑰
- 用 balance 確認金鑰和連線
- 用 services 取得服務清單，上架到自己的面板
- 用最小數量傳送一次 add，取得訂單編號
- 用 status 確認狀態有變化後，再開啟自動下單
curl、PHP、Python、Node.js 範例和所有欄位說明請見API 文件，其他問題可以在常見問題的 API 分類中查看。