# Tài liệu API LocalSERP Proxy

> API REST LocalSERP Proxy tại localserpproxy.com/api: khóa API, lỗi, giới hạn và endpoint cho số dư, nạp tiền, đơn hàng và proxy.

- URL: https://localserpproxy.com/vi/docs/api/
- Cập nhật lần cuối: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Bạn có thể tự động hóa mọi thao tác trong tài khoản: kiểm tra số dư, nạp tiền bằng crypto, mua gói, tạo thông tin đăng nhập proxy, đổi IP di động. JSON qua HTTPS, một khóa API, ví dụ bằng curl, Python và Node.js.

## Cách sử dụng API LocalSERP Proxy?

**Trả lời nhanh**

Gửi yêu cầu HTTPS đến `https://localserpproxy.com/api/v1`, kèm khóa API trong tiêu đề `Authorization: Bearer API_KEY`. Tạo khóa trên [trang dành cho nhà phát triển](https://localserpproxy.com/app/developer?lang=vi) trong tài khoản (hoặc bằng `POST /v1/api-keys`) và chỉ cấp các quyền cần thiết. Yêu cầu và phản hồi đều ở định dạng JSON; lỗi luôn được trả về dưới dạng `{ "error": { "code", "message" } }`.

## Thông tin tổng quan

| Thuộc tính | Giá trị |
| --- | --- |
| URL cơ sở | `https://localserpproxy.com/api/v1` |
| Định dạng | JSON qua HTTPS, UTF-8 |
| Xác thực | API key: `Authorization: Bearer API_KEY` |
| Phạm vi quyền của API key | `read`, `proxies`, `billing` |
| Tiền tệ | USD dưới dạng chuỗi có 2 chữ số thập phân (`"29.00"`) |
| Số tiền mã hóa | Chuỗi thập phân, không bao giờ dùng số thực (`"0.00045210"`) |
| Lưu lượng truy cập | Byte (1 GB = 1.000.000.000 byte) |
| Ngày tháng | ISO 8601 theo UTC (`2026-10-05T14:03:11Z`) |
| Phiên bản | `/v1` trong mọi đường dẫn |

## 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`.

### Phạm vi quyền

Chỉ cấp cho mỗi API key những quyền mà tập lệnh của bạn cần. API key không có phạm vi quyền bắt buộc sẽ nhận `403 forbidden`.

| Phạm vi quyền | Quyền được cấp |
| --- | --- |
| `read` | đọc mọi thông tin (tài khoản, số dư, dịch vụ, mức sử dụng). |
| `proxies` | thay đổi cài đặt và thông tin đăng nhập proxy (nhãn, tự động gia hạn, mật khẩu mới), quản lý người dùng phụ, quản lý danh sách IP cho phép và xoay cổng di động (bao gồm liên kết xoay). |
| `billing` | tạo đơn hàng và nạp tiền, thanh toán bằng số dư. |

Ngoại lệ duy nhất là **liên kết xoay di động**, được thiết kế để gọi từ dấu trang trình duyệt hoặc một `curl` thuần: `GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (khóa có phạm vi `proxies`). Xem [Cổng di động và xoay IP](https://localserpproxy.com/vi/docs/api/mobile/).

*Kiểm tra số dư*

```bash
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.

*422 validation_failed*

```json
{
  "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"
  }
}
```

### Mã trạng thái

| Trạng thái | Ý nghĩa |
| --- | --- |
| `422` | `validation_failed`: một hoặc nhiều trường không hợp lệ. |
| `401` | `unauthorized`: token bị thiếu, không hợp lệ hoặc đã hết hạn. |
| `402` | `insufficient_balance`: số dư không đủ để thanh toán đơn hàng. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: API key không có phạm vi quyền cần thiết hoặc tài khoản đã bị tạm ngưng. |
| `404` | `not_found`: tài nguyên không tồn tại hoặc thuộc về tài khoản khác. |
| `409` | `conflict` (hoặc mã cụ thể hơn): không thể thực hiện thao tác ở trạng thái hiện tại. |
| `429` | `rate_limited` hoặc `rotation_too_soon`. |

## 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`).

## Tài liệu tham khảo API

- **[Tài khoản và số dư](https://localserpproxy.com/vi/docs/api/account/)** — Xem cài đặt tài khoản, số dư trả trước bằng USD và mọi giao dịch của số dư đó (nạp tiền, mua hàng, hoàn tiền).
- **[Nạp tiền bằng crypto](https://localserpproxy.com/vi/docs/api/top-ups/)** — Nạp tiền bằng crypto: lấy địa chỉ nạp và số tiền chính xác, gửi đúng số tiền đó, báo đã gửi khoản thanh toán (không bắt buộc cung cấp ID giao dịch), sau đó theo dõi khoản nạp cho đến khi tiền được cộng vào số dư. Số dư dùng để thanh toán cho mọi gói dịch vụ của chúng tôi.
- **[Đơn hàng](https://localserpproxy.com/vi/docs/api/orders/)** — Xem danh sách gói dịch vụ và giá, mua gói bằng số dư (dịch vụ mới, thêm lưu lượng hoặc gia hạn cổng) và xem các đơn hàng trước đây.
- **[Proxy dân cư và thông tin xác thực](https://localserpproxy.com/vi/docs/api/residential/)** — Quản lý gói đăng ký lưu lượng (proxy dân cư và proxy xoay vòng 4G/5G tính theo GB): thông tin xác thực proxy, người dùng phụ có thông tin xác thực và giới hạn lưu lượng riêng, mức sử dụng hằng ngày và các vị trí bạn có thể nhắm mục tiêu trong tên người dùng proxy.
- **[Cổng proxy di động và xoay vòng IP](https://localserpproxy.com/vi/docs/api/mobile/)** — Cổng 4G/5G chuyên dụng: đổi IP ngay hoặc theo lịch, dùng liên kết xoay IP và xem lưu lượng hằng ngày.
- **[Khóa API và danh sách IP cho phép](https://localserpproxy.com/vi/docs/api/api-keys/)** — Tạo và thu hồi khóa API với phạm vi quyền hạn giới hạn, đồng thời quản lý danh sách IP cho phép: tối đa 10 IP nguồn được phép sử dụng proxy mà không cần tên người dùng và mật khẩu.

> **Thanh toán từ tập lệnh** Các gói luôn được thanh toán bằng số dư USD trả trước. Nạp tiền bằng crypto (tối thiểu 25.00 USD) với POST /v1/topups, sau đó mua bằng POST /v1/orders. Có thể thực hiện cả hai trong một lệnh gọi: khoản nạp có thể kèm đơn hàng trong purchase, và gói sẽ được mua ngay khi khoản nạp được ghi có.

---

LocalSERP Proxy: LocalSERP Proxy là dịch vụ proxy dân cư tại Hoa Kỳ để kiểm tra kết quả tìm kiếm địa phương, quảng cáo và giá theo từng thành phố, thanh toán bằng tiền mã hóa và không cần tải lên giấy tờ tùy thân.