Tóm tắt chính
Định dạng request của API v2 chuẩn của SMM panel, 6 action, ví dụ phản hồi, thông báo lỗi và giới hạn request, viết cho đại lý.
API của SMM panel là cách kết nối để đặt hàng và kiểm tra trạng thái tự động từ một panel khác hoặc phần mềm của riêng bạn. 1PANEL PLUS dùng API v2 chuẩn của SMM panel, nên nếu bạn đã có code kết nối với panel khác, chỉ cần đổi địa chỉ và key là kết nối được ngay. API và website dùng cùng dịch vụ, cùng giá mỗi 1,000 và cùng số dư.
Ai dùng API của SMM panel?
- Đại lý: đưa dịch vụ lên panel của mình và tự động chuyển đơn của khách
- Agency: đặt đơn cho nhiều kênh cùng lúc vào giờ cố định
- Lập trình viên: viết script đặt hàng khi buổi phát bắt đầu hoặc khi có video mới được đăng
- Nhà vận hành: gom số dư và trạng thái đơn hàng vào bảng điều khiển của riêng mình
Làm sao để lấy API key?
Tạo key ở màn hình API key trong bảng điều khiển sau khi lần nạp đầu tiên được ghi nhận. Key chỉ hiển thị một lần, đúng lúc bạn tạo, nên hãy sao chép ngay và cất giữ ở nơi an toàn. Khi bạn tạo key mới, key cũ ngừng hoạt động ngay lập tức, nên nếu nghĩ key đã bị lộ, bạn chỉ cần tạo key mới để thay thế.
Gửi request API như thế nào?
Gửi mọi request bằng POST đến một địa chỉ duy nhất https://1panelplus.com/api/v2. Dùng cách nào tiện cho bạn, trường form (application/x-www-form-urlencoded hoặc multipart) hoặc nội dung JSON (Content-Type: application/json), và đưa key cùng action vào mọi request. Mọi phản hồi đều là JSON.
Ví dụ request (trường form): key=YOUR_API_KEY&action=balance
Ví dụ request (JSON): {"key": "YOUR_API_KEY", "action": "balance"}
| action | Giá trị cần gửi | Giá trị trả về |
|---|---|---|
| services | Không có | Danh sách dịch vụ |
| add | service, link, quantity hoặc comments | order (ID đơn hàng) |
| status | Một order, hoặc orders (tối đa 100, cách nhau bằng dấu phẩy) | charge, start_count, status, remains, currency |
| refill | order | refill (ID refill) |
| refill_status | refill | status |
| balance | Không có | balance, currency |
- action
- services
- Giá trị cần gửi
- Không có
- Giá trị trả về
- Danh sách dịch vụ
- action
- add
- Giá trị cần gửi
- service, link, quantity hoặc comments
- Giá trị trả về
- order (ID đơn hàng)
- action
- status
- Giá trị cần gửi
- Một order, hoặc orders (tối đa 100, cách nhau bằng dấu phẩy)
- Giá trị trả về
- charge, start_count, status, remains, currency
- action
- refill
- Giá trị cần gửi
- order
- Giá trị trả về
- refill (ID refill)
- action
- refill_status
- Giá trị cần gửi
- refill
- Giá trị trả về
- status
- action
- balance
- Giá trị cần gửi
- Không có
- Giá trị trả về
- balance, currency
Lấy danh sách dịch vụ bằng services như thế nào?
Gửi action=services, bạn nhận được mọi dịch vụ đang bán dưới dạng mảng. Mỗi dịch vụ gồm service (ID dịch vụ), name, type, category, rate, min, max, refill và cancel. rate là giá mỗi 1,000 (USD); khi type là Package, đó là giá của một gói. refill là true với dịch vụ có thời hạn refill, còn cancel luôn là false. category chứa cả tên nền tảng lẫn danh mục, nên bạn có thể tái tạo nguyên các danh mục trên panel của mình.
Ví dụ phản hồi: [{"service": SERVICE_ID, "name": "Tên dịch vụ", "type": "Default", "category": "YouTube - Tên danh mục", "rate": "Giá mỗi 1,000", "min": "Số lượng tối thiểu", "max": "Số lượng tối đa", "refill": true, "cancel": false}]
Giá và dịch vụ có thể thay đổi, nên nếu là đại lý, bạn nên lấy lại services theo chu kỳ cố định và đồng bộ giá cùng số lượng tối thiểu, tối đa trên panel của mình.
Đặt hàng bằng add như thế nào?
Gửi action=add cùng service (ID dịch vụ), link (link công khai) và quantity, đơn hàng sẽ được đặt và chi phí được trừ vào số dư ngay lập tức. Giá trị order trong phản hồi là ID đơn hàng; hãy lưu lại để dùng cho status và refill. Tài khoản đã được ghi nhận lần nạp đầu tiên mới có thể đặt hàng.
- Dịch vụ thông thường: gửi service, link và quantity
- Dịch vụ Custom Comments: gửi comments thay cho quantity. Mỗi dòng một bình luận, tối đa 500 ký tự mỗi dòng, và số dòng chính là số lượng
- Dịch vụ Package: không cần số lượng. Đơn hàng tính cho một gói
Ví dụ request: key=YOUR_API_KEY&action=add&service=SERVICE_ID&link=https://www.youtube.com/watch?v=videoid&quantity=1000
Ví dụ phản hồi: {"order": ORDER_ID}
Kiểm tra trạng thái đơn hàng bằng status như thế nào?
Gửi action=status cùng order (một ID đơn hàng) để nhận trạng thái của đơn đó, hoặc gửi orders với các ID đơn hàng nối bằng dấu phẩy để tra cứu tối đa 100 đơn cùng lúc. Nếu quản lý nhiều đơn, gộp chúng bằng orders giúp tiết kiệm rất nhiều request.
Ví dụ phản hồi (một đơn): {"charge": "Số tiền đã trừ", "start_count": "Số khởi điểm", "status": "In progress", "remains": "Số lượng còn lại", "currency": "USD"}
Ví dụ phản hồi (nhiều đơn): {"ORDER_ID_1": {"charge": "...", "start_count": "...", "status": "Completed", "remains": "0", "currency": "USD"}, "ORDER_ID_2": {"error": "Incorrect order ID"}}
| Giá trị status | Ý nghĩa |
|---|---|
| Pending | Đã nhận và đang chờ bắt đầu, hoặc đang chuyển sang xử lý |
| In progress | Đang giao |
| Completed | Đã giao đủ |
| Partial | Đã giao một phần và số tiền còn lại đã về số dư của bạn |
| Canceled | Không thể xử lý và toàn bộ số tiền đã về số dư của bạn |
- Giá trị status
- Pending
- Ý nghĩa
- Đã nhận và đang chờ bắt đầu, hoặc đang chuyển sang xử lý
- Giá trị status
- In progress
- Ý nghĩa
- Đang giao
- Giá trị status
- Completed
- Ý nghĩa
- Đã giao đủ
- Giá trị status
- Partial
- Ý nghĩa
- Đã giao một phần và số tiền còn lại đã về số dư của bạn
- Giá trị status
- Canceled
- Ý nghĩa
- Không thể xử lý và toàn bộ số tiền đã về số dư của bạn
charge là số tiền đã thanh toán trừ đi số tiền đã hoàn, nên sau đơn hoàn thành một phần hoặc bị hủy, bạn thấy ngay số tiền thực tế đã dùng. Trạng thái đơn hàng tự động cập nhật khoảng mỗi phút, nên tra cứu status với khoảng cách chừng một phút là đủ.
Dùng refill và refill_status như thế nào?
Gửi action=refill cùng order để yêu cầu refill, và bạn nhận lại refill (ID refill). Yêu cầu được chấp nhận với đơn đã hoàn thành hoặc hoàn thành một phần của dịch vụ có thời hạn refill, trong thời hạn refill tính từ ngày đơn hàng kết thúc, khi không có refill nào đang chạy và đã qua 24 giờ kể từ yêu cầu gần nhất. Gửi action=refill_status cùng refill, hệ thống trả về trạng thái là một trong Pending, In progress, Completed hoặc Rejected.
Ví dụ phản hồi: {"refill": REFILL_ID} và {"status": "Completed"}
Quy định refill giống như trên website. Điều kiện chi tiết có trong Giải thích thời hạn refill.
Kiểm tra số dư bằng balance như thế nào?
Gửi action=balance, bạn nhận được số dư hiện tại và đơn vị tiền tệ (USD). Nếu là đại lý, hãy kiểm tra số dư trước khi chuyển đơn và cài cảnh báo khi số dư xuống dưới một mức nhất định, để đơn hàng luôn được chuyển liên tục.
Ví dụ phản hồi: {"balance": "Số dư hiện tại", "currency": "USD"}
Các thông báo lỗi API có ý nghĩa gì?
Lỗi được trả về dưới dạng JSON với một câu tiếng Anh trong trường error. Mỗi câu có một nguyên nhân cố định, nên phần mềm của bạn có thể so sánh nguyên văn và xử lý.
| Giá trị error | Ý nghĩa |
|---|---|
| Invalid API key | Key bị thiếu hoặc không đúng |
| Too many requests | Bạn đã vượt giới hạn request mỗi phút. Hãy gửi lại sau ít phút |
| Add funds first | Bạn có thể đặt hàng sau khi lần nạp đầu tiên được ghi nhận |
| Incorrect service ID | Không phải ID của dịch vụ đang bán |
| Incorrect link | Định dạng link không hợp lệ |
| Quantity out of range | Số lượng nằm ngoài khoảng tối thiểu và tối đa của dịch vụ |
| Incorrect comments | Các dòng bình luận bị trống hoặc có dòng dài hơn 500 ký tự |
| Not enough funds on balance | Số dư của bạn thấp hơn chi phí đơn hàng |
| Incorrect order ID | Không phải ID đơn hàng của tài khoản này |
| Incorrect refill ID | Không phải ID refill của tài khoản này |
| Incorrect action | Giá trị action không thuộc 6 action |
- Giá trị error
- Invalid API key
- Ý nghĩa
- Key bị thiếu hoặc không đúng
- Giá trị error
- Too many requests
- Ý nghĩa
- Bạn đã vượt giới hạn request mỗi phút. Hãy gửi lại sau ít phút
- Giá trị error
- Add funds first
- Ý nghĩa
- Bạn có thể đặt hàng sau khi lần nạp đầu tiên được ghi nhận
- Giá trị error
- Incorrect service ID
- Ý nghĩa
- Không phải ID của dịch vụ đang bán
- Giá trị error
- Incorrect link
- Ý nghĩa
- Định dạng link không hợp lệ
- Giá trị error
- Quantity out of range
- Ý nghĩa
- Số lượng nằm ngoài khoảng tối thiểu và tối đa của dịch vụ
- Giá trị error
- Incorrect comments
- Ý nghĩa
- Các dòng bình luận bị trống hoặc có dòng dài hơn 500 ký tự
- Giá trị error
- Not enough funds on balance
- Ý nghĩa
- Số dư của bạn thấp hơn chi phí đơn hàng
- Giá trị error
- Incorrect order ID
- Ý nghĩa
- Không phải ID đơn hàng của tài khoản này
- Giá trị error
- Incorrect refill ID
- Ý nghĩa
- Không phải ID refill của tài khoản này
- Giá trị error
- Incorrect action
- Ý nghĩa
- Giá trị action không thuộc 6 action
Request refill có thể trả về Refill is not available for this service (dịch vụ không có thời hạn refill), Order is not finished yet (đơn hàng chưa kết thúc), Refill period has ended (đã quá thời hạn refill), hoặc Refill already requested, try again later (đang có refill đang chạy hoặc chưa đủ 24 giờ).
Có thể gửi bao nhiêu request API?
Mỗi key có thể gửi tối đa 300 request mỗi phút. Gộp các lần tra cứu trạng thái thành từng nhóm 100 bằng orders và chỉ lấy lại danh sách dịch vụ khi cần, bạn sẽ có dư địa thoải mái. Ví dụ, với 1,000 đơn đang chạy, 10 request mỗi phút một lần là kiểm tra được tất cả.
Đại lý đặt giá bán như thế nào?
Giá trị rate bạn nhận qua API là giá mỗi 1,000 của 1PANEL PLUS, còn giá bán trên panel của bạn do bạn tự đặt. Ví dụ, nếu cộng thêm 25% cho dịch vụ có rate $2.00, bạn bán với giá $2.50 mỗi 1,000; khi khách đặt 4,000, doanh thu của bạn là $10.00 và $8.00 được trừ tại 1PANEL PLUS. Các mức giá này là ví dụ để minh họa cách tính.
Nên thiết lập kết nối API theo thứ tự nào?
- Nạp số dư và tạo API key trong bảng điều khiển
- Kiểm tra key và kết nối bằng balance
- Lấy danh sách dịch vụ bằng services và đưa lên panel của bạn
- Gửi một add với số lượng nhỏ nhất và nhận ID đơn hàng
- Xác nhận trạng thái thay đổi bằng status, rồi bật đặt hàng tự động
Ví dụ curl, PHP, Python và Node.js cùng mô tả đầy đủ các trường có trong tài liệu API, và các câu hỏi khác có trong nhóm API của Câu hỏi thường gặp.