Tài liệu API LocalSERP Proxy

Xác thực

Mọi yêu cầu, ngoại trừ danh mục công khai, đều cần có API key: Authorization: Bearer API_KEY. API key được hiển thị đầy đủ một lần duy nhất khi bạn tạo: hãy lưu như mật khẩu. Bạn có thể thu hồi API key bất cứ lúc nào; các yêu cầu sử dụng key đó sau đó sẽ trả về 401 unauthorized.

curl -s "https://localserpproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"

Yêu cầu và phản hồi

• JSON đầu vào, JSON đầu ra: gửi Content-Type: application/json kèm nội dung.
• Danh sách có thể dài được phân trang bằng page (bắt đầu từ 1) và perPage (1–100, mặc định 20), đồng thời trả về { "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }. Danh sách ngắn trả về { "data": [...] }.
• ID là chuỗi không mang ý nghĩa, có tiền tố loại: ord_ (đơn hàng), top_ (nạp tiền), txn_ (biến động số dư), res_ (gói đăng ký lưu lượng), mob_ (cổng di động), key_ (khóa API) và ipw_ (mục trong danh sách IP cho phép).
• Thử lại an toàn: POST /v1/orders và POST /v1/topups chấp nhận tiêu đề Idempotency-Key (bất kỳ chuỗi duy nhất nào, được lưu trong 24 h). Gửi lại cùng một khóa sẽ trả về phản hồi đầu tiên thay vì mua hoặc nạp tiền hai lần.
• Ví dụ minh họa cấu trúc của từng câu trả lời: ID, IP, số tiền và ngày tháng trong ví dụ chỉ để minh họa; ID gói và giá là thông tin thực tế.

Lỗi

Mọi lỗi đều có cùng cấu trúc nội dung. code ổn định và dành cho mã của bạn; message là câu tiếng Anh có thể thay đổi. Lỗi xác thực liệt kê từng trường không hợp lệ trong fields. Có thể bổ sung mã mới: hãy xử lý mã không xác định như lỗi chung.

{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}

Giới hạn tốc độ

Mỗi phản hồi đều có RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset. Khi vượt giới hạn, API trả về 429 rate_limited cùng header Retry-After (giây): hãy chờ khoảng thời gian đó rồi thử lại. IP của cổng proxy di động chỉ có thể đổi tối đa 1 lần mỗi 30 giây (429 rotation_too_soon, với Retry-After).