重點摘要
從轉售商的角度，整理了標準 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 分類查看。