REST API v2

Tổng quan

Đây là giao diện mà một agent AI vận hành. Mỗi lệnh gọi là một động từ được chọn bởi action, nên một agent tìm trong danh mục, đọc lại đơn giá và giới hạn, rồi hành động, tìm-rồi-hành-động, với giá được xác nhận trước khi bất kỳ khoản tiền nào chuyển đi. MCP server và CLI bao quanh chính những lệnh gọi này; trang này là giao thức thô bên dưới.

API tuân theo cấu trúc SMM API v2 được áp dụng rộng rãi, nên phần mềm panel, script và các tích hợp agent hiện có đều hoạt động với thay đổi tối thiểu. Mọi thao tác đều đi qua một endpoint duy nhất và chọn động từ bằng tham số action. Phản hồi là JSON. Dễ cho một script hoặc một LLM phân tích và nối chuỗi.

Endpoint

POST https://api.socialgo.com/api/v2

Xác thực

Xác thực theo từng yêu cầu, không session, không bắt tay, đó chính là điều khiến nó gọi được bởi một agent. Gửi key bí mật của bạn trên mọi lệnh gọi. Tìm và xoay nó trong bảng điều khiển ở Tài khoản → API. Hãy coi key như một mật khẩu: giữ nó ở phía máy chủ, không bao giờ để trong code client hay lời nhắc của agent.

Định dạng yêu cầu

Gửi các tham số form application/x-www-form-urlencoded qua POST. Mọi phản hồi đều là JSON. Hai tham số có mặt trên mọi lệnh gọi:

• key: API key của bạn (bắt buộc)
• action: động từ cần chạy (bắt buộc)

Định dạng lỗi

Khi thất bại, phản hồi mang một trường error với thông báo dễ đọc cho người, và mã trạng thái HTTP phản ánh vấn đề (ví dụ 400 yêu cầu sai, 401 key không hợp lệ). Một cấu trúc dễ đoán duy nhất, để một script hoặc agent có thể rẽ nhánh mà không phải đoán.

{
  "error": "Incorrect request"
}

Hành động

Mỗi động từ làm một việc. Một agent nối chúng theo thứ tự: services để tìm thứ cần mua, add để mua nó, status để theo dõi. Các lệnh gọi đọc (services, status, balance) cho phép nó xác nhận giá và tiền trước khi các lệnh gọi ghi (add, refill, cancel) chi bất cứ thứ gì.

1. Liệt kê dịch vụ

Danh mục mà agent đọc đầu tiên: mọi dịch vụ nó có thể đặt, kèm mã dịch vụ, danh mục, đơn giá (giá trên 1000), và số lượng tối thiểu/tối đa. Nó dùng các mã service trả về để đặt đơn hàng, và đơn giá để xác nhận chi phí trước khi chi tiền.

Yêu cầu

key=YOUR_API_KEY
action=services

Phản hồi

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. Thêm đơn hàng

Lệnh gọi ghi. Đặt một đơn hàng cho một dịch vụ. Truyền mã service, link đích, và quantity. Phản hồi trả về mã order mới để theo dõi. Một agent chỉ chạy lệnh này sau khi đã xác nhận đơn giá và giới hạn.

Tham số

• service: mã dịch vụ từ danh sách dịch vụ
• link: URL của bài viết / hồ sơ / kênh
• quantity: số lượng đơn vị cần giao

Yêu cầu

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

Phản hồi

{
  "order": 23501
}

3. Thêm đơn hàng, nhỏ giọt

Chia một đơn hàng thành các đợt giao nhỏ hơn trải theo thời gian, để có đường tăng trưởng đều đặn hơn. Đặt runs (bao nhiêu đợt giao) và interval (số phút giữa mỗi đợt). Tổng số giao là quantity × runs. Phép toán mà một agent dùng để định lượng chiến dịch mà bạn không phải làm thủ công.

Tham số bổ sung

• runs: số đợt giao
• interval: số phút giữa mỗi đợt

Yêu cầu

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

Phản hồi

{
  "order": 23502
}

4. Trạng thái đơn hàng

Trả về trạng thái hiện tại của một đơn hàng: khoản tính phí, số lượng bắt đầu, trạng thái, số lượng còn lại và tiền tệ. Đây là cách một agent theo dõi đơn hàng mà bạn không phải làm mới bảng điều khiển, và cách nó phát hiện một cú tụt đáng đánh dấu để bù đắp.

Yêu cầu

key=YOUR_API_KEY
action=status
order=23501

Phản hồi

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

Các giá trị status có thể có: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Trạng thái nhiều đơn hàng

Kiểm tra nhiều đơn hàng trong một lệnh gọi. Truyền một danh sách mã cách nhau bằng dấu phẩy trong tham số orders. Phản hồi được lập chỉ mục theo mã đơn hàng, nên một agent kiểm tra cả chiến dịch trong một vòng đi-về thay vì mỗi lệnh gọi một đơn.

Yêu cầu

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

Phản hồi

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. Bù đắp

Yêu cầu bù đắp cho một đơn hàng có dịch vụ hỗ trợ điều đó (refill: true trong danh sách dịch vụ) và trả về một mã bù đắp để theo dõi. Truyền một order đơn lẻ hoặc một danh sách orders cách nhau bằng dấu phẩy. Nhờ đó một agent có thể yêu cầu bù đắp hàng loạt sau khi kiểm tra trạng thái phát hiện các cú tụt.

Yêu cầu (đơn)

key=YOUR_API_KEY
action=refill
order=23501

Phản hồi

{
  "refill": 4001
}

Yêu cầu (nhiều)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Phản hồi

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. Hủy

Yêu cầu hủy các đơn hàng chưa được xử lý (dịch vụ có cancel: true). Truyền một danh sách orders cách nhau bằng dấu phẩy; phản hồi báo cáo kết quả theo từng đơn. Nút hoàn tác mà một agent với tới khi có gì đó bị xếp hàng nhầm.

Yêu cầu

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Phản hồi

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. Số dư

Trả về số dư tài khoản và tiền tệ của bạn. Một agent đọc nó để kiểm soát việc chi tiêu trước khi đặt đơn hàng, và panel của chính bạn đọc nó để hiển thị số tiền. Lệnh gọi rẻ nhất để xác nhận có tiền để chi.

Yêu cầu

key=YOUR_API_KEY
action=balance

Phản hồi

{
  "balance": "182.45",
  "currency": "USD"
}

Gọi nó từ bất cứ đâu

Một endpoint, các tham số form đơn giản. Nên một shell, một cron job, hay một agent có thể vận hành nó theo cùng một cách. Đây là một đơn hàng hoàn chỉnh được đặt từ dòng lệnh:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

Ghi chú & thực hành tốt nhất

• Đọc trước khi ghi. Gọi services (hoặc balance) để xác nhận đơn giá, giới hạn và tiền, rồi gọi add. Cùng một rào chắn tìm-rồi-hành-động mà bảng điều khiển và MCP server dùng để không có gì bị chi mà chưa có giá được xác nhận.
• Lưu bộ nhớ đệm danh sách dịch vụ và làm mới định kỳ, mã, đơn giá và giới hạn có thay đổi.
• Kiểm tra số lượng min/max trước khi gửi đơn hàng để tránh các lệnh gọi bị từ chối.
• Kiểm tra trạng thái theo lô bằng lệnh gọi nhiều đơn thay vì mỗi đơn một yêu cầu.
• Giữ key của bạn ở phía máy chủ. Nếu nó từng bị lộ, hãy xoay ngay lập tức từ bảng điều khiển.