# REST API：余额、用量、凭据、订单、列表与设备。

控制面板的所有功能均可通过 HTTPS 上的 JSON 接口完成。基础 URL 为 `https://api.proxshift.com/v1`，采用 Bearer 身份验证和游标分页。

> Info：本页所述的接口约定为最终版本。同一约定还以 [OpenAPI 3.1 文档](https://proxshift.com/zh/docs/openapi.json) 发布；该文档由本页生成，可用于客户端生成器和智能体工具。


## 约定

- **基础 URL**: `https://api.proxshift.com/v1`
- **身份验证**: `Authorization: Bearer TOKEN`。令牌可在控制面板的 **API 令牌**下创建，每个令牌均可单独撤销。`GET /v1/pricing` 无需令牌。
- **格式**: 请求和响应均使用 JSON、`Content-Type: application/json` 和 UTF-8。时间戳采用 UTC 时区的 ISO 8601 格式。金额为以 USD 计价的十进制字符串；除非字段名标有 `_gb`，否则流量均以字节为单位。
- **分页**: 列表端点接受 `limit`（默认 50，最大 200）和 `cursor`，并返回 `next_cursor`（最后一页为 null）。
- **幂等性**: 调用 `POST /orders` 和 `POST /orders/{id}/renew` 时请发送 `Idempotency-Key` 请求头；24 小时内重复使用同一键将返回原始结果，不会重复扣款。
- **速率限制**: 每个令牌每分钟可发送 120 个请求。每个响应都包含 `X-RateLimit-Remaining`；超出限制时返回 `429` 和 `Retry-After`。


## 错误

错误使用标准状态码和统一的 JSON 结构。`code` 保持稳定，供程序处理；`message` 面向用户，内容可能会变更。

```json
{
  "error": {
    "code": "insufficient_balance",
    "message": "This order costs 28.22 USD; the wallet holds 12.40 USD."
  }
}
```

| 状态码 | 错误代码 | 含义 |
| --- | --- | --- |
| 400 | invalid_request, invalid_parameter | JSON 格式错误，或字段值超出允许范围；`message` 会指出相应字段 |
| 401 | invalid_token | Bearer 令牌缺失、已撤销或格式错误 |
| 402 | insufficient_balance | 钱包余额不足以支付本次购买 |
| 404 | not_found | ID 未知，或对象属于其他账户 |
| 409 | conflict | 当前状态不允许执行此操作，例如续订已经结束的订单 |
| 429 | rate_limited | 请求过多；请等待 `Retry-After` 指定的秒数 |
| 5xx | internal_error | 请采用退避策略重试；如果响应中未返回 `order` 对象，则没有扣款 |


## 账户与余额


### GET /v1/account

令牌所属的账户。

请求：

```bash
curl https://api.proxshift.com/v1/account -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "id": "acc_3f9k2m",
  "created_at": "2026-09-21T08:14:02Z",
  "whitelist_count": 2,
  "subuser_count": 3
}
```


### GET /v1/balance

钱包余额，以及各流量池网络的流量余额（以字节和 GB 表示）。

请求：

```bash
curl https://api.proxshift.com/v1/balance -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "wallet_usd": "142.60",
  "traffic": {
    "residential": { "bytes": 96636764160, "gb": 90.0 },
    "mobile":      { "bytes": 2147483648,  "gb": 2.0 }
  }
}
```


### GET /v1/usage

按天统计消耗的流量，可按网络、订单或子用户筛选。流量池网络报告计费字节数；独享订单报告传输字节数。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| from, to | query | 日期格式为 `YYYY-MM-DD`，包含起止日期，采用 UTC。默认：最近 30 天 |
| network | query | `residential`、`mobile`、`isp`、`datacenter`（可选） |
| order_id | query | 仅限一个独享订单（可选） |
| subuser_id | query | 仅限一个子用户（可选） |

请求：

```bash
curl "https://api.proxshift.com/v1/usage?from=2026-09-01&to=2026-09-21&network=residential" \
     -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "network": "residential",
  "days": [
    { "date": "2026-09-20", "bytes": 5368709120, "requests": 184220 },
    { "date": "2026-09-21", "bytes": 1073741824, "requests": 40118 }
  ],
  "total_bytes": 6442450944
}
```


## 凭据、子用户与白名单


### GET /v1/credentials

账户用于共享网关的用户名和密码。

请求：

```bash
curl https://api.proxshift.com/v1/credentials -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "username": "u7f3a9c",
  "password": "kq2Lm8Pz1r",
  "hosts": { "residential": "res.proxshift.com", "mobile": "mob.proxshift.com" },
  "ports": { "http": 9000, "socks5": 9001 }
}
```


### POST /v1/credentials/rotate

生成新密码。旧密码仍可继续使用十分钟。

请求：

```bash
curl -X POST https://api.proxshift.com/v1/credentials/rotate -H "Authorization: Bearer TOKEN"
```

响应：

```json
{ "username": "u7f3a9c", "password": "Xr4Nv7Qw2t", "previous_valid_until": "2026-09-21T09:24:00Z" }
```


### POST /v1/subusers

创建子用户：一组额外的凭据，并拥有独立的流量上限。`GET /v1/subusers` 可列出子用户；`PATCH /v1/subusers/{id}` 可更改上限或将其禁用；`DELETE` 可将其删除。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| label | body | 自由文本，将显示在用量报告中 |
| limit_gb | body | 所有流量池网络合计的流量上限（以 GB 为单位）；设为 `null` 表示不设上限 |
| networks | body | 允许使用的流量池网络数组，默认为 `["residential","mobile"]` |

请求：

```bash
curl -X POST https://api.proxshift.com/v1/subusers \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"label":"client-acme","limit_gb":50}'
```

响应：

```json
{
  "id": "sub_9d2x",
  "label": "client-acme",
  "username": "u7f3a9c-acme",
  "password": "Pm3Kz8Rt5v",
  "limit_gb": 50,
  "used_gb": 0,
  "networks": ["residential", "mobile"],
  "enabled": true
}
```


### GET /v1/whitelist

无需凭据即可连接的地址。

请求：

```bash
curl https://api.proxshift.com/v1/whitelist -H "Authorization: Bearer TOKEN"
```

响应：

```json
{ "items": [ { "ip": "198.51.100.23", "label": "worker-1", "added_at": "2026-09-19T10:02:11Z" } ] }
```


### POST /v1/whitelist

添加 IPv4 地址（每个账户最多 50 个）。`DELETE /v1/whitelist/{ip}` 可删除一个地址。更改将在一分钟内生效。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| ip | body | 公网 IPv4 地址 |
| label | body | 可选的自由文本 |

请求：

```bash
curl -X POST https://api.proxshift.com/v1/whitelist \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"ip":"198.51.100.23","label":"worker-1"}'
```

响应：

```json
{ "ip": "198.51.100.23", "label": "worker-1", "added_at": "2026-09-21T09:15:40Z" }
```


## 定价


### GET /v1/pricing（公开，无需令牌）

已公布的价目表：按 GB 计价的阶梯价格、独享代理租期、位置分区和批量折扣。数据与网站一致，无需令牌。

请求：

```bash
curl https://api.proxshift.com/v1/pricing
```

响应：

```json
{
  "currency": "USD",
  "residential": { "unit": "GB", "tiers": [ { "min_gb": 1, "price": "2.45" }, { "min_gb": 100, "price": "1.54" } ] },
  "isp": {
    "terms": [ { "days": 30, "per_month": "1.12" }, { "days": 90, "per_month": "0.99" } ],
    "zones": { "a": { "label": "United States", "mult": 1.0, "codes": ["US"] } },
    "volume_discounts": [ { "min_ips": 10, "pct": 5 } ]
  }
}
```


## 订单与代理列表


### POST /v1/orders

购买流量池网络的流量，或租用独享地址或设备。购买成功后将从钱包扣款；请发送 `Idempotency-Key`。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| network | body | `residential`, `mobile`, `isp`, `datacenter`, `mobile_device` |
| gb | body | 流量池网络：要购买的 GB 数（价格阶梯根据该数量确定） |
| country | body | 独享代理：地址的 ISO 国家/地区代码 |
| city | body | 独享代理：提供服务时可指定城市值（可选） |
| carrier_asn | body | 移动设备：首选运营商的 AS 编号（可选） |
| quantity | body | 独享代理：地址或设备数量 |
| term_days | body | 独享代理：`1`、`30`、`60` 或 `90`（`1` 仅适用于 ISP 和移动设备） |

请求：

```bash
curl -X POST https://api.proxshift.com/v1/orders \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -H "Idempotency-Key: 5d1c7e2a-order-de-isp" \
     -d '{"network":"isp","country":"DE","quantity":10,"term_days":90}'
```

响应：

```json
{
  "id": "ord_7hq4",
  "network": "isp",
  "country": "DE",
  "quantity": 10,
  "term_days": 90,
  "starts_at": "2026-09-21T09:20:00Z",
  "ends_at": "2026-12-20T09:20:00Z",
  "total_usd": "33.86",
  "status": "provisioning"
}
```


### GET /v1/orders

所有订单，最新的排在最前。`GET /v1/orders/{id}` 返回一个订单；配置完成后也会包含其地址。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| status | query | `provisioning`、`active`、`ended`（可选） |
| network | query | 按网络筛选（可选） |

请求：

```bash
curl "https://api.proxshift.com/v1/orders?status=active" -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "items": [ { "id": "ord_7hq4", "network": "isp", "country": "DE", "quantity": 10, "status": "active", "ends_at": "2026-12-20T09:20:00Z" } ],
  "next_cursor": null
}
```


### POST /v1/orders/{id}/renew

将独享订单延长一个租期，并保留相同地址。订单处于有效状态时可执行此操作。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| term_days | body | `30`、`60` 或 `90`；默认：订单当前租期 |

请求：

```bash
curl -X POST https://api.proxshift.com/v1/orders/ord_7hq4/renew \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -H "Idempotency-Key: renew-ord_7hq4-2026-12" -d '{"term_days":90}'
```

响应：

```json
{ "id": "ord_7hq4", "ends_at": "2027-03-20T09:20:00Z", "total_usd": "33.86", "status": "active" }
```


### GET /v1/proxies

你在各订单中的独享地址。`format=txt` 返回纯文本 `ip:port:user:pass` 行，每个地址一行，可直接用于任何工具。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| network | query | `isp`、`datacenter`、`mobile_device`（可选） |
| order_id | query | 仅限一个订单（可选） |
| format | query | `json`（默认）或 `txt` |

请求：

```bash
curl "https://api.proxshift.com/v1/proxies?network=isp&format=txt" -H "Authorization: Bearer TOKEN"
```

响应：

```json
203.0.113.42:8000:u7f3a9c:kq2Lm8Pz1r
203.0.113.57:8000:u7f3a9c:kq2Lm8Pz1r
```


## 设备


### GET /v1/devices

你的独享移动设备及其当前 IP、运营商和轮换设置。`GET /v1/devices/{id}` 返回一台设备。

请求：

```bash
curl https://api.proxshift.com/v1/devices -H "Authorization: Bearer TOKEN"
```

响应：

```json
{
  "items": [
    {
      "id": "dev_8k2m",
      "order_id": "ord_2ps9",
      "country": "US",
      "carrier": "T-Mobile",
      "endpoint": { "ip": "198.51.100.9", "http": 8000, "socks5": 8001 },
      "current_ip": "172.58.19.204",
      "rotate_every_minutes": null,
      "last_rotated_at": "2026-09-21T08:50:12Z",
      "ends_at": "2026-11-20T09:20:00Z"
    }
  ],
  "next_cursor": null
}
```


### POST /v1/devices/{id}/rotate

立即向运营商申请新 IP。设备使用新地址恢复在线后返回响应；正在进行的连接会中断。控制面板中的轮换链接调用同一操作，但使用签名密钥而非令牌。

请求：

```bash
curl -X POST https://api.proxshift.com/v1/devices/dev_8k2m/rotate -H "Authorization: Bearer TOKEN"
```

响应：

```json
{ "id": "dev_8k2m", "current_ip": "172.58.22.77", "rotated_at": "2026-09-21T09:31:05Z" }
```


### PATCH /v1/devices/{id}

更改轮换计时器。设为 `null` 可将其禁用。

| 字段 | 位置 | 描述 |
| --- | --- | --- |
| rotate_every_minutes | body | 2 到 1440 之间的整数，或 `null` |

请求：

```bash
curl -X PATCH https://api.proxshift.com/v1/devices/dev_8k2m \
     -H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
     -d '{"rotate_every_minutes":10}'
```

响应：

```json
{ "id": "dev_8k2m", "rotate_every_minutes": 10 }
```


来源：https://proxshift.com/zh/docs/api