PNPAPI 接入文档

PHONE NUMBER POOL / V1

API 接入文档

面向通过 API 批量或自动化使用接码服务的客户。普通用户购买和兑换 CDK，请使用零售接码页面。

零售模式CDK 兑换sms.weiye.xyz/retail
API 模式客户余额计费https://pool.weiye.xyz

开通流程

  1. 创建客户平台管理员在“客户与计费”中创建独立客户账户。
  2. 配置价格并充值设置服务、国家、批发单价和客户可用余额。
  3. 签发 API Key管理员交付以 pnp_live_ 开头的客户 Key。
  4. 完成联调客户按本文档检查账户、创建任务并轮询验证码。
客户中心已开通客户可登录 pool.weiye.xyz/portal，查看余额、接码记录、资金流水、API Key，并使用充值兑换码自助充值。
API Key 是资金凭据只能保存在调用方服务端，不要写入前端网页、公开仓库或业务日志。

基础约定

Base URLhttps://pool.weiye.xyz
认证方式Authorization: Bearer <API_KEY>
金额单位整数分：125 = ¥1.25
时间格式Unix 秒级时间戳

所有请求使用 HTTPS 和 JSON。示例使用以下环境变量：

Shell
export PNP_BASE_URL="https://pool.weiye.xyz"
export PNP_API_KEY="pnp_live_替换为管理员签发的Key"

快速开始

1. 查询账户和余额

GET /v1/account
curl -sS "$PNP_BASE_URL/v1/account" \
  -H "Authorization: Bearer $PNP_API_KEY"

2. 查询有效价格

GET /v1/prices
curl -sS "$PNP_BASE_URL/v1/prices" \
  -H "Authorization: Bearer $PNP_API_KEY"

创建任务前，确认目标 service + country 已返回有效价格。不要假设所有服务和国家都已开放。

POST/v1/activations
创建接码任务
curl
curl -sS -X POST "$PNP_BASE_URL/v1/activations" \
  -H "Authorization: Bearer $PNP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260811-10001" \
  -d '{
    "service": "codex",
    "country": "USA",
    "lease_seconds": 600
  }'
字段必填说明
service是服务标识，以价格接口返回值为准
country是国家代码，例如 USA
lease_seconds否60-3600 秒，默认 600
Idempotency-Key是调用方唯一业务请求号，最长 200 字符
必须持久化 activation_id相同客户使用同一个 Idempotency-Key 重试时返回同一任务，不会重复预扣余额。

响应示例

201 Created / 200 Idempotent Replay
{
  "ok": true,
  "activation": {
    "activation_id": "act_xxx",
    "service": "codex",
    "country": "USA",
    "status": "waiting",
    "phone_number": "+16725550123",
    "price_amount": 125,
    "currency": "CNY",
    "code": "",
    "lease_expires_at": 1786443000.0,
    "replace_count": 0,
    "failure_reason": ""
  }
}
GET/v1/activations/{activation_id}
查询状态和验证码
curl
curl -sS "$PNP_BASE_URL/v1/activations/act_xxx" \
  -H "Authorization: Bearer $PNP_API_KEY"

建议每 3-5 秒轮询一次。只有 status=success 时读取 code；进入终态后立即停止轮询。

POST/v1/activations/{activation_id}/replace
换号
curl
curl -sS -X POST "$PNP_BASE_URL/v1/activations/act_xxx/replace" \
  -H "Authorization: Bearer $PNP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: replace-order-10001-1" \
  -d '{}'

每次实际换号使用新的幂等键；网络重试继续使用本次换号的原幂等键。

POST/v1/activations/{activation_id}/cancel
取消
curl
curl -sS -X POST "$PNP_BASE_URL/v1/activations/act_xxx/cancel" \
  -H "Authorization: Bearer $PNP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

用户放弃流程时应主动取消。未成功任务会释放预扣金额，成功任务不会退款。

状态定义

状态终态处理方式
provisioning否正在分配号码，继续轮询
waiting否已分配号码，等待新验证码
success是从 code 读取验证码
cancelled是已取消，预扣金额已释放
timeout是租约超时，预扣金额已释放
no_numbers是当前无可用号码，可稍后新建任务
failed是查看 failure_reason
成功标准只有检测到租号后产生的新验证码才结算成功。历史短信或没有新验证码不会被视为成功。

计费与查询

  • 创建 activation 时按当前有效价格预扣余额。
  • 任务进入 success 后，预扣转为正式扣款。
  • cancelled、timeout、no_numbers、failed 会释放预扣。
  • 余额不足返回 HTTP 402，不创建任务。
GET /v1/account账户与余额GET /v1/prices当前有效价格GET /v1/ledger?limit=200资金账本GET /v1/activations?status=all&limit=200任务列表

错误处理

Error Response
{
  "ok": false,
  "error_code": "INVALID_API_KEY",
  "error": "API Key 无效"
}
HTTP常见错误处理建议
400INVALID_REQUEST检查 JSON、字段和 Idempotency-Key
401INVALID_API_KEY检查 Bearer Key 或联系管理员
402INSUFFICIENT_BALANCE联系管理员充值
403ACCOUNT_UNAVAILABLE客户账户已暂停
404ACTIVATION_NOT_FOUND检查任务 ID 和所属客户
409PRICE_NOT_FOUND / 状态冲突检查价格或刷新任务状态

网络超时和 5xx 可以重试；创建和换号重试必须复用原来的 Idempotency-Key。

上线检查清单

  • API Key 仅保存在调用方服务端密钥配置中。
  • 创建和换号请求使用稳定且唯一的幂等键。
  • 持久化 activation_id，不要只保存手机号。
  • 轮询间隔不少于 3 秒，并在终态后停止。
  • 仅在 success 状态读取和使用验证码。
  • 用户放弃时调用 cancel。
  • 记录状态码、error_code、activation_id，但不记录完整 API Key。
  • 定期使用 account 和 ledger 接口对账。
管理员交付内容Base URL: https://pool.weiye.xyzAPI Key: pnp_live_由管理员安全发送文档: https://pool.weiye.xyz/integration
已复制