# LocalSERP Proxy API 文档

> LocalSERP Proxy REST API 位于 localserpproxy.com/api：余额、充值、订单和代理的 API 密钥、错误、限制及端点。

- URL: https://localserpproxy.com/zh/docs/api/
- 最后更新: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

账户中的所有操作都可以通过脚本完成：查询余额、使用加密货币支付充值、购买套餐、创建代理凭据、轮换移动代理 IP。通过 HTTPS 传输 JSON，只需一个 API 密钥，并提供 curl、Python 和 Node.js 示例。

## 如何使用 LocalSERP Proxy API？

**快速解答**

向 `https://localserpproxy.com/api/v1` 发送 HTTPS 请求，并在请求头 `Authorization: Bearer API_KEY` 中附上 API 密钥。在账户的[开发者页面](https://localserpproxy.com/app/developer?lang=zh)创建密钥（或使用 `POST /v1/api-keys` 创建），并仅授予所需权限范围。请求和响应均为 JSON；错误始终以 `{ "error": { "code", "message" } }` 返回。

## 快速了解

| 属性 | 值 |
| --- | --- |
| 基础 URL | `https://localserpproxy.com/api/v1` |
| 格式 | 通过 HTTPS 传输的 JSON，UTF-8 编码 |
| 身份验证 | API 密钥：`Authorization: Bearer API_KEY` |
| API 密钥权限范围 | `read`、`proxies`、`billing` |
| 金额 | USD 字符串，保留 2 位小数（`"29.00"`） |
| 加密货币金额 | 十进制字符串，绝不使用浮点数（`"0.00045210"`） |
| 流量 | 字节（1 GB = 1,000,000,000 字节） |
| 日期 | ISO 8601 UTC（`2026-10-05T14:03:11Z`） |
| 版本 | 每个路径中的 `/v1` |

## 身份验证

除公开目录外，每个请求都必须携带 API 密钥：`Authorization: Bearer API_KEY`。创建密钥时会**完整显示一次**：请像保管密码一样妥善保存。你可以随时撤销密钥；撤销后，使用该密钥发出的请求将返回 `401 unauthorized`。

### 权限范围

为每个密钥仅授予脚本所需的权限。缺少所需权限范围的密钥会返回 `403 forbidden`。

| 权限范围 | 允许的操作 |
| --- | --- |
| `read` | 读取所有信息（账户、余额、服务、用量）。 |
| `proxies` | 更改代理设置和凭据（标签、自动续费、新密码），管理子用户、管理 IP 白名单并轮换移动代理端口（包括轮换链接）。 |
| `billing` | 创建订单和充值，并使用余额付款。 |

唯一例外是**移动代理轮换链接**，专为通过浏览器书签或纯文本 `curl` 调用而设计：`GET https://localserpproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY`（具有 `proxies` 权限范围的密钥）。请参阅[移动代理端口和 IP 轮换](https://localserpproxy.com/zh/docs/api/mobile/)。

*查看余额*

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

## 请求和响应

- **JSON 输入，JSON 输出**：发送带有请求体的 `Content-Type: application/json`。
- **列表**：可能增长的列表使用 `page`（从 1 开始）和 `perPage`（1–100，默认值为 20）进行分页，并返回 `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`。较短的列表返回 `{ "data": [...] }`。
- **ID**：不透明字符串，带有类型前缀：`ord_`（订单）、`top_`（充值）、`txn_`（余额变动）、`res_`（流量订阅）、`mob_`（移动代理端口）、`key_`（API 密钥）和 `ipw_`（IP 白名单条目）。
- **安全重试**：`POST /v1/orders` 和 `POST /v1/topups` 接受 `Idempotency-Key` 请求头（任意唯一字符串，保留 24 小时）。重复使用同一个密钥会返回首次响应，避免重复购买或充值。
- **示例**展示了各类响应的结构：其中的 ID、IP、金额和日期仅作示例，套餐 ID 和价格则为实际信息。

## 错误

所有错误的响应体格式相同。`code` 是稳定的，供代码使用；`message` 是英文句子，可能会变更。验证错误会在 `fields` 中列出每个无效字段。可能会新增代码：请将未知代码作为一般失败处理。

*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"
  }
}
```

### 状态码

| 状态 | 含义 |
| --- | --- |
| `422` | `validation_failed`：一个或多个字段无效。 |
| `401` | `unauthorized`：令牌缺失、无效或已过期。 |
| `402` | `insufficient_balance`：余额不足以支付订单。`details` = `InsufficientBalanceDetails`。 |
| `403` | `forbidden`：API 密钥缺少所需权限范围，或账户已暂停。 |
| `404` | `not_found`：资源不存在或属于其他账户。 |
| `409` | `conflict`（或更具体的代码）：当前状态下无法执行此操作。 |
| `429` | `rate_limited` 或 `rotation_too_soon`。 |

## 速率限制

每个响应都包含 `RateLimit-Limit`、`RateLimit-Remaining` 和 `RateLimit-Reset`。超过限制时，API 会返回 `429 rate_limited`，并附带 `Retry-After` 标头（秒）：等待相应时长后重试。移动代理端口的 IP 最多每 30 秒更换一次（`429 rotation_too_soon`，带有 `Retry-After`）。

## API 参考

- **[账户和余额](https://localserpproxy.com/zh/docs/api/account/)** — 查看您的账户设置、预付 USD 余额以及余额的所有变动（充值、购买、退款）。
- **[加密货币充值](https://localserpproxy.com/zh/docs/api/top-ups/)** — 使用加密货币为余额充值：获取充值地址和准确金额，按该金额转账，报告付款已发送（交易 ID 可选），然后跟踪充值状态，直至余额到账。余额可用于支付我们的任何套餐。
- **[订单](https://localserpproxy.com/zh/docs/api/orders/)** — 查看套餐及其价格，使用余额购买套餐（新服务、增加流量或延长端口期限），并查看历史订单。
- **[住宅代理和凭据](https://localserpproxy.com/zh/docs/api/residential/)** — 管理流量订阅（住宅代理和按 GB 计费的轮换式 4G/5G）：代理凭据、拥有独立凭据和流量上限的子用户、每日用量，以及可在代理用户名中指定的目标位置。
- **[移动端口和 IP 轮换](https://localserpproxy.com/zh/docs/api/mobile/)** — 专用 4G/5G 端口：立即或按定时计划更换 IP，使用轮换链接并查看每日流量。
- **[API 密钥和 IP 白名单](https://localserpproxy.com/zh/docs/api/api-keys/)** — 创建和撤销具有受限权限范围的 API 密钥，并管理 IP 白名单：最多允许 10 个来源 IP 无需用户名和密码即可使用代理。

> **通过脚本付款** 套餐始终使用预付 USD 余额支付。使用加密货币充值（最低 25.00 USD），通过 POST /v1/topups，然后通过 POST /v1/orders 购买。两步可在一次调用中完成：充值请求可在 purchase 中附带订单，余额到账后即购买套餐。

---

LocalSERP Proxy: LocalSERP Proxy 是一项美国住宅代理服务，用于逐个城市检查本地搜索结果、广告和价格，支持加密货币支付，无需上传身份证件。