客户 API 开发文档

1. 1登录客户中心，进入 我的 API，创建 oip_app_ 开头的 App ID，并立即保存 API Secret。
2. 2把 OFFLINEIP_API_BASE_URL、OFFLINEIP_API_APP_ID 和 OFFLINEIP_API_SECRET 放进服务端环境变量，不要写进前端页面或公开仓库。
3. 3先请求 GET /api/v1/account 验证签名，再请求 GET /api/v1/offers 获取可用产品。
4. 4创建订单或续费时，为一次业务操作生成一个 Idempotency-Key。超时或网络重试必须复用原 key 和完全相同的原始 body。
5. 5下单成功表示订单已受理。保存返回的 order_no，按响应中的 poll_after_seconds 查询订单详情，直到 poll_after_seconds 为 null；待核对订单请勿重复提交。

OFFLINEIP_API_BASE_URL=https://www.offlineip.com
OFFLINEIP_API_APP_ID=oip_app_EXAMPLE_APP_ID
OFFLINEIP_API_SECRET=sk_replace-with-your-secret

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

{
  "success": true,
  "code": "ok",
  "message": "OK",
  "data": {},
  "timestamp": "2026-08-17T12:00:00.000Z",
  "trace_id": "trc_EXAMPLE_TRACE_ID"
}

签名前把请求拆成 7 行，用换行符 \n 连接。METHOD 大写；host 取请求域名，小写且不含协议与端口；path 含开头斜杠；canonical_query 对 key 和 value 分别 URL 解码后再 rawurlencode，按 key、value 升序排序， 重复 key 不合并，无 query 时留空；body 使用原始请求体的 SHA-256，GET 使用空字符串的 SHA-256。

METHOD
host
path
canonical_query
timestamp
nonce
sha256(body)

import crypto from 'node:crypto';

const baseUrl = process.env.OFFLINEIP_API_BASE_URL;
const appId = process.env.OFFLINEIP_API_APP_ID;
const secret = process.env.OFFLINEIP_API_SECRET;

const rfc3986 = (v) =>
  encodeURIComponent(v).replace(/[!'()*]/g, (c) =>
    `%${c.charCodeAt(0).toString(16).toUpperCase()}`);

const canonicalQuery = (raw) =>
  !raw ? '' : raw.split('&')
    .map((pair) => {
      const i = pair.indexOf('=');
      const k = i === -1 ? pair : pair.slice(0, i);
      const v = i === -1 ? '' : pair.slice(i + 1);
      return [rfc3986(decodeURIComponent(k)), rfc3986(decodeURIComponent(v))];
    })
    .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1
      : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0))
    .map(([k, v]) => `${k}=${v}`)
    .join('&');

export async function call(method, path, body) {
  const url = new URL(path, baseUrl);
  const payload = body === undefined ? '' : JSON.stringify(body);
  const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
  const nonce = `nce_${crypto.randomBytes(16).toString('hex')}`;

  const canonical = [
    method.toUpperCase(),
    url.hostname.toLowerCase(),
    url.pathname,
    canonicalQuery(url.search.replace(/^\?/, '')),
    timestamp,
    nonce,
    crypto.createHash('sha256').update(payload).digest('hex'),
  ].join('\n');

  const headers = {
    'X-API-AppId': appId,
    'X-API-Timestamp': timestamp,
    'X-API-Nonce': nonce,
    'X-API-Signature': crypto.createHmac('sha256', secret)
      .update(canonical).digest('hex'),
    Accept: 'application/json',
    'User-Agent': 'OfflineIP-Integration/1.0',
  };
  if (payload) headers['Content-Type'] = 'application/json';

  const res = await fetch(url, { method, headers, body: payload || undefined });
  return res.json();
}

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

{
  "duration_days": 30,
  "items": [
    { "offer_code": "off_...", "quantity": 2 },
    { "offer_code": "off_...", "quantity": 1, "cidr": "104.206.10.0/24" }
  ]
}

items 最多 50 行，整笔订单总数量不超过 2000。duration_days 支持 30 至 1080 天，必须是 30 的整数倍；购买还须满足产品返回的支持时长。 旧版单地区格式 offer_code + quantity + duration_days 继续兼容，并支持可选 cidr；顶层 offer_code、quantity、cidr 均不能与 items 同时出现。

GET /api/v1/proxies?page_size=100

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

请求下一页时把返回的 next_page_token 原样放入 page_token，并保持相同的 page_size。token 绑定当前账号与资源类型，篡改、过期或跨账号使用都会被拒绝。

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

paid 或 procuring 表示处理中。当 poll_after_seconds 是整数时，等待返回的秒数后再查询；为 null 或订单进入终态时停止轮询。 只有 delivery.available=true 时，详情中的 proxies 才可交付使用。partial 表示部分交付，已返回且可用的 IP 可先使用；remaining_count 表示尚未交付数量，未知时为 null。 部分交付也可能已停止轮询，请始终遵循 poll_after_seconds。manual_review 表示结果待核对，停止自动轮询并联系客服，切勿重新下单。 已确认的采购失败会按实际未交付数量退回余额；部分退款时 payment_status 为 partially_refunded，已交付的 IP 保留可用；退款金额以 refund 为准。 全额退款时状态为 refunded。