客户 API 开发文档

接入步骤

1. 1. 正式环境“我的 API”页面提供沙盒联调入口。进入测试环境后，登录客户中心，进入“我的 API”，创建 sbx_app_ 开头的 App ID，并立即保存 API Secret。
2. 2. 把 PUPPYIP_API_BASE_URL、PUPPYIP_API_APP_ID 和 PUPPYIP_API_SECRET 放进服务端环境变量，不要写进前端页面。
3. 3. 先请求 GET /api/v1/account 验证签名，再请求 GET /api/v1/offers 获取可用产品。
4. 4. 创建订单或续费时，为一次业务操作生成一个 Idempotency-Key。同一次操作的超时或网络重试必须复用原 key 和完全相同的原始 body；只有发起新的业务操作时才更换 key。
5. 5. 下单成功表示订单已受理。保存返回的 order_no，按响应中的 poll_after_seconds 查询订单详情，直到订单完成或退款。
6. 6. 服务端请求建议设置稳定的 User-Agent，例如 PuppyIP-Integration/1.0，避免默认脚本标识被安全策略误判。
7. 7. 沙盒调通后，回到正式环境创建 live_app_ 开头的 App ID。上线只替换正式环境变量。复制代码示例后，只需要替换环境变量，签名函数、请求头和接口路径不需要重写。

网站接入流程

使用 API 连接您的网站与 PuppyIP，完成商品展示、购买、交付和续费。客户账户、零售价、收款、账本和客服由您的网站管理。

先建立客户与订单的对应关系

API 密钥代表您的 PuppyIP 账户，account、wallet、orders 和 proxies 返回该账户的数据。请在自己的服务端保存“本地客户 → 本地订单 → order_no → proxy_id”的对应关系，并在展示或操作前验证客户归属。不要把整个 API 账户的订单或 IP 列表直接返回给每位客户。

note 仅为订单备注，不作为客户权限或查询条件，当前响应也不返回 note。API Secret 和连接凭据不得进入公开页面或日志。

1. 展示商品

   GET /api/v1/offers

   通过 /offers/available 查询可售商品，也可使用 /offers 获取商品列表。遍历分页，按 offer_code 更新商品；用 include=cidr_stock,line_group 获取号段库存和普通／推荐分类。

2. 确认报价与库存

   GET /api/v1/offers

   按数量和时长查询报价，您的零售价自行管理。指定号段时同时检查 cidr_stock 与 max_quantity；0 为无库存，null 为未知。查询不锁价、不预留库存。

3. 收款与余额

   GET /api/v1/wallet

   客户向您的网站付款；API 下单和续费从您的 PuppyIP 钱包扣款。两套资金记录分别核对，API 不会替您向客户收款或充值。

4. 创建订单

   POST /api/v1/orders

   提交前保存本地订单、Idempotency-Key 和原始 JSON 字节。超时重试使用相同键、相同请求体和新签名；返回 201 后保存 order_no，不把受理当作交付完成。

5. 交付 IP

   GET /api/v1/orders/{order_no}

   按 poll_after_seconds 查询，遇到 429 遵循 Retry-After。只交付 delivery.available 允许读取的连接；部分交付模式下还需检查 complete 与 remaining_count。

6. 更新连接信息

   GET /api/v1/proxies/{proxy_id}

   保存 proxy_id，读取最新 host、port、凭据和到期时间，并更新自己的记录。回调发送已开启时，收到通知先验签再查询当前状态；否则继续轮询。API 不会自动修改客户软件的连接配置。

7. 续费与失败处理

   POST /api/v1/proxies/renew

   按本地客户归属选择 proxy_ids；逐项检查成功、失败、待确认列表。待确认项不要另起一笔续费。退款字段只说明该笔 PuppyIP 业务的退款，不代表您已向自己的客户退款。

API v1 不提供子客户注册、收款、充值、退款申请、更换 IP 或试用 IP。客户业务流程由您的应用管理。凭据修改需要单独权限，且仅在开放此操作的环境可用。

环境切换

建议把连接信息放在环境变量中。测试使用 PUPPYIP_API_BASE_URL=https://sandbox.puppyip.com 和 sbx_app_ 开头的 App ID；上线改为 PUPPYIP_API_BASE_URL=https://puppyip.com 和 live_app_ 开头的 App ID。测试和上线不需要改请求头、签名函数或接口路径。

PUPPYIP_API_BASE_URL=https://sandbox.puppyip.com
PUPPYIP_API_APP_ID=sbx_app_EXAMPLE_SANDBOX_APP_ID
PUPPYIP_API_SECRET=replace-with-your-secret

当前可用接口

请求头

Canonical String

签名前先把请求拆成 7 行，用换行符 \n 连接：

METHOD
host
path
canonical_query
timestamp
nonce
sha256(body)

GET /api/v1/account 固定示例

GET
puppyip.com
/api/v1/account

2026-06-28T12:00:00+00:00
nonce-empty-body
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

上面这组固定示例使用文档测试 Secret puppyip-docs-test-secret 计算出的签名是 e3c27a2055ad38f16861790294802b9fac81e02e8d72fbeaa87299598785832d。

代码示例

以下示例使用环境变量。请不要把 API Secret 写入前端页面、公开仓库或日志。

curl

curl 只负责发送请求。请先用下方 PHP 或 Node.js 签名函数，为这一次请求生成当前的 TIMESTAMP、NONCE 和 SIGNATURE；不要复制上面的固定算法校验值发送请求，也不要把 Secret 写进 shell 历史。

curl "$PUPPYIP_API_BASE_URL/api/v1/account" \
  -H "X-API-AppId: $PUPPYIP_API_APP_ID" \
  -H "X-API-Timestamp: $TIMESTAMP" \
  -H "X-API-Nonce: $NONCE" \
  -H "X-API-Signature: $SIGNATURE" \
  -H "Accept: application/json" \
  -H "User-Agent: PuppyIP-Integration/1.0"

PHP

$baseUrl = rtrim(getenv('PUPPYIP_API_BASE_URL') ?: 'https://sandbox.puppyip.com', '/');
$appId = getenv('PUPPYIP_API_APP_ID') ?: '';
$secret = getenv('PUPPYIP_API_SECRET') ?: '';
$method = 'GET';
$target = $baseUrl.'/api/v1/account';
$parts = parse_url($target);
$path = $parts['path'] ?? '/';
$rawQuery = $parts['query'] ?? '';
$body = '';
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$nonce = 'nce_'.bin2hex(random_bytes(16));
$host = strtolower($parts['host'] ?? '');

function canonicalQuery(string $rawQuery): string
{
    if ($rawQuery === '') {
        return '';
    }

    $pairs = array_map(function (string $pair): array {
        [$key, $value] = array_pad(explode('=', $pair, 2), 2, '');

        return [rawurlencode(rawurldecode($key)), rawurlencode(rawurldecode($value))];
    }, explode('&', $rawQuery));

    usort($pairs, fn (array $left, array $right): int => $left[0] <=> $right[0] ?: $left[1] <=> $right[1]);

    return implode('&', array_map(fn (array $pair): string => $pair[0].'='.$pair[1], $pairs));
}

$canonical = implode("\n", [
    $method,
    $host,
    $path,
    canonicalQuery($rawQuery),
    $timestamp,
    $nonce,
    hash('sha256', $body),
]);

$signature = hash_hmac('sha256', $canonical, $secret);
$headers = [
    'X-API-AppId: '.$appId,
    'X-API-Timestamp: '.$timestamp,
    'X-API-Nonce: '.$nonce,
    'X-API-Signature: '.$signature,
    'Accept: application/json',
    'User-Agent: PuppyIP-Integration/1.0',
];

$handle = curl_init($target);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($handle);

if ($response === false) {
    throw new RuntimeException(curl_error($handle));
}

echo $response;

Node.js

import crypto from 'node:crypto';

const baseUrl = process.env.PUPPYIP_API_BASE_URL ?? 'https://sandbox.puppyip.com';
const appId = process.env.PUPPYIP_API_APP_ID ?? '';
const secret = process.env.PUPPYIP_API_SECRET ?? '';
const method = 'GET';
const url = new URL('/api/v1/account', baseUrl);
const body = '';
const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
const nonce = `nce_${crypto.randomBytes(16).toString('hex')}`;

const rfc3986 = (value) => encodeURIComponent(value).replace(
  /[!'()*]/g,
  (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
);
const compare = (left, right) => left < right ? -1 : (left > right ? 1 : 0);
const canonicalQuery = (rawQuery) => {
  if (rawQuery === '') return '';

  return rawQuery
    .split('&')
    .map((pair) => {
      const separator = pair.indexOf('=');
      const key = separator === -1 ? pair : pair.slice(0, separator);
      const value = separator === -1 ? '' : pair.slice(separator + 1);

      return [rfc3986(decodeURIComponent(key)), rfc3986(decodeURIComponent(value))];
    })
    .sort((left, right) => compare(left[0], right[0]) || compare(left[1], right[1]))
    .map(([key, value]) => `${key}=${value}`)
    .join('&');
};
const rawQuery = url.search.startsWith('?') ? url.search.slice(1) : url.search;

const canonical = [
  method,
  url.hostname.toLowerCase(),
  url.pathname,
  canonicalQuery(rawQuery),
  timestamp,
  nonce,
  crypto.createHash('sha256').update(body).digest('hex'),
].join('\n');

const signature = crypto
  .createHmac('sha256', secret)
  .update(canonical)
  .digest('hex');

const headers = {
  'X-API-AppId': appId,
  'X-API-Timestamp': timestamp,
  'X-API-Nonce': nonce,
  'X-API-Signature': signature,
  Accept: 'application/json',
  'User-Agent': 'PuppyIP-Integration/1.0',
};

const response = await fetch(url, { method, headers });
console.log(await response.json());

响应包络

所有接口都返回统一 JSON 包络。成功时 success=true，业务数据在 data；失败时 code 是稳定错误码，trace_id 可用于联系支持排查。

{
  "success": true,
  "code": "ok",
  "message": "OK",
  "data": {},
  "timestamp": "2026-06-28T12:00:00+00:00",
  "trace_id": "trc_EXAMPLE_TRACE_ID"
}

查询账户

查看当前 API 密钥所属的账户信息。

所需权限account:read

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 每项操作仅访问当前 API 密钥所属账户。API 不开放更换 IP 或试用 IP。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/account

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "account_id": "acct_0123456789abcdef0123456789",
        "email": "[email protected]",
        "email_verified": true,
        "status": "active",
        "created_at": "2026-11-09T00:00:00+00:00"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询钱包余额

查看 API 购买使用的钱包余额与币种。

所需权限wallet:read

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 核对余额时使用响应的币种与整数金额。此 API 不提供充值操作，沙盒余额没有实际资金价值。
• 金额计算使用整数最小货币单位或精确十进制运算，不要使用二进制浮点数；小数金额字段为保留两位小数的字符串。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/wallet

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "balance_cents": 10000,
        "balance": "100.00",
        "frozen_cents": 0,
        "cash_value": true
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询商品

购买前查询可售商品、价格、时长与可选号段。

所需权限offers:read

请求参数

• 报价按账户价格、查询数量与时长计算，不预留库存；购买前价格和库存可能变化。请勿将不同商品的库存相加。库存值 null 表示未知，不代表 0 或无限。
• 金额计算使用整数最小货币单位或精确十进制运算，不要使用二进制浮点数；小数金额字段为保留两位小数的字符串。
• 原样传回 next_page_token，并保持筛选条件与交付模式不变。标记有效期为 3 天。has_more 为 true 时即使本页为空也应继续；分页不代表冻结快照。
• 沙盒提供普通、推荐和 CIDR 测试商品，号段库存包含 3、0、null；null 表示未知，不能当作 0 或总库存。数量限制按每次请求校验，不模拟全局库存耗尽；返回连接仅用于测试，不代表所选号段的真实出口。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/offers?page_size=200

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "payment_mode": "wallet",
        "offers": [
            {
                "offer_code": "off_0123456789abcdef0123456789",
                "name": "United States - Los Angeles",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles",
                "line_name": "United States - Los Angeles",
                "ip_type": "2",
                "protocol": "0",
                "unit_price_cents": 2000,
                "unit_price": "20.00",
                "base_duration_days": 30,
                "duration_days": [
                    30,
                    60,
                    90
                ],
                "max_quantity": 12,
                "cidrs": [
                    "198.51.100.0/24"
                ]
            }
        ],
        "page_size": 200,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

GET /api/v1/offers?line_group=recommended&include=cidr_stock,line_group&page_size=200

{
  "offer_code": "offer-code-from-response",
  "line_group": "recommended",
  "ip_type": "2",
  "protocol": "0",
  "max_quantity": 20,
  "cidrs": ["198.51.100.0/24", "203.0.113.0/24", "192.0.2.0/24"],
  "cidr_stock": {
    "198.51.100.0/24": 12,
    "203.0.113.0/24": 0,
    "192.0.2.0/24": null
  },
  "stock_updated_at": "2026-11-09T08:00:00+00:00"
}

创建订单

使用钱包购买一个或多个商品，再查询订单获取交付结果。

所需权限orders:write

请求参数

• HTTP 201 表示订单已创建，不代表交付完成。保存 order_no，并按 poll_after_seconds 查询。同一商品不能重复指定同一号段，也不能在同次请求中混用自动分配与指定号段。
• 金额计算使用整数最小货币单位或精确十进制运算，不要使用二进制浮点数；小数金额字段为保留两位小数的字符串。
• 超时后保留原 Idempotency-Key 与完全相同的请求体字节，并使用新的时间戳和 nonce 重试。不要仅因结果尚未完成就换一个键重新购买或续费。
• external_order_no 在当前账户与环境内唯一；同订单号、相同原始请求体重试返回原创建结果，不会再次扣款。不同请求体返回 409 external_order_conflict。查询只在 include=external_order_no 时增加该字段。
• 沙盒 final_partial 至少购买 2 个 IP：交付一部分并退还已确定未交付部分，最终状态 delivered、payment_status=partially_refunded。indeterminate 保持 procurement_blocked，不交付、不自动退款或重复执行。旧 partial 场景仍表示暂时部分交付，随后完成。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: example-create-order-001

{
    "offer_code": "off_0123456789abcdef0123456789",
    "quantity": 1,
    "duration_days": 30
}

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 201

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "order_no": "PSO20261109000000EXAMPLE",
        "status": "procuring",
        "payment_status": "paid",
        "payment_method": "wallet",
        "currency": "CNY",
        "subtotal_cents": 2000,
        "total_cents": 2000,
        "total": "20.00",
        "created_at": "2026-11-09T00:00:00+00:00",
        "items": [
            {
                "name": "United States - Los Angeles",
                "quantity": 1,
                "duration_days": 30,
                "offer_code": "off_0123456789abcdef0123456789",
                "unit_price_cents": 2000,
                "total_price_cents": 2000
            }
        ],
        "delivery": {
            "expected_count": 1,
            "delivered_count": 0,
            "complete": false,
            "available": false
        },
        "poll_after_seconds": 1,
        "refund": null,
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

POST /api/v1/orders
Idempotency-Key: order-demo-001

{
  "duration_days": 30,
  "items": [
    {"offer_code": "sandbox_us_static", "quantity": 2},
    {"offer_code": "sandbox_jp_static", "quantity": 1}
  ]
}

POST /api/v1/orders
Idempotency-Key: order-note-demo-001

{
  "offer_code": "sandbox_us_static",
  "quantity": 2,
  "duration_days": 30,
  "note": "客户A / 业务单号12345"
}

查询订单列表

分页查看当前账户的订单，包括在网站购买的订单。

所需权限orders:read

请求参数

• 列表返回摘要，不包含连接凭据或单项价格。状态按当前交付模式筛选。has_more=true 时，即使本页为空，也需继续翻页。
• 部分交付仅通过 GET 请求的可选请求头开启。不传时，原有交付行为与响应字段保持不变。
• 原样传回 next_page_token，并保持筛选条件与交付模式不变。标记有效期为 3 天。has_more 为 true 时即使本页为空也应继续；分页不代表冻结快照。
• 筛选条件同时生效，后续页必须重复等价条件与交付模式；更改或移除条件返回 invalid_page_token。日期区间包含两端。
• external_order_no 在当前账户与环境内唯一；同订单号、相同原始请求体重试返回原创建结果，不会再次扣款。不同请求体返回 409 external_order_conflict。查询只在 include=external_order_no 时增加该字段。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/orders?page_size=50

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "orders": [
            {
                "order_no": "PSO20261109000000EXAMPLE",
                "status": "delivered",
                "payment_status": "paid",
                "payment_method": "wallet",
                "currency": "CNY",
                "total_cents": 2000,
                "total": "20.00",
                "created_at": "2026-11-09T00:00:00+00:00",
                "items": [
                    {
                        "name": "United States - Los Angeles",
                        "quantity": 1,
                        "duration_days": 30,
                        "offer_code": "off_0123456789abcdef0123456789"
                    }
                ],
                "delivery": {
                    "expected_count": 1,
                    "delivered_count": 1,
                    "complete": true,
                    "available": true
                },
                "poll_after_seconds": null,
                "refund": null
            }
        ],
        "page_size": 50,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询订单详情

查看支付、交付和退款进度，并获取可用的连接信息。

所需权限orders:read

请求参数

• 通过 delivery.available 判断能否读取连接。退款的 currency 与 amount_cents 应独立于订单合计读取，未知退款金额不能当作 0。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。
• 部分交付仅通过 GET 请求的可选请求头开启。不传时，原有交付行为与响应字段保持不变。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/orders/PSO20261109000000EXAMPLE

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "order_no": "PSO20261109000000EXAMPLE",
        "status": "delivered",
        "payment_status": "paid",
        "payment_method": "wallet",
        "currency": "CNY",
        "subtotal_cents": 2000,
        "total_cents": 2000,
        "total": "20.00",
        "created_at": "2026-11-09T00:00:00+00:00",
        "items": [
            {
                "name": "United States - Los Angeles",
                "quantity": 1,
                "duration_days": 30,
                "offer_code": "off_0123456789abcdef0123456789",
                "unit_price_cents": 2000,
                "total_price_cents": 2000
            }
        ],
        "delivery": {
            "expected_count": 1,
            "delivered_count": 1,
            "complete": true,
            "available": true
        },
        "poll_after_seconds": null,
        "refund": null,
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2026-12-09T00:00:00+00:00"
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

订单详情包含 order_no、status、payment_status、payment_method、currency、subtotal_cents、total_cents、total、created_at、items、delivery、poll_after_seconds、refund、proxies。列表只返回安全摘要，不返回代理凭据。refund 为 null 或退款状态对象，含 status、destination、amount_cents、currency、refunded_at。refund.status=succeeded 表示记录的退款已成功，不代表整单已退；是否全退看 payment_status。无法确认的金额、币种或去向返回 null，不能当作 0 元或未退款。amount_cents 必须与其 currency 一起读取，不要按订单币种或当前汇率推算。

订单状态与沙盒场景

查询 IP 列表

分页获取账户下可读取的 IP 连接信息。

所需权限proxies:read

请求参数

• 新接入请显式分页。正式环境同时不传两项分页参数时保留最多 2000 条的旧行为，并非无限返回。筛选不改变账户及过期保留边界。
• 生产 IP 列表保留到期后 72 小时内的资源，expires_at 为 null 的资源也仍可列入。此列表规则不代表单个 IP 详情或沙盒列表存在相同时间限制。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。
• 部分交付仅通过 GET 请求的可选请求头开启。不传时，原有交付行为与响应字段保持不变。
• 原样传回 next_page_token，并保持筛选条件与交付模式不变。标记有效期为 3 天。has_more 为 true 时即使本页为空也应继续；分页不代表冻结快照。
• 筛选条件同时生效，后续页必须重复等价条件与交付模式；更改或移除条件返回 invalid_page_token。日期区间包含两端。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/proxies?page_size=100

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2026-12-09T00:00:00+00:00"
            }
        ],
        "page_size": 100,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询单个 IP

通过已保存的 IP 标识查询最新连接信息。

所需权限proxies:read

请求参数

• 以 proxy_id 关联资源，需要时查询最新连接信息。此接口在 data 中直接返回 IP 对象，没有额外 environment 包装。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。
• 部分交付仅通过 GET 请求的可选请求头开启。不传时，原有交付行为与响应字段保持不变。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/proxies/px_0123456789abcdef0123456789

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "proxy_id": "px_0123456789abcdef0123456789",
        "status": "active",
        "host": "198.51.100.10",
        "port": 10080,
        "protocol": "0",
        "username": "example_user",
        "password": "example_password",
        "connection": "198.51.100.10:10080:example_user:example_password",
        "socks5_uri": "socks5://example_user:[email protected]:10080",
        "ip_type": "2",
        "country_code": "US",
        "region": "Los Angeles",
        "line_name": "US Los Angeles 2",
        "starts_at": "2026-11-09T00:00:00+00:00",
        "expires_at": "2026-12-09T00:00:00+00:00"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

续费 IP

使用钱包延长所选 IP 的有效期，并逐个查看续费结果。

所需权限proxies:write

请求参数

• HTTP 200 不代表所有 IP 都续费成功，请检查三个结果标识列表与 line_items。全部失败时 HTTP 为 422，data 仍返回相同结构的结果。待确认项需要核对结果，不要重复创建续费。
• 金额计算使用整数最小货币单位或精确十进制运算，不要使用二进制浮点数；小数金额字段为保留两位小数的字符串。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。
• 超时后保留原 Idempotency-Key 与完全相同的请求体字节，并使用新的时间戳和 nonce 重试。不要仅因结果尚未完成就换一个键重新购买或续费。
• 沙盒仅成功项延长有效期；确定失败项退还对应费用，未知项保留扣款且不自动重续。failed 返回 422 operation_failed，结果保留在 data；其他场景返回 200。相同幂等键重放原结果，未决 IP 不接受新的续费。
• 不传 sync 或传 true 时保留原同步结果。sync=false 时 proxy_ids 必须不重复；首次返回 HTTP 202，data={"operation_id":"rop_...","status":"processing"}，不代表续费成功。请查询 GET /api/v1/proxies/renewal-operations/{operation_id}。重试原键和原请求体可能重放最初的受理响应，进度应查询任务。正式环境需开放异步续费，沙盒使用隔离模拟。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

POST /api/v1/proxies/renew
Content-Type: application/json
Idempotency-Key: example-renew-001

{
    "proxy_ids": [
        "px_0123456789abcdef0123456789"
    ],
    "duration_days": 30
}

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "status": "completed",
        "currency": "CNY",
        "total_cents": 2000,
        "total": "20.00",
        "charged_cents": 2000,
        "refunded_cents": 0,
        "successful_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [],
        "line_items": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "host": "198.51.100.10",
                "status": "succeeded",
                "duration_days": 30,
                "amount_cents": 2000,
                "amount": "20.00",
                "charged_cents": 2000,
                "refunded_cents": 0
            }
        ],
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2027-01-08T00:00:00+00:00"
            }
        ],
        "wallet": {
            "environment": "production",
            "currency": "CNY",
            "balance_cents": 8000,
            "balance": "80.00",
            "frozen_cents": 0,
            "cash_value": true
        }
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

POST 请求使用 application/json。续费 proxy_ids 必须为非空公共 ID 数组，每次最多 1000 个，每个 ID 最长 80 个字符；超出限制返回 HTTP 422 / validation_error。duration_days 必须为 30 的正整数倍且不超过 1095。分页 token 为不透明字符串；接口响应有可选字段，接入端应容忍新增字段，并对未知业务状态停止自动重试、保留 trace_id 联系支持。

POST /api/v1/proxies/renew
Idempotency-Key: renew-demo-001

{
  "proxy_ids": ["SANDBOX_PROXY_20260629080000_001"],
  "duration_days": 30
}

{
  "status": "completed",
  "total_cents": 12000,
  "charged_cents": 12000,
  "refunded_cents": 0,
  "successful_proxy_ids": ["SANDBOX_PROXY_20260629080000_001"],
  "failed_proxy_ids": [],
  "unresolved_proxy_ids": [],
  "line_items": [{
    "proxy_id": "SANDBOX_PROXY_20260629080000_001",
    "host": "198.51.100.10",
    "status": "succeeded",
    "duration_days": 30,
    "amount_cents": 12000,
    "amount": "120.00",
    "charged_cents": 12000,
    "refunded_cents": 0
  }]
}

查询地区

查看当前商品目录中的地区标识。

所需权限offers:read

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 目录用于筛选导航，不保证指定数量或时长可购买。请用商品接口查询报价与库存，并用 offer_code 下单。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/locations

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "locations": [
            {
                "location_id": "loc_0123456789abcdef0123456789ab",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles"
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询地区树

按国家分组查看地区目录。

所需权限offers:read

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 目录用于筛选导航，不保证指定数量或时长可购买。请用商品接口查询报价与库存，并用 offer_code 下单。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/locations/tree

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "countries": [
            {
                "country_code": "US",
                "country_name": "United States",
                "locations": [
                    {
                        "location_id": "loc_0123456789abcdef0123456789ab",
                        "country_code": "US",
                        "country_name": "United States",
                        "region": "Los Angeles"
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询商品标签

查看当前目录中的普通与推荐分类。

所需权限offers:read

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 目录用于筛选导航，不保证指定数量或时长可购买。请用商品接口查询报价与库存，并用 offer_code 下单。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/tags

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "tags": [
            {
                "code": "recommended",
                "name": {
                    "zh_CN": "推荐",
                    "en": "Recommended"
                }
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询可售商品

获取可售商品及对应的价格、库存和可选号段。

所需权限offers:read

请求参数

• 报价按账户价格、查询数量与时长计算，不预留库存；购买前价格和库存可能变化。请勿将不同商品的库存相加。库存值 null 表示未知，不代表 0 或无限。
• 金额计算使用整数最小货币单位或精确十进制运算，不要使用二进制浮点数；小数金额字段为保留两位小数的字符串。
• 原样传回 next_page_token，并保持筛选条件与交付模式不变。标记有效期为 3 天。has_more 为 true 时即使本页为空也应继续；分页不代表冻结快照。
• 沙盒提供普通、推荐和 CIDR 测试商品，号段库存包含 3、0、null；null 表示未知，不能当作 0 或总库存。数量限制按每次请求校验，不模拟全局库存耗尽；返回连接仅用于测试，不代表所选号段的真实出口。
• 可直接调用此接口，或使用 /offers?selection=highest_stock。支持按数量和时长筛选，每个商品的报价和可选号段以该条返回记录为准。收到 invalid_page_token 时，请从第一页重新查询。查询不预留库存。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/offers/available?page_size=200

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "payment_mode": "wallet",
        "offers": [
            {
                "offer_code": "off_0123456789abcdef0123456789",
                "name": "United States - Los Angeles",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles",
                "line_name": "United States - Los Angeles",
                "ip_type": "2",
                "protocol": "0",
                "unit_price_cents": 2000,
                "unit_price": "20.00",
                "base_duration_days": 30,
                "duration_days": [
                    30,
                    60,
                    90
                ],
                "max_quantity": 12,
                "cidrs": [
                    "198.51.100.0/24"
                ]
            }
        ],
        "page_size": 200,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询公告

读取网站当前已发布的公告。

所需权限account:read

请求参数

• 返回当前网站公告，共 0 或 1 条；has_more 为 false，next_page_token 为 null。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/announcements

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "announcements": [
            {
                "announcement_id": "ann_0123456789abcdef0123456789ab",
                "title": {
                    "zh_CN": "公告",
                    "en": "Announcement"
                },
                "content": "PuppyIP service announcement.",
                "published_at": "2026-11-09T00:00:00+00:00"
            }
        ],
        "page_size": 20,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

修改连接凭据

提交凭据修改任务，再查询各个 IP 的执行结果。

所需权限proxies:credentials

请求参数

• 此操作需要单独的 proxies:credentials 权限，旧密钥不会自动获得。正式环境只有开放此功能时可用；沙盒使用隔离的模拟资源。
• 受理后返回 202 processing。重复原键与原请求体返回同一任务的当前状态；修改请求体返回 409 idempotency_key_conflict，新的请求与未决任务重叠返回 409 operation_in_progress。查询每个 IP 的结果；未决状态不自动再次修改，等待确认。成功项快照不代表此后未发生其他修改。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。
• 超时后保留原 Idempotency-Key 与完全相同的请求体字节，并使用新的时间戳和 nonce 重试。不要仅因结果尚未完成就换一个键重新购买或续费。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

POST /api/v1/proxies/credentials
Content-Type: application/json
Idempotency-Key: example-credentials-001

{
    "proxy_ids": [
        "px_0123456789abcdef0123456789"
    ],
    "random": true
}

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 202

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "cop_documentation_example",
        "status": "processing",
        "successful_proxy_ids": [],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询凭据修改结果

查看指定任务已确认与待确认的结果。

所需权限proxies:credentials

请求参数

• 受理后返回 202 processing。重复原键与原请求体返回同一任务的当前状态；修改请求体返回 409 idempotency_key_conflict，新的请求与未决任务重叠返回 409 operation_in_progress。查询每个 IP 的结果；未决状态不自动再次修改，等待确认。成功项快照不代表此后未发生其他修改。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/proxies/credential-operations/cop_documentation_example

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "cop_documentation_example",
        "status": "processing",
        "successful_proxy_ids": [],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询异步续费

查询已提交的续费任务，不会重新发起续费。

所需权限proxies:write

请求参数

• 不传 sync 或传 true 时保留原同步结果。sync=false 时 proxy_ids 必须不重复；首次返回 HTTP 202，data={"operation_id":"rop_...","status":"processing"}，不代表续费成功。请查询 GET /api/v1/proxies/renewal-operations/{operation_id}。重试原键和原请求体可能重放最初的受理响应，进度应查询任务。正式环境需开放异步续费，沙盒使用隔离模拟。
• 处理中 data 仅含 operation_id 与 status；核实结果后增加现有续费金额、逐项结果、钱包和连接快照。无法核实结果时，manual_review 可能不含金额和钱包字段；缺失不能解释为金额为 0 或已经退款。扣款前失败可带 error，单项 host 可为 null；报价变化会明确失败且不扣款。仅确认失败项可退款，未决项不得另起任务重续。完成结果是快照，最新连接请查询单个 IP。external_order_no 与 remark 仅在异步请求中保存，不增加到本响应。
• 连接密码和完整连接字符串仅保存在可信服务端，不要写入公开页面或日志。时间使用包含 UTC 偏移的 ISO 8601 格式；null 表示未知，不等于 0。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/proxies/renewal-operations/rop_documentation_example

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "rop_documentation_example",
        "status": "processing"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

查询回调设置

查看当前 API 密钥配置的回调订阅。

所需权限webhooks:write

请求参数

无需额外业务参数。请求仍需携带签名请求头。

• 每个 API 密钥管理自己的订阅，需要单独的 webhooks:write 权限，旧密钥不会自动获得。正式环境关闭时，POST 配置返回 403 feature_disabled；已有配置仍可查询或停用。沙盒提供配置与验签文档用于测试，但实际向外发送仍需开启发送功能；配置成功不代表发送已开启。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

GET /api/v1/webhook

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": true,
        "url": "https://example.com/puppyip-webhook",
        "events": [
            "order.updated",
            "renewal.updated",
            "proxy.updated"
        ],
        "version": 1
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

设置回调

设置 HTTPS 接收地址和需要订阅的事件。

所需权限webhooks:write

请求参数

• 每个 API 密钥管理自己的订阅，需要单独的 webhooks:write 权限，旧密钥不会自动获得。正式环境关闭时，POST 配置返回 403 feature_disabled；已有配置仍可查询或停用。沙盒提供配置与验签文档用于测试，但实际向外发送仍需开启发送功能；配置成功不代表发送已开启。
• 使用配置此回调的 API 密钥对应的 API Secret 验签。X-PuppyIP-Timestamp 为 Unix 秒；对 PuppyIP-Webhook-v1\n<timestamp>\n<原始 JSON 字节> 计算 HMAC-SHA256 小写十六进制，其中每个 \n 为一个 LF 换行字节。用恒定时间比较 X-PuppyIP-Signature，并验证时间戳处于接受窗口、X-PuppyIP-Event-ID 与 body.event_id 相同。先验原始字节，再解析 JSON，不要重新编码后验签。
• 仅 HTTP 200 表示接收成功；已经处理过的 event_id 也应返回 200。最多尝试 10 次，重试保留相同 event_id 与正文，但签名时间戳更新。按 event_id 去重，不假定严格顺序或只发送一次。通知用于提示查询当前 API 状态，不能独立作为付款凭据或再次扣款依据。撤销密钥、停用订阅或更改配置可能取消待发送通知。
• 事件对象包含 event_id、event、environment、occurred_at、observed_at、reason、data，不使用 API 的 success 响应包裹。event 为 order.updated、renewal.updated 或 proxy.updated。同一对象的多次变化可能合并为一条通知；occurred_at 为该通知首次触发时间，observed_at 为通知中状态的观察时间。重试保留相同正文，通知不保证覆盖每一次中间状态。
• order.updated 的 data 包含 order_no、status、payment_status、currency、total_cents；proxy.updated 包含 proxy_id、status、expires_at；renewal.updated 包含 status、currency、total_cents、charged_cents、refunded_cents 及 successful_proxy_ids、failed_proxy_ids、unresolved_proxy_ids。无法确认的续费金额可为 null，不能当作 0。通知不含连接密码或连接串，最新连接需通过有权限的 API 查询。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

POST /api/v1/webhook
Content-Type: application/json
Idempotency-Key: example-configure-webhook-001

{
    "url": "https://example.com/puppyip-webhook",
    "events": [
        "order.updated",
        "renewal.updated",
        "proxy.updated"
    ]
}

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": true,
        "url": "https://example.com/puppyip-webhook",
        "events": [
            "order.updated",
            "renewal.updated",
            "proxy.updated"
        ],
        "version": 1
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

停用回调

停用当前 API 密钥的回调订阅。

所需权限webhooks:write

请求参数

• DELETE 需要正常请求签名、webhooks:write 和 Idempotency-Key。在已完成响应的 24 小时重放期内，使用同一 API 密钥、原幂等键和原请求体会重放这次停用结果，不会停用此后重新配置的订阅；新的停用操作请使用新幂等键。正常的 API 轮询查询不受影响。

请求示例

以下为路径与业务参数；完整请求还需携带签名请求头。 查看签名示例

DELETE /api/v1/webhook
Idempotency-Key: example-disable-webhook-001

返回字段

下表列出完整响应字段；data 内为本接口的业务数据。 查看通用响应

响应示例 HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": false,
        "url": null,
        "events": [],
        "version": 2
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

稳定分页

GET /api/v1/offers?page_size=200

{
  "offers": [],
  "page_size": 200,
  "has_more": true,
  "next_page_token": "opaque-token-from-response"
}

请求下一页时，把返回的 next_page_token 原样放入 page_token，并保持相同的 page_size 和筛选条件，例如 GET /api/v1/offers?page_size=200&page_token=...。线路、订单和 IP 列表均使用相同响应字段；线路每页最多 200 条，订单和 IP 的每页上限以接口校验为准。token 绑定当前账号、环境、资源类型和线路筛选条件，篡改、过期、跨账号或更换筛选条件使用都会被拒绝。

以 has_more=false 判断翻页结束；即使 offers 为空或少于 page_size，只要 has_more=true 就继续使用 next_page_token。各页读取当前数据，并非冻结的全目录快照；定期从第一页重新同步，按 offer_code 去重和更新。

订单状态与沙盒场景

创建订单返回 201 后，请使用 PuppyIP 返回的 order_no 查询 GET /api/v1/orders/{order_no}。paid 或 procuring 表示处理中；当 poll_after_seconds 为整数时，等待返回的秒数后再查询，为 null 或订单进入终态时停止轮询。收到 429 时优先遵循 Retry-After。只有 delivery.available=true 时，详情中的 proxies 才可交付客户。

{
  "order_no": "SANDBOX_ORDER_EXAMPLE",
  "status": "procuring",
  "payment_status": "paid",
  "delivery": {
    "expected_count": 3,
    "delivered_count": 1,
    "complete": false,
    "available": false
  },
  "poll_after_seconds": 1,
  "refund": null,
  "proxies": []
}

部分交付读取（可选）

GET /api/v1/orders/{order_no}
X-PuppyIP-Delivery-Mode: partial

正式环境与沙盒均支持该可选请求头，仅作用于 GET /api/v1/orders、GET /api/v1/orders/{order_no}、GET /api/v1/proxies 和 GET /api/v1/proxies/{proxy_id}。未传该请求头或值不为 partial 时，各环境保留原有响应字段、状态和读取行为：正式环境保留整单交付门禁；沙盒订单响应保留整单交付门禁，沙盒代理列表与详情保留原有按账号和沙盒标识读取测试资源的行为。旧客户端无需修改。不影响 POST 请求、原始 JSON 签名、Idempotency-Key 或历史响应重放。

开启后，已付款且仍属于当前账号的已到 IP 可先行读取；未付款、全额退款、缺失或已转移的资源仍不可取得。delivery.available=true 表示当前有可用资源，delivery.complete=true 才表示整单交付完成。订单可显示 partially_delivered；procurement_blocked 仍表示结果未结清，不应当作整单成功，继续遵循 poll_after_seconds。

仅开启此模式时，订单详情及列表的 delivery 增加 delivery.remaining_count：尚未结清时为原始预期数量减去当前已到数量和已确认单项退款数量，下限为 0；整单完成、全额退款或取消后为 0。历史已完成订单的资源缺失不计为待到货。expected_count 保留原购买数量，部分退款另看 refund。订单列表仍不返回代理凭据。

分页 token 绑定交付读取模式；翻页时保持相同请求头，切换模式须从第一页重新获取，否则返回 422 invalid_page_token。删除已停用的 API Key 不会清除有效期内的已完成响应或尚未结清的幂等记录；换用新 Key 重试仍须保持原 Idempotency-Key 和原始 body，不能借更换凭证重新执行同一笔购买。

常见错误

invalid_signature

签名缺失、App ID 错误、canonical string 拼接不一致，或使用了错误的 API Secret。

stale_timestamp

时间戳没有时区、格式不是 ISO 8601，或客户端时间与服务器相差超过 5 分钟。

replayed_nonce

同一个 API Key 下重复使用了相同 nonce。每次请求都应该生成新的随机 nonce。

idempotency_key_required

要求幂等键的请求缺少 Idempotency-Key，或其长度、字符不符合要求。

idempotency_key_conflict

同一个 Idempotency-Key 已经用于不同请求体。

idempotency_processing / idempotency_replay_failed

相同操作仍在处理中，或首次响应暂时无法安全重放。保持相同 key 和原始 body，按响应建议稍后重试。

idempotency_unresolved

HTTP 409。先前请求可能已经产生扣款或其他结果，需要核对；不能把异常或超时当作未执行，也不要换 key 自动重试。

insufficient_scope

API Key 没有所需权限，或请求来源 IP 不在允许范围内。

api_key_revoked

API Key 已停用。请换用仍有效且具有所需权限的 Key。

validation_error

请求字段、数量、时长或组合不符合接口约束；按 data.errors 修正后再提交。

offer_not_found / order_not_found / proxy_not_found

公共标识不存在、已不可用，或不属于当前账号和环境。请重新读取对应列表。

insufficient_wallet_balance

钱包余额不足，创建订单或续费没有扣款成功。

invalid_page_token

分页 token 已过期、被修改，或用于错误的账号、环境或资源。请从第一页重新获取。

rate_limited

请求过快。读取 Retry-After 响应头后重试；不要用无间隔循环轮询。

unsupported_operation

该操作不属于 Customer API v1，例如更换 IP 或试用 IP。

proxy_endpoint_unavailable / operation_failed

连接端点暂不可用或操作未完成。请保存 trace_id，并按响应状态重试或联系支持。