LocalSERP Proxy API 文档

身份验证

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

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 中列出每个无效字段。可能会新增代码：请将未知代码作为一般失败处理。

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

速率限制

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