Tài liệu API

Gửi key/action trong body application/x-www-form-urlencoded hoặc JSON. Không nhận query trên URL. Production bắt buộc HTTPS. GET không hỗ trợ. Ví dụ chỉ dùng dữ liệu minh họa.

curl -X POST 'https://smmvelox.com/api/v2' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'action=add' \
  --data-urlencode 'service=123' \
  --data-urlencode 'link=https://example.com/post' \
  --data-urlencode 'quantity=1000' \
  --data-urlencode 'client_order_id=YOUR_UNIQUE_ORDER_ID' \
  --data-urlencode 'max_charge=11550'

Xác thực API Key

Giữ key bí mật, chỉ gửi trong body. Không đưa vào URL, mã frontend hoặc chia sẻ cho người khác. Thay/thu hồi key có hiệu lực ngay. Tài khoản phải hoạt động và xác minh email.

API Key chỉ được gửi qua HTTPS trong phần thân POST; không đưa key vào URL hoặc mã phía trình duyệt.

API luôn báo giá và thanh toán bằng VND. USD trên giao diện chỉ để tham khảo.

V1 chỉ công bố Default có mapping/đơn vị đã xác minh: rate là VND / 1.000 lượt; charge = rate × quantity / 1.000. service là ID nội bộ tương ứng DV-ID; order là chuỗi ID đơn nội bộ ổn định. Không trả ID nguồn. Tiền dùng chuỗi decimal chính xác tối đa 12 chữ số lẻ.

key=YOUR_API_KEY&action=services

[
  {
    "service": 123,
    "name": "Example",
    "desc": "",
    "type": "Default",
    "category": "Facebook",
    "platform": "facebook",
    "rate": "11550.000000000000",
    "rate_unit": "per_1000",
    "min": "100",
    "max": "100000",
    "refill": false,
    "cancel": false,
    "dripfeed": false,
    "currency": "VND"
  }
]

API luôn báo giá và thanh toán bằng VND. USD trên giao diện chỉ để tham khảo.

key=YOUR_API_KEY&action=balance

{
  "balance": "100000.000000000001",
  "currency": "VND"
}

add yêu cầu service nguyên dương, link URL http/https tối đa 2.000 ký tự, quantity nguyên trong min/max. Không nhận price/rate/discount/currency/user_id/status/provider hoặc trường ngoài contract. Batch status tối đa 100 ID.

key=YOUR_API_KEY&action=add&service=123&link=https://example.com/post&quantity=1000&client_order_id=YOUR_UNIQUE_ORDER_ID

{
  "order": "456"
}

Trạng thái Pending/Processing/In progress/Completed/Partial/Canceled dựa trên bằng chứng. Đơn review/chưa rõ trả Pending và review_required=true. start_count/remains là null khi thiếu bằng chứng, không giả 0. charge lấy snapshot đã trả.

key=YOUR_API_KEY&action=status&order=456

{
  "charge": "11550",
  "status": "Pending",
  "start_count": null,
  "remains": null,
  "currency": "VND",
  "review_required": false
}

Trả kết quả dạng đối tượng theo từng ID; ID không tồn tại có lỗi riêng. Tối đa 100 ID mỗi lần.

key=YOUR_API_KEY&action=status&orders=456,999

{
  "456": {
    "charge": "11550",
    "status": "Pending",
    "start_count": null,
    "remains": null,
    "currency": "VND",
    "review_required": false
  },
  "999": {
    "error": "Incorrect order ID"
  }
}

Package/per_unit, custom comments, subscriptions, dripfeed chưa hỗ trợ và bị ẩn. cancel/refill/refill_status trả HTTP 400 Action is not supported; không đổi trạng thái hoặc tự hoàn tiền. Các cờ cancel/refill/dripfeed luôn false ở V1.

key=YOUR_API_KEY&action=cancel

{
  "error": "Action is not supported"
}

Quy tắc đặt đơn và trạng thái

Khi đặt đơn qua API, mạng có thể ngắt sau lúc hệ thống đã nhận đơn và trừ tiền. Timeout hoặc HTTP 503 không tự chứng minh yêu cầu chưa được xử lý. Hãy dùng một mã duy nhất cho mỗi ý định đặt đơn.

1. Trước lần add đầu tiên, tạo client_order_id duy nhất (hoặc idempotency_key), lưu lại cùng service, link, quantity và max_charge đã gửi.
2. Nếu nhận được order ID, lưu ID đó và dùng action=status với order để kiểm tra; không tạo add mới chỉ để hỏi trạng thái.
3. Nếu timeout hoặc mất phản hồi và chưa có order ID, chỉ thử lại khi kết nối/API sẵn sàng; gửi lại chính xác cùng action=add, mã yêu cầu và toàn bộ tham số ban đầu. Không tạo mã mới.
4. Nếu API trả order ID sau lần thử lại, sử dụng ID đó để theo dõi. Nếu vẫn chưa rõ, dừng tự động thử lại vô hạn và liên hệ hỗ trợ kèm mã yêu cầu (không gửi API Key).

curl -X POST 'https://smmvelox.com/api/v2' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'action=add' \
  --data-urlencode 'service=123' \
  --data-urlencode 'link=https://example.com/post' \
  --data-urlencode 'quantity=1000' \
  --data-urlencode 'client_order_id=YOUR_UNIQUE_ORDER_ID' \
  --data-urlencode 'max_charge=11550'

Không thể tra cứu status bằng client_order_id; action=status cần order ID. Nếu chưa nhận được ID, chỉ có thể thử lại add an toàn với cùng mã và nội dung đã gửi (khi API sẵn sàng), hoặc liên hệ hỗ trợ.

Ví dụ lỗi JSON và cách xử lý

{
  "error": "Client order ID conflicts with an existing request"
}

{
  "error": "Invalid request parameters",
  "fields": [
    "quantity"
  ]
}

{
  "error": "Rate limit exceeded"
}

{
  "error": "API order creation is disabled"
}

Các JSON trên là ví dụ từ các trường hợp thực tế; thông báo error có thể khác tùy nguyên nhân. Mã HTTP và hướng xử lý mới là điều cần kiểm tra.

Mã lỗi HTTP

Phản hồi lỗi dùng JSON có trường error; lỗi xác thực và thông tin nội bộ không được công khai.

Bảo mật, giới hạn và lỗi

Tùy chọn: tối đa 20 IPv4/IPv6 chính xác, mỗi dòng một IP. Trống nghĩa là không giới hạn IP. Không hỗ trợ CIDR. Danh sách sai bị từ chối và giữ cấu hình cũ.

Mỗi phút: 60 request/IP trước xác thực; thêm 120 lượt đọc hoặc 15 add theo user và key. Body tối đa 64 KiB. Lỗi 429 có Retry-After. Không tin Forwarded/X-Forwarded-For tự gửi từ client.

FAQ: Lấy key sau đăng nhập. Quên key phải thay mới, không thể xem lại secret cũ. Key nhà cung cấp không dùng ở đây. V1 (30/10/2026): services, balance, add Default và status đơn/batch. Các thao tác sau bán chờ V2 có luồng an toàn.