文档中心 - 移动代理使用指南

基础URL

https://api.proxies.sx/v1

认证方式

所有API请求需要通过API密钥进行认证。您可以从控制面板获取您的API密钥。

请求头: X-API-Key: psx_your_api_key_here

API密钥权限范围

权限范围	说明
ports:read	读取端口信息
ports:write	创建、更新、删除端口
ports:rotate	轮换端口到新设备
billing:read	读取账单和支付历史
traffic:read	读取流量使用数据
account:read	读取账户信息

快速入门指南

第1步: 检查您的资源

curl https://api.proxies.sx/v1/account/summary \
  -H "X-API-Key: psx_your_key"

第2步: 获取可用位置

curl https://api.proxies.sx/v1/countries/with-devices \
  -H "X-API-Key: psx_your_key"

第3步: 创建端口

curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"COUNTRY_ID","expiresAt":86400}'

第4步: 使用您的代理

# HTTP代理
http://proxyLogin:proxyPassword@serverIp:httpPort

# SOCKS5代理
socks5://proxyLogin:proxyPassword@serverIp:socksPort

第5步: 需要时轮换IP

# 选项A: API轮换（需要认证）
curl -X POST https://api.proxies.sx/v1/ports/PORT_ID/rotate \
  -H "X-API-Key: psx_your_key"

# 选项B: 令牌轮换（无需认证！）
curl https://api.proxies.sx/rotate/YOUR_ROTATION_TOKEN

参考数据端点

GET/v1/countries/with-devices权限: ports:read

获取有可用设备的国家及空闲设备数量

请求示例

curl https://api.proxies.sx/v1/countries/with-devices \
  -H "X-API-Key: psx_your_key"

响应

[
  {
    "_id": "69276bf1f547dfc948699263",
    "name": "Germany",
    "code": "DE",
    "iso3": "DEU",
    "phoneCode": "+49",
    "freeDeviceCount": 26
  },
  {
    "_id": "69276bf1f547dfc9486992b4",
    "name": "United Kingdom",
    "code": "GB",
    "iso3": "GBR",
    "phoneCode": "+44",
    "freeDeviceCount": 21
  }
]

GET/v1/carriers/country/:countryId?withDevice=true权限: ports:read

获取某国家的运营商及空闲设备数量

请求示例

curl "https://api.proxies.sx/v1/carriers/country/69276bf1f547dfc948699263?withDevice=true" \
  -H "X-API-Key: psx_your_key"

响应

[
  {
    "_id": "69276bf5f547dfc94869f2dc",
    "name": "Vodafone D2 GmbH",
    "brand": "Vodafone",
    "mcc": "262",
    "mnc": "02",
    "technology": "LTE",
    "freeDeviceCount": 19
  },
  {
    "_id": "69276bf5f547dfc94869f2df",
    "name": "Telefónica Germany GmbH & Co. oHG",
    "brand": "O2",
    "technology": "LTE",
    "freeDeviceCount": 7
  }
]

GET/v1/tariffs权限: ports:read

获取可用套餐和价格（包含开发者友好的计算字段）

请求示例

curl https://api.proxies.sx/v1/tariffs \
  -H "X-API-Key: psx_your_key"

响应

[
  {
    "_id": "69414767d149cecffee56788",
    "type": "PortsShared",
    "price": 10,
    "portRange": { "min": 1, "max": 10 },
    "category": "shared",
    "resourceType": "ports",
    "pricePerUnit": 10,
    "unitType": "slot",
    "billingPeriod": "monthly",
    "displayName": "共享端口槽位 (1-10)"
  },
  {
    "_id": "69414788d149cecffee567a0",
    "type": "TrafficShared",
    "price": 4,
    "trafficRange": { "min": 1, "max": 10 },
    "category": "shared",
    "resourceType": "traffic",
    "pricePerUnit": 4,
    "unitType": "gb",
    "billingPeriod": "one-time",
    "displayName": "共享流量 (1-10 GB)"
  }
]

端口管理端点

GET/v1/ports权限: ports:read

列出所有端口，包含连接详情、设备信息和流量使用情况

请求示例

curl https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key"

响应

[
  {
    "_id": "6935a7065cb903907b750c64",
    "id": "6935a7065cb903907b750c64",
    "name": "psx_8cc33c_91vjml",
    "displayName": "代理 #1",

    "httpPort": 8522,
    "socksPort": 5522,
    "serverIp": "138.201.158.43",
    "proxyLogin": "user_8cc33c91vjml",
    "proxyPassword": "gyQ4n6hP8R",

    "slotType": "shared",
    "exclusive": false,
    "osFingerprint": "windows:1",

    "suspended": false,
    "status": "active",
    "expiresAt": 1765210246994,

    "rotationToken": "32c2144a26f1ff1a3a0b79c4e31b7369",
    "rotationSettings": {
      "enabled": true,
      "intervalMinutes": 30,
      "intervalSeconds": 1800,
      "lastRotatedAt": "2025-12-17T09:30:00.000Z",
      "rotationCount": 5
    },

    "usedTraffic": 1.5,
    "rotationLink": "https://api.proxies.sx/rotate/32c2144a26f1ff1a3a0b79c4e31b7369",

    "device": {
      "_id": "69280411c01b1bb60efc4ab7",
      "name": "dongle501_de",
      "country": { "name": "Germany", "code": "DE" },
      "carrier": { "name": "Vodafone D2 GmbH", "brand": "Vodafone" },
      "region": { "name": "Berlin" }
    }
  }
]

POST/v1/ports权限: ports:write

创建新端口（需要已购买的端口槽位）

请求体

{
  "countryId": "69276bf1f547dfc948699263",  // 必填
  "expiresAt": 86400,                        // 必填（秒: 86400=24小时）
  "carrierId": "carrier_id",                 // 可选
  "osFingerprint": "windows:1"               // 可选
}

请求示例

curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"69276bf1f547dfc948699263","expiresAt":86400}'

响应

{
  "_id": "675123abc...",
  "displayName": "代理 #1",
  "serverIp": "62.30.207.124",
  "httpPort": 8002,
  "socksPort": 5002,
  "proxyLogin": "自动生成",
  "proxyPassword": "自动生成",
  "expiresAt": 1702320967890
}

GET/v1/ports/:id权限: ports:read

获取端口完整详情，包括设备信息和轮换设置

请求示例

curl https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64 \
  -H "X-API-Key: psx_your_key"

GET/v1/ports/:id/status权限: ports:read

获取端口在线/离线状态

响应

{
  "status": "online",
  "isActive": true,
  "lastChecked": "2025-12-17T10:00:00.000Z",
  "expiresAt": 1765210246994
}

GET/v1/ports/:id/ping权限: ports:read

测试代理连接并测量响应时间

响应

{
  "success": true,
  "ip": "109.40.240.170",
  "responseTime": 513,
  "testTime": "2025-12-17T10:37:36.621Z"
}

GET/v1/ports/:id/ip权限: ports:read

获取端口当前公网IP地址

响应

{
  "publicIp": "109.40.240.170",
  "serverIp": "138.201.158.43"
}

DELETE/v1/ports/:id权限: ports:write

删除端口（从调制解调器和数据库中移除）

请求示例

curl -X DELETE https://api.proxies.sx/v1/ports/675123abc... \
  -H "X-API-Key: psx_your_key"

响应

{
  "message": "端口删除成功"
}

IP轮换端点

POST/v1/ports/:id/rotate权限: ports:rotate

轮换端口获取新IP。共享端口切换设备（5分钟冷却），独享端口使用飞行模式（1分钟冷却）。

请求示例

curl -X POST https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64/rotate \
  -H "X-API-Key: psx_your_key"

响应（共享设备）

{
  "success": true,
  "portId": "6935a7065cb903907b750c64",
  "oldDeviceId": "69280411c01b1bb60efc4ab7",
  "newDeviceId": "69280412c01b1bb60efc4ab8",
  "oldIp": "109.40.240.170",
  "newIp": "109.40.241.55",
  "rotationDurationMs": 2450,
  "rotationCount": 5,
  "message": "端口轮换成功"
}

响应（独享设备 - 飞行模式）

{
  "success": true,
  "portId": "6935a7065cb903907b750c64",
  "oldIp": "109.40.240.170",
  "rotationDurationMs": 1523,
  "message": "已通过飞行模式触发IP重置。新IP将在10-30秒内可用。",
  "isAirplaneMode": true
}

GET/v1/ports/:id/can-rotate权限: ports:read

检查端口是否可以轮换及冷却状态

响应（可轮换）

{
  "canRotate": true,
  "availableDevices": 26
}

响应（冷却中）

{
  "canRotate": false,
  "reason": "频率限制。需等待180秒后才能再次轮换。",
  "nextRotationAt": "2025-12-17T10:05:00.000Z",
  "cooldownRemaining": 180
}

PATCH/v1/ports/:id/rotation-settings权限: ports:write

启用/配置自动轮换。间隔单位为秒：300-86400（共享），60-86400（独享）

请求体

{
  "enabled": true,
  "intervalSeconds": 1800,  // 300-86400（共享）或60-86400（独享）- 单位：秒
  "matchCarrier": false,    // 轮换时保持同一运营商
  "matchCity": false        // 轮换时保持同一城市/地区
}

请求示例

curl -X PATCH https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64/rotation-settings \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"intervalSeconds":1800}'

响应

{
  "enabled": true,
  "intervalMinutes": 30,
  "intervalSeconds": 1800,
  "lastRotatedAt": "2025-12-17T02:24:17.359Z",
  "rotationCount": 7,
  "matchCarrier": false,
  "matchCity": false,
  "excludedDeviceIds": [],
  "_id": "694166405313a0aecb26ca09",
  "id": "694166405313a0aecb26ca09"
}

// 注意: 响应同时包含intervalMinutes（旧版）和intervalSeconds（主要）。
// 新集成请始终使用intervalSeconds。

GET/v1/ports/:id/rotation-history权限: ports:read

获取端口的轮换历史

响应

{
  "rotations": [
    {
      "_id": "6941a706...",
      "portId": "6935a7065cb903907b750c64",
      "fromDeviceId": "69280411c01b1bb60efc4ab7",
      "toDeviceId": "69280412c01b1bb60efc4ab8",
      "fromIp": "109.40.240.170",
      "toIp": "109.40.241.55",
      "triggerType": "api_token",
      "success": true,
      "rotationDurationMs": 2450,
      "country": "Germany",
      "carrier": "Vodafone",
      "createdAt": "2025-12-17T09:55:00.000Z"
    }
  ],
  "total": 5
}

// triggerType值: "manual"（手动）, "automatic"（自动）, "api_token"（API令牌）

账户和计费端点

GET/v1/account权限: account:read

完整账户详情，包含钱包、订阅、端口和状态标志

响应

{
  "user": {
    "_id": "6935a45d04523391208cc33c",
    "email": "user@example.com",
    "role": "customer",
    "isActive": true
  },
  "wallet": {
    "totalDeposited": 100.00,
    "totalSpent": 50.00,
    "availableBalance": 50.00,
    "currency": "USD"
  },
  "subscription": {
    "shared": {
      "active": true,
      "slots": { "total": 5, "used": 2, "available": 3 },
      "traffic": { "purchasedGB": 10, "usedGB": 2.5, "availableGB": 7.5 },
      "expiresAt": "2025-01-15T00:00:00.000Z",
      "daysRemaining": 29
    },
    "private": {
      "active": false,
      "slots": { "total": 0, "used": 0, "available": 0 }
    }
  },
  "status": {
    "hasActiveSubscription": true,
    "hasAvailableSlots": true,
    "hasAvailableTraffic": true,
    "lowBalance": false,
    "lowTraffic": false
  }
}

GET/v1/account/summary权限: account:read

轻量级账户摘要，用于仪表板小组件和快速状态检查

响应

{
  "balance": 50.00,
  "currency": "USD",
  "shared": {
    "slots": { "total": 5, "used": 2, "available": 3 },
    "trafficGB": { "total": 10, "used": 2.5, "available": 7.5 },
    "expiresAt": "2025-01-15T00:00:00.000Z",
    "daysRemaining": 29
  },
  "private": {
    "slots": { "total": 0, "used": 0, "available": 0 },
    "trafficGB": { "total": 0, "used": 0, "available": 0 }
  },
  "alerts": [
    { "type": "low_traffic", "message": "流量即将耗尽", "severity": "info" }
  ]
}

GET/v1/account/usage?period=30d权限: traffic:read

按端口和槽位类型的流量使用明细（7d、30d或90d周期）

响应

{
  "period": "30d",
  "generatedAt": "2025-12-17T10:00:00.000Z",
  "traffic": {
    "shared": {
      "totalUsedGB": 2.5,
      "portCount": 2,
      "byPort": [
        { "portId": "6935a706...", "portName": "代理 #1", "usedGB": 1.5 },
        { "portId": "6935a707...", "portName": "代理 #2", "usedGB": 1.0 }
      ]
    },
    "combined": {
      "totalUsedGB": 2.5,
      "portCount": 2
    }
  }
}

GET/v1/traffic/balance-breakdown权限: traffic:read

详细的流量和计费明细，包含公式说明

响应

{
  "totalPayments": 100.00,
  "adminPaymentCredits": 0,
  "totalPurchases": 50.00,
  "trafficUsedGB": 2.5,
  "purchasedTrafficGB": 10,
  "availableTrafficGB": 7.5,
  "pricePerGB": 4,
  "balance": 50.00,
  "currency": "USD",
  "formula": "余额 = (总充值 + 管理员赠送) - 总消费"
}

完整工作流程示例

# 1. 首先检查账户状态
curl https://api.proxies.sx/v1/account/summary \
  -H "X-API-Key: psx_your_key"

# 2. 获取可用国家
curl https://api.proxies.sx/v1/countries/with-devices \
  -H "X-API-Key: psx_your_key"

# 3. 获取德国的运营商
curl "https://api.proxies.sx/v1/carriers/country/69276bf1f547dfc948699263?withDevice=true" \
  -H "X-API-Key: psx_your_key"

# 4. 创建24小时端口
curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"69276bf1f547dfc948699263","expiresAt":86400}'

# 5. 列出您的端口
curl https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key"

# 6. 轮换端口获取新IP
curl -X POST https://api.proxies.sx/v1/ports/PORT_ID/rotate \
  -H "X-API-Key: psx_your_key"

# 7. 启用自动轮换（每30分钟 = 1800秒）
curl -X PATCH https://api.proxies.sx/v1/ports/PORT_ID/rotation-settings \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"intervalSeconds":1800}'

# 8. 查看轮换历史
curl https://api.proxies.sx/v1/ports/PORT_ID/rotation-history \
  -H "X-API-Key: psx_your_key"

# 9. 更改操作系统指纹为Windows
curl -X PATCH https://api.proxies.sx/v1/ports/PORT_ID/os-fingerprint \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"osFingerprint":"windows:1"}'

# 10. 获取使用分析
curl "https://api.proxies.sx/v1/account/usage?period=30d" \
  -H "X-API-Key: psx_your_key"

# 11. 完成后删除端口
curl -X DELETE https://api.proxies.sx/v1/ports/PORT_ID \
  -H "X-API-Key: psx_your_key"

代理连接格式

HTTP代理

http://用户名:密码@服务器IP:HTTP端口

SOCKS5代理

socks5://用户名:密码@服务器IP:SOCKS5端口

示例

http://user_abc123:pass456@138.201.158.43:8522
socks5://user_abc123:pass456@138.201.158.43:5522

开发者关键响应字段

端口对象字段

slotType - "shared"（共享）| "private"（独享）
status - "active"（活动）| "suspended"（暂停）| "expired"（过期）
rotationToken - 无需认证的轮换令牌
trafficSummary - { usedMB, usedGB }
healthStatus - "healthy"（健康）| "degraded"（降级）| "offline"（离线）
osFingerprint - 当前操作系统伪装设置

账户对象字段

wallet - 详细余额明细
subscription - 槽位和流量可用性
status.hasAvailableSlots - 布尔标志
status.lowTraffic - 布尔标志
status.nearingExpiration - 布尔标志

准备好开始集成了吗？

从控制面板获取您的API密钥，开始构建。

获取API密钥联系支持

PROXIES.SX API 文档

基础URL

认证方式

API密钥权限范围

快速入门指南

第1步: 检查您的资源

第2步: 获取可用位置

第3步: 创建端口

第4步: 使用您的代理

第5步: 需要时轮换IP

参考数据端点

端口管理端点

IP轮换端点

账户和计费端点

完整工作流程示例

代理连接格式

开发者关键响应字段

端口对象字段

账户对象字段

准备好开始集成了吗？