经销商 API 文档 — 集成 SMS 验证

注意： 本参考面向 API 用户（开发者和集成商）。每个端点包含说明、身份验证要求、示例请求和响应。

身份验证 Bearer 令牌设置 虚拟号码 一次性 SMS 验证 租用号码 保留号码数天并接收所有短信

身份验证

所有端点需要在 Authorization 头中使用 Bearer 令牌。

如何获取 API 密钥

登录 Proxnum 账户并前往您的 个人资料页面
滚动到“API 密钥管理”部分
点击“创建 API 密钥”生成新密钥
复制显示的 API 令牌

在每次请求中包含 API 令牌：

Authorization: Bearer YOUR_API_TOKEN_HERE
Accept: application/json
Content-Type: application/json

快速链接：

通用响应格式

错误使用标准化结构，便于集成按 code 处理。所有错误响应遵循此模式：

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for the selected service and country"
}

端点

GET /api/v1/resell/price?service=&country=

获取指定服务和国家的基础价与售价。下单前可用于估算费用。

参数（查询）： service (string), country (int)

示例请求：

curl -s -X GET "https://proxnum.com/api/v1/resell/price?service=ig&country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

成功响应：

{
  "country": "6",
  "service": "ig",
  "base_price": 0.0334,
  "sell_price": 0.1114892
}

GET /api/v1/prices

获取所有可用服务和国家的完整定价。返回所有组合的基础价和经销商售价。

参数（查询，可选）：

service service（字符串）- 按服务代码筛选（如 ig、wa、tg）
country country（整数）- 按国家代码筛选

示例请求（全部价格）：

curl -s -X GET "https://proxnum.com/api/v1/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

示例请求（按国家筛选）：

curl -s -X GET "https://proxnum.com/api/v1/prices?country=6" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

成功响应（按国家筛选）：

{
  "success": true,
  "prices": {
    "6": {
      "ig": {
        "base_price": 0.0334,
        "sell_price": 0.1114892,
        "available": 245
      },
      "wa": {
        "base_price": 0.0389,
        "sell_price": 0.1298737,
        "available": 189
      },
      "tg": {
        "base_price": 0.0223,
        "sell_price": 0.0744551,
        "available": 521
      },
      "go": {
        "base_price": 0.0278,
        "sell_price": 0.0928206,
        "available": 312
      }
    }
  }
}

注意： 响应为嵌套对象：第一层键为国家代码，第二层键为服务代码。每项服务包含 base_price（成本）、sell_price（经销商售价）和 available（可用号码数量，未知时为 null）。

POST /api/v1/resell/virtual/buy

购买临时（虚拟）号码。将尝试分配号码并从账户扣费。

请求体（JSON）： {"service":"ig","country":6}

示例请求：

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"service":"ig","country":6}'

成功响应（标准化）：

{
  "success": true,
  "activation": {
    "id": 737,
    "phone": "62895406203932",
    "activation_id": "4390520873",
    "msg": "Waiting Sms",
    "date_created": "2025-11-08 21:50:34",
    "amount_paid": 0.111489,
    "status": 1
  }
}

常见错误代码：

{
  "success": false,
  "code": "no_numbers",
  "message": "No numbers available for this service in the selected country"
}

{
  "success": false,
  "code": "insufficient_balance",
  "message": "Not enough balance to place the order"
}

GET /api/v1/resell/virtual/{id}/status

检查激活状态。{id} 接受购买时返回的 activation id 字符串。

示例请求：

curl -s -X GET "https://proxnum.com/api/v1/resell/virtual/4390520873/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

成功（验证码可用时）：

{
  "success": true,
  "status": "completed",
  "code": "1234",
  "activation": { "id": 737, "phone": "628...", "activation_id": "4390520873" }
}

POST /api/v1/resell/virtual/resend

请求重发/重新激活。在请求体中使用 activation id 字符串。

请求体： {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/resend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

响应（已接受）：

{
  "success": true,
  "message": "Resend requested; new activation created",
  "activation": { "id": 738, "activation_id": "4390520874", "phone": "628..." }
}

POST /api/v1/resell/virtual/cancel

请求取消激活并退款。服务器评估是否可退款并返回标准化结果。

请求体： {"activation_id":"4390520873"}

curl -s -X POST "https://proxnum.com/api/v1/resell/virtual/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activation_id":"4390520873"}'

已接受：

{
  "success": true,
  "code": "cancel_accepted",
  "message": "Cancellation accepted, refund processed"
}

已拒绝：

{
  "success": false,
  "code": "cancel_rejected",
  "message": "Cancellation rejected — activation already completed or not refundable"
}

GET /api/v1/resell/activations

列出已认证用户的激活记录（分页）。支持 page 和 per_page 查询参数。

curl -s -X GET "https://proxnum.com/api/v1/resell/activations?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

租用号码

租用号码在您购买的时长内一直分配给您的账户，并接收发送给它的所有短信。使用这些接口向客户展示可选时长和价格、租用号码、读取收到的短信、在允许的时间内取消以及为有效租用续期。

所有租用接口也可以不带 /resell 前缀使用（例如 /api/v1/rental/catalog）。公开目录 /api/v1/rental/catalog 无需令牌。

租用接口的响应包含 "ok"（true 或 false）、失败时的 "error" 错误代码，以及以您账户语言显示的可读 "message"。HTTP 状态码反映结果（200 成功，202 已接受并处理中，4xx 请求问题，503 暂时不可用）。

租用状态

active — 号码归您所有，在 expires_at 之前接收短信。
cancelling — 已申请取消，正在等待确认。尚未退款。
cancelled — 取消已确认，amount_paid 已退回您的余额。
expired — 租用期已结束。

GET /api/v1/resell/rental/catalog?country=&hours=

返回当前提供的租用时长、国家，以及某个国家和时长下各服务的价格和库存。时长列表实时来自我们的号码供应，请始终从 durations[] 读取，不要写死数值。

查询参数：country（可选，数字国家 ID，见国家代码页面）和 hours（可选，必须是 durations[].hours 中的值）。无效或缺失的值将使用响应中返回的默认值。

示例请求：

curl -s "https://proxnum.com/api/v1/resell/rental/catalog?country=187&hours=168" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "country": "187",
  "hours": 168,
  "durations": [
    { "hours": 24, "label": "1 day" },
    { "hours": 72, "label": "3 days" },
    { "hours": 168, "label": "1 week" },
    { "hours": 720, "label": "30 days" }
  ],
  "countries": [ { "id": "187", "name": "USA" }, { "id": "16", "name": "United Kingdom" } ],
  "services": [
    { "code": "wa", "name": "WhatsApp", "icon": "...", "price": 4.2, "stock": 35 }
  ],
  "cancel_window_seconds": 120
}

POST /api/v1/resell/rental/buy

租用号码并从余额扣费。hours 必须是目录中 durations[].hours 的值之一。可选发送 max_price：如果当前价格更高，则不会扣费，并返回错误 price_changed 及新价格。

请求体（JSON）： {"service":"wa","country":187,"hours":168,"max_price":4.20}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/buy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"service":"wa","country":187,"hours":168,"max_price":4.20}'

{
  "ok": true,
  "error": null,
  "message": "Your rental number is ready.",
  "price": 4.2,
  "balance": 25.8,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "service": "wa",
    "service_name": "WhatsApp",
    "country": "187",
    "country_name": "USA",
    "status": "active",
    "amount_paid": 4.2,
    "hours": 168,
    "purchased_at": "2026-10-03T12:00:00+03:00",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "cancel_until": "2026-10-03T12:02:00+03:00",
    "can_cancel": true,
    "cancel_pending": false,
    "can_extend": true
  }
}

常见错误：invalid_period (422)、no_numbers (409)、price_changed (409)、insufficient_funds (402)、option_unavailable (422)、unavailable 或 provider_unreachable（503，未扣费）。

GET /api/v1/resell/rental/{id}/status

返回租用信息及收到的短信（最新的在前）。每条消息包含文本，检测到验证码时还包含 code。等待短信期间请每 5 到 10 秒轮询一次。id 可以是我们的租用 ID，也可以是购买时返回的激活 ID。

curl -s "https://proxnum.com/api/v1/resell/rental/512/status" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "rental": {
    "id": 512,
    "phone": "14155550123",
    "status": "active",
    "expires_at": "2026-10-10T12:00:00+03:00",
    "can_cancel": false,
    "can_extend": true,
    "messages": [
      { "id": 9001, "sender": "WhatsApp", "text": "Your WhatsApp code: 123-456", "code": "123456", "date": "2026-10-03T12:05:10+03:00" }
    ]
  }
}

POST /api/v1/resell/rental/cancel

仅可在购买后 2 分钟内、未收到任何短信且未续期的情况下取消租用。取消需要与号码供应方确认，可能需要几分钟。

请求体： {"id":512}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"id":512}'

HTTP/1.1 202 Accepted
{
  "ok": true,
  "pending": true,
  "refunded": 0,
  "message": "Cancellation requested. Your refund will be added once the cancellation is confirmed, usually within a few minutes.",
  "rental": { "id": 512, "status": "cancelling", "cancel_pending": true }
}

HTTP/1.1 200 OK
{
  "ok": true,
  "pending": false,
  "refunded": 4.2,
  "balance": 30,
  "rental": { "id": 512, "status": "cancelled" }
}

HTTP/1.1 409 Conflict
{
  "ok": false,
  "error": "sms_received",
  "message": "This number has already received an SMS, so it cannot be cancelled."
}

HTTP 202 且 "pending": true 表示请求已被接受但尚未退款。请轮询状态接口：当 amount_paid 已退款时 status 变为 cancelled；如果取消被拒绝（例如期间收到了短信），status 会恢复为 active。确认前绝不会退款，也绝不会重复退款。

常见错误：window_closed、sms_received、extended、cancel_pending（已有请求正在处理）、not_active（均为 409）。

GET /api/v1/resell/rental/{id}/extend-options

列出某个有效租用可用的续期时长和价格。价格针对该号码实时获取。

curl -s "https://proxnum.com/api/v1/resell/rental/512/extend-options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{
  "ok": true,
  "options": [
    { "hours": 24, "label": "1 day", "price": 1.1 },
    { "hours": 168, "label": "1 week", "price": 5.0 }
  ]
}

POST /api/v1/resell/rental/{id}/extend

按续期选项返回的某个时长为有效租用续期并从余额扣费。发送 max_price 可确保扣费永远不会超过您向客户展示的价格。已续期的租用无法再取消。

请求体（JSON）： {"hours":168,"max_price":5.00}

curl -s -X POST "https://proxnum.com/api/v1/resell/rental/512/extend" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"hours":168,"max_price":5.00}'

{
  "ok": true,
  "message": "Rental extended by 1 week.",
  "price": 5,
  "balance": 25,
  "rental": { "id": 512, "status": "active", "expires_at": "2026-10-17T12:00:00+03:00", "can_cancel": false }
}

常见错误：invalid_period (422)、price_changed (409)、insufficient_funds (402)、not_active (409)、unavailable (503)。

GET /api/v1/resell/rentals

分页的租用列表，最新的在前。查询参数：page 和 per_page（1 到 100）。

curl -s "https://proxnum.com/api/v1/resell/rentals?page=1&per_page=25" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

{ "ok": true, "total": 3, "page": 1, "per_page": 25, "data": [ { "id": 512, "phone": "14155550123", "status": "active", "...": "..." } ] }

实现说明

尽可能使扣费操作按订单幂等；请检查返回的 order 或 transaction 字段获取标准标识符。
下单前使用 price 端点试算费用。
常见标准化错误代码：no_numbers、insufficient_balance、service_unavailable、cancel_rejected。

最佳实践：

集成中始终处理成功和错误响应
为网络超时实现适当的错误处理
缓存国家和服务列表以减少 API 调用
可用时使用 webhook 获取实时状态更新

Open Proxnum in your browser

ProxNum

开发者 API 参考

身份验证

如何获取 API 密钥

通用响应格式

端点

GET /api/v1/resell/price?service=&country=

GET /api/v1/prices

POST /api/v1/resell/virtual/buy

GET /api/v1/resell/virtual/{id}/status

POST /api/v1/resell/virtual/resend

POST /api/v1/resell/virtual/cancel

GET /api/v1/resell/activations

租用号码

租用状态

GET /api/v1/resell/rental/catalog?country=&hours=

POST /api/v1/resell/rental/buy

GET /api/v1/resell/rental/{id}/status

POST /api/v1/resell/rental/cancel

GET /api/v1/resell/rental/{id}/extend-options

POST /api/v1/resell/rental/{id}/extend

GET /api/v1/resell/rentals

实现说明