API
订单与购买
购买分两次请求:先报价,再带 Idempotency-Key 请求头下单。使用相同值重复发送购买请求,将返回第一个订单,不会重复扣款。
更新于 2026年11月22日
价格与库存#
| 请求 | 返回内容 |
|---|---|
| GET /pricing/me | 账户所有产品和期限的价格。 |
| GET /catalog/availability?proxy_type=isp | 当前可购买的地区:datacenter、isp、mtproto 或 residential。 |
| GET /mobile/locations?in_stock=true | 移动代理地区及运营商、价格和功能。地区标识即其 location_code。 |
第 1 步:报价#
POST /orders/quote 返回新订单当前的价格,不会下单。需要 read 或 purchase 权限。
| 字段 | 取值 |
|---|---|
| proxy_type | datacenter、isp、residential、mobile 或 mtproto |
| location_code | 国家代码如 US、城市如 us_la,或移动地区标识 |
| proxy_count | 1 至 1000。住宅代理为 GB 数 |
| duration_days | 1 至 365 |
| variant | 可选。web 为 Telegram WEB 代理,pro 为 Residential Pro |
| features | 可选,仅限移动代理。所需的设备功能 |
响应包含 unit_price(每个代理的价格,住宅代理为每 GB)、total、balance 和 enough_balance。优惠码或一次性推荐折扣只会降低扣款金额。
第 2 步:购买#
POST /orders 接受相同字段,另加 location_name(控制台显示的名称)、报价中的 unit_price 和可选的 promo_code。需要 purchase 权限。
PLAN='{"proxy_type":"datacenter","location_code":"US","proxy_count":2,"duration_days":30}'
# 1. The price. Nothing is bought.
PRICE=$(curl -s https://proxya.co/api/v1/orders/quote \
-H "Authorization: Bearer $PROXYA_API_KEY" \
-H "Content-Type: application/json" \
-d "$PLAN" | jq -r .unit_price)
# 2. The purchase. One key per purchase, the same key on every retry.
KEY=$(uuidgen)
curl https://proxya.co/api/v1/orders \
-H "Authorization: Bearer $PROXYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $KEY" \
--max-time 300 \
-d "$(echo "$PLAN" | jq --arg p "$PRICE" '. + {location_name: "United States", unit_price: $p}')"Idempotency-Key#
- 使用密钥进行的购买、续费和恢复必须带
Idempotency-Key请求头:1 至 128 个可打印 ASCII 字符,每次购买使用新值。 - 24 小时内,相同值和相同请求体的请求返回第一次的结果:同一订单或同一错误,不会重复扣款。
- 相同值配不同请求体返回
409。第一个请求尚在执行时重复发送也返回409。 - 失败的购买不会以相同值重试。请先查看订单列表,再用新值购买。
unit_price 必须与当前价格一致。若两步之间价格变动,购买返回 400。请重新报价后再购买。
订单#
curl "https://proxya.co/api/v1/orders?status=active&limit=50" \
-H "Authorization: Bearer $PROXYA_API_KEY"
curl https://proxya.co/api/v1/orders/$ORDER_ID \
-H "Authorization: Bearer $PROXYA_API_KEY"GET /orders支持status、proxy_type、search、page和最大 100 的limit。GET /orders/{id}返回订单及其代理和renew_options。{id}为订单id或order_number。- 状态:
pending、provisioning、active、expiring、suspended、terminated、expired、cancelled。provisioning表示仍在开通,请稍后再查询。 - 没有 credentials 权限时,代理的用户名、密码和链接返回为空,订单带有
credentials_hidden: true。
续费#
订单中的 renew_options 列出可续费的所有期限及当前每个代理的价格。POST /orders/{id}/extend 接受该列表中的 duration_days 和 unit_price,并需要 Idempotency-Key。
import uuid
order = session.get(f"{API}/orders/{order_id}", timeout=30).json()
option = next(o for o in order["renew_options"] if o["duration_days"] == 30)
renewed = session.post(
f"{API}/orders/{order_id}/extend",
json={"duration_days": option["duration_days"], "unit_price": str(option["unit_price"])},
headers={"Idempotency-Key": str(uuid.uuid4())},
timeout=300,
)
renewed.raise_for_status()
print(renewed.json()["expires_at"])POST /orders/{id}/restore 使用相同请求体,可在终止后 7 天内恢复 ISP 或数据中心订单,IP 和凭据保持不变。各产品的规则见 订单与续费。
没有找到答案?
网站在线客服 24 小时回复。通过 Telegram 联系通常最快,提交工单会通过邮件回复。