下游 API 文档

使用 CDK 验证额度、获取临时号码并查询短信验证码。本文档对应当前运行的公开接口，供已获发 CDK 的下游系统接入。

基础地址：https://jiema.newzoe.cloud · 更新：2026-10-08

接入概览

项目	说明
鉴权	每次请求传入分配给你的 `cdk`。无单独的下游 API Key；请将 CDK 当作凭证保管。
传参	POST 使用 JSON 请求体并设置 `Content-Type: application/json`；GET 使用 URL 查询参数。
响应	返回 JSON。成功时 `ok: true`；失败时通常是非 2xx 状态及 `{"ok":false,"error":"..."}`。
额度	首次收到某次激活的验证码时，CDK 已用次数增加 1。取号可能产生供应商费用，即使还没有收到验证码。
安全	只通过 HTTPS 调用。不要把 CDK、短信内容或号码写入公开日志、前端仓库或错误上报。

调用流程

调用 POST /api/init 验证 CDK，读取剩余额度及可能存在的进行中激活。
没有进行中的激活时调用 POST /api/buy-auto 取号，保存响应中的 activation.activationId 和 phoneNumber。
把号码提交给目标服务，随后以约 5 秒间隔调用 GET /api/status，直到 status.state 为 ok，取得 status.code。
不再需要号码时，可调用 POST /api/set-status 传 status: 6 标记完成，或传 status: 8 标记取消。

重复调用 /api/buy-auto 可能恢复尚未结束的号码；不要把它当成查询状态接口。轮询请使用 /api/status。

POST /api/init

验证 CDK 并恢复该 CDK 最近的进行中激活。cdk 可放在 JSON 请求体，也可放在查询参数。

curl -X POST 'https://jiema.newzoe.cloud/api/init' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"SMS-XXXX-XXXX-XXXX"}'

有效且有余额时：

{
  "ok": true,
  "mode": "simple",
  "cdk": {
    "remaining": 1,
    "maxUses": 1,
    "service": "openai",
    "country": "US",
    "maxPriceUsd": 0.15,
    "routeCount": 1,
    "reuseType": "single",
    "reuseMax": 3,
    "used": 0
  }
}

若有进行中的激活，响应还包含 activation 和 status；应优先继续使用该 activationId。额度耗尽时返回 HTTP 200、exhausted: true，并可能带有 lastActivation 供查看最后一次验证码。未提供 CDK 时返回 {"ok":true,"needsCdk":true}；无效或过期的 CDK 返回 HTTP 400。

POST /api/buy-auto

取得号码。服务和国家由 CDK 配置决定，调用方不能通过此接口临时改价或改国家。

curl -X POST 'https://jiema.newzoe.cloud/api/buy-auto' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"SMS-XXXX-XXXX-XXXX"}'

{
  "ok": true,
  "activation": {
    "activationId": "12345",
    "phoneNumber": "+12025550123",
    "provider": "smspool",
    "createdAt": "2026-10-08T04:00:00.000Z"
  },
  "status": { "label": "号码已取得，自动等待短信", "state": "waiting" },
  "cdk": { "remaining": 1, "maxUses": 1 }
}

activationId 是数据库数字 ID 的字符串表示，后续查询要原样传回。恢复已有激活时可能出现 reused: true，也可能直接带回当前 status.code。供应商不可用或取号失败时可能返回 HTTP 500；不要在网络超时后立即无限重试，应先调用 /api/init 检查是否已创建激活。

forceNew: true 可要求跳过当前激活与复用池，分配新号码。它不会自动取消旧激活，可能产生额外费用；只有确认需要换号时使用。

GET /api/status

查询某次激活的短信状态。必填查询参数：cdk 和 id（取号响应里的 activationId）。

curl -G 'https://jiema.newzoe.cloud/api/status' \
  --data-urlencode 'cdk=SMS-XXXX-XXXX-XXXX' \
  --data-urlencode 'id=12345'

等待短信：

{
  "ok": true,
  "status": { "label": "waiting", "state": "waiting" },
  "cdk": { "remaining": 1, "maxUses": 1 }
}

收到验证码：

{
  "ok": true,
  "status": {
    "label": "got code",
    "state": "ok",
    "code": "123456",
    "done": true,
    "moreLeft": 0
  },
  "cdk": { "remaining": 0, "maxUses": 1 }
}

`state`	含义与处理
`waiting`	尚未取得新验证码；稍后继续轮询。
`ok`	读取 `code`；`done` 表示该 CDK 是否达到本轮上限，`moreLeft` 表示 multi 类型剩余次数。
`cancelled`	激活已取消或超时；停止轮询。

超时由服务器配置控制，当前默认约 10 分钟。id 不存在或不属于该 CDK 时返回 HTTP 404。CDK 额度耗尽后，本接口的前置校验可能返回 HTTP 400 used up；可用 /api/init 的 lastActivation 查看最后一次验证码。

POST /api/set-status

对指定激活执行结束操作。cdk、id 和数字型 status 都是必填。

curl -X POST 'https://jiema.newzoe.cloud/api/set-status' \
  -H 'Content-Type: application/json' \
  -d '{"cdk":"SMS-XXXX-XXXX-XXXX","id":"12345","status":8}'

`status`	结果
`6`	标记完成；响应示例 `{"ok":true,"label":"finished"}`。
`8`	标记取消；响应示例 `{"ok":true,"label":"cancelled"}`。供应商端是否释放号码取决于供应商。

当前实现对 status: 3 只返回 resent 标签，不保证实际触发短信重发，下游请勿把它当作可靠的重发接口。CDK 额度耗尽时本接口也可能返回 HTTP 400 used up。

错误处理

HTTP	常见 `error`	建议处理
400	`no cdk` / `bad cdk` / `expired`	检查 CDK 是否提供、输入是否正确、是否过期。
400	`used up`	停止取号，调用 `/api/init` 查看耗尽状态。
400	`no id` / `params`	补齐请求参数。
404	`not found`	检查激活 ID 是否属于当前 CDK。
500	供应商或服务器错误信息	记录 HTTP 状态与错误描述；取号前先确认是否已有激活，再决定是否重试。

/api/init 的错误文字略有不同：无效 CDK 为 CDK invalid，过期为 CDK expired。请优先按 HTTP 状态、ok 和业务字段判断，不要依赖 label 的显示文字。

集成注意事项

每个 CDK 只可读取自己的激活记录；保存 cdk 与 activationId 的对应关系。
建议以 5 秒左右间隔轮询并设置客户端超时；不要高频并发轮询。
single 和 multi 由 CDK 决定。multi CDK 可能复用同一号码，使用 moreLeft 判断是否还有次数。
请求结果可能因号码池、供应商及激活状态而增加字段；解析时应容忍未识别字段和可选字段缺失。
如只需人工操作，可直接访问接码助手网页。