接码平台 · API 对接文档

获取 CDK

找平台管理员购买 CDK 卡密，每张卡密含一定次数，如 50 次 / 100 次。

取号

用 CDK 作为 API Key 调用取号接口，拿到一个手机号。

查码

每 10~15 秒查询一次，状态变为 completed 即返回验证码，此时扣除 1 次。

快速开始

所有接口使用 HTTP 基本调用，CDK 即你的 API Key，放在请求头中：

# 取号
curl -X POST __BASE__/Open/V1/Orders \
  -H "Authorization: Bearer AIKM-XXXX-XXXX-XXXX" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: checkout-20260810-001" \
  -d '{"service":"chat_us"}'

响应示例（HTTP 201）：

{
  "ok": true,
  "data": {
    "orderId": "ord_QMxi7jODTVCGC3lA",
    "service": "chat_us",
    "country": "美国 VIP",
    "callingCode": "+1",
    "status": "waiting",
    "phone": "7077244879",
    "code": "",
    "currency": "CNY",
    "amount": 0.8,
    "amountMinor": 80,
    "billingStatus": "charged",
    "canCancel": false,
    "cancelAvailableAt": "2026-07-11T08:02:00.000Z",
    "createdAt": "2026-07-11T08:00:00.000Z",
    "allocatedAt": "2026-07-11T08:00:00.000Z",
    "expiresAt": "2026-07-11T08:10:00.000Z"
  }
}

💡 拿到 orderId 后轮询查码（建议每 10~15 秒一次），直到 status 变为 completed，此时 code 字段就是验证码。

API 参考

通用说明

基础地址：__BASE__
认证：所有请求携带 Authorization: Bearer <CDK>
成功响应统一为 {"ok":true,"data":{...}}；失败为 {"ok":false,"error":{"code":"...","message":"..."},"requestId":"..."}
限流：单 CDK 每分钟 60 次（可配置），超限返回 HTTP 429，响应头含 X-RateLimit-*

1. 取号 POST /Open/V1/Orders

参数	位置	必填	说明
`service`	Body	否	默认 `chat_us`。可选：`chat_us`（美国 +1）、`chat_gb`（英国 +44）、`chat_za`（南非 +27）
`X-Idempotency-Key`	Header	是	8~128 位字母数字及 `._:-`。重复提交同一键返回原订单，不会重复取号扣次

成功返回 HTTP 201。手机号在 phone 字段，配合 callingCode 使用。

2. 查码 GET /Open/V1/Orders/{orderId}

curl "__BASE__/Open/V1/Orders/ord_QMxi7jODTVCGC3lA" \
  -H "Authorization: Bearer AIKM-XXXX-XXXX-XXXX"

status 为 completed 时，code 为验证码。只有该 CDK 自己的订单可查，否则返回 404。

3. 取消 POST /Open/V1/Orders/{orderId}/Cancel

号码分配满 2 分钟后可取消，已收到验证码的订单不能取消。取消 / 失败 / 超时的订单不扣次，号码立即释放。

4. 查询余额（剩余次数）GET /Open/V1/Account

curl "__BASE__/Open/V1/Account" \
  -H "Authorization: Bearer AIKM-XXXX-XXXX-XXXX"

响应中的 balance 为剩余次数（计次模式，单位是次而非金额），usage 为已用/进行中统计。

5. 扣次流水 GET /Open/V1/Transactions

查询该 CDK 的发放 / 扣次 / 调整记录，支持游标翻页：

curl "__BASE__/Open/V1/Transactions?limit=50&before=...&beforeId=..." \
  -H "Authorization: Bearer AIKM-XXXX-XXXX-XXXX"

Node.js 对接示例

// 取号 → 轮询查码 → 拿到验证码
const BASE = "__BASE__";
const CDK = "AIKM-XXXX-XXXX-XXXX";

async function getCode(idempotencyKey) {
  const headers = { Authorization: `Bearer ${CDK}`, "Content-Type": "application/json" };

  // 1. 取号
  const created = await fetch(`${BASE}/Open/V1/Orders`, {
    method: "POST",
    headers: { ...headers, "X-Idempotency-Key": idempotencyKey },
    body: JSON.stringify({ service: "chat_us" }),
  }).then(r => r.json());
  if (!created.ok) throw new Error(created.error.code + ": " + created.error.message);
  const orderId = created.data.orderId;
  console.log("已取号：", created.data.phone);

  // 2. 每 10~15 秒轮询查码
  for (let i = 0; i < 40; i++) {
    await new Promise(r => setTimeout(r, 10000));
    const order = await fetch(`${BASE}/Open/V1/Orders/${orderId}`, { headers }).then(r => r.json());
    if (order.data.status === "completed") {
      console.log("验证码：", order.data.code);
      return order.data.code;
    }
    if (["cancelled", "failed", "expired"].includes(order.data.status)) {
      throw new Error("订单已失效：" + order.data.status);
    }
  }
  throw new Error("等待超时");
}

getCode("checkout-20260810-001").catch(console.error);

订单状态与错误码

订单状态

状态	含义	计次
`allocating`	正在分配号码	—
`waiting`	已分配号码，等待验证码	—
`completed`	已收到验证码（code 字段）	扣 1 次
`cancelled` / `failed` / `expired`	取消 / 失败 / 等待超时	不扣次

常见错误码

HTTP	错误码	说明
400	`INVALID_IDEMPOTENCY_KEY`	幂等键格式错误
401	`INVALID_API_KEY`	CDK 无效或已删除
402	`INSUFFICIENT_BALANCE`	卡密可用次数不足
403	`API_KEY_DISABLED`	CDK 已被禁用
403	`UNSUPPORTED_SERVICE`	不支持的 service
404	`ORDER_NOT_FOUND`	订单不存在或不属于该 CDK
409	`IDEMPOTENCY_CONFLICT`	同一幂等键对应不同请求
409	`CANCEL_WAIT_REQUIRED`	取号未满 2 分钟不能取消
409	`ORDER_COMPLETED`	已收到验证码，不能取消
429	`RATE_LIMITED`	每分钟请求达到上限
429	`CONCURRENCY_LIMITED`	进行中订单达到并发上限
503	`NUMBER_UNAVAILABLE`	暂时没有可用号码，稍后重试

计次规则

✅ 收到验证码才扣 1 次。取号、等待、取消、失败、超时均不扣次。

扣次时机：订单状态变为 completed（验证码到达）时扣除 1 次。
自动退款：等码超过 2 分钟未收到验证码，订单自动取消——号码释放、次数不扣（相当于原路退回）。
并发限制：同一 CDK 可同时进行的订单数受平台配置限制（默认 3），超过返回 429 CONCURRENCY_LIMITED，建议收到验证码或取消后再取新号。
幂等保障：取号必须携带 X-Idempotency-Key，重复提交（如网络重试）返回原订单，不会重复扣次。
查询余额：GET /Open/V1/Account 可随时查看剩余次数与使用统计。

常见问题

验证码多久能收到？

取决于服务方下发速度，通常 30 秒~2 分钟。建议每 10~15 秒查一次；超过 2 分钟未收到会自动取消并退款（不扣次）。

取号提示 NUMBER_UNAVAILABLE 怎么办？

该地区暂时没有可用号码（如美国号码缺货），可换 service（chat_gb / chat_za）或稍后重试，不会扣次。

同一幂等键重复提交会怎样？

返回第一次的订单（不会重复取号、不重复扣次），可用于网络重试的安全保障。需要取新号时换一个新的幂等键。

CDK 次数用完了怎么办？

调用取号返回 402 INSUFFICIENT_BALANCE。联系平台管理员购买新的 CDK。

取到的手机号能重复使用吗？

每个订单对应一个号码，收到验证码后订单完成；如需再次取号请创建新订单（新号码）。