美国接码 API：取号码 / 取验证码 / 换号 / 查库存

美国接码 API 是把号码市场做成 HTTP 接口：用 API Key 调用取号、取码、换号、查库存，返回 JSON。号码是美国 T-Mobile 实卡（非 VoIP），按 2-30 天档位出租；价格、库存与网页下单完全一致，适合批量注册、批量验证，以及给自己的下游接码站供货。

美国接码 API 是什么（30 秒了解）

• 美国接码 API 面向程序调用：请求头带 X-Api-Key，服务端校验账号与余额后返回号码、接码链接、到期时间和本次扣费。
• 和网页下单的区别只有一个：网页是手动点，API 是程序调用；号码池、价格、库存与退换规则完全一致。
• 计费口径：取到号码才扣费；同一档位再取一个就再扣一次；取验证码本身不额外收费。
• 支持的能力：取号、取码（含 wait 长轮询）、换号、按单号取号、订单分页、号段与库存查询、API Key 鉴权。

接口长什么样（示例）

• 取号码：POST /api/open/buy，body 传 {"item_key":"openai_21_30","quantity":1}，返回号码 + 接码链接 + 本次扣费。
• 下单防重：POST /api/open/buy 的 body 里带你自己生成的 order_no（幂等键），同一个 order_no 重试只会返回同一笔订单和同一批号码，不会重复扣费。
• 按单号取号：GET /api/open/order?order_no=你的单号（或 ?order_id=本站订单号），返回号码 + 接码链接 + 到期时间。
• 号码列表：GET /api/open/numbers 支持 order_id / min_order_id / page / page_size 筛选与翻页。
• 取验证码：GET /api/open/code?number=号码&wait=15，返回该号码收到的验证码；wait 是长轮询秒数（0-30），没码时最多等指定秒数再返回。
• 换号：POST /api/open/change，号码没收到验证码时可以换一个新号（同一档位单价再扣一次）。
• 查库存：GET /api/open/stock?item_key=...，返回各档位实时可售数量；加 with_prefixes=1 可以带号段明细，方便你决定什么时候进货。
• 订单查询：GET /api/open/orders 支持 order_id 定点、since_order_id 增量和 page/page_size 翻页，返回每单的号码与到期时间。
• 鉴权：请求头带 X-Api-Key（在「个人资料 / API 文档」里生成），返回 JSON，错误码见接口文档。

5 分钟接入：最小可用流程

• 第一步：在「个人资料 / API 文档」生成 API Key，先充少量余额。
• 第二步：调用 /api/open/stock 查目标项目的档位、价格和可售数量。
• 第三步：调用 /api/open/buy 下单，body 里带上你自己生成的 order_no；拿到号码、接码链接和到期时间。
• 第四步：把号码填到目标平台，调用 /api/open/code（建议 wait=10~20）等验证码。
• 第五步：超时或断网时，用同一个 order_no 重试下单，或用 /api/open/order 查回已生成的号码。

适合谁

• 需要批量注册与验证账号的工作室。
• 自己做接码站、需要从上游取号码与验证码的下游网站。
• 需要把收码能力接进自有系统的团队。

三种批量方式

• 批量下单：号码市场支持多号段多选、一次下单多个号码，可以按项目批量采购。
• 批量下载：购买记录与我的号码都支持整批导出 txt，包含号码与接码链接。
• API 对接：用账号的 API Key 调用接口获取号码与短信，适合自动化系统。

接入建议

• 先小批量测试目标平台的收码成功率，再扩大规模。
• 做好号码与账号的对应关系记录，避免号码到期导致账号失联。
• 对长期使用的号码提前续费，比到期后重新买号更划算。
• 下单一定带 order_no：超时重试才安全，不会重复扣费。
• 取码优先用 wait 长轮询，不要每秒硬轮询。

curl 示例（可直接复制）

# 1) 查库存（with_prefixes=1 可带号段明细）
curl -s "https://sms688.com/api/open/stock?item_key=openai_21_30&with_prefixes=1" \
  -H "X-Api-Key: sk_你的key"

# 2) 下单（order_no 是你的幂等键，重试不会重复扣费）
curl -s -X POST "https://sms688.com/api/open/buy" \
  -H "X-Api-Key: sk_你的key" -H "Content-Type: application/json" \
  -d '{"item_key":"openai_21_30","quantity":1,"order_no":"job-20261018-001"}'

# 3) 取验证码（wait 长轮询，没码最多等 15 秒）
curl -s "https://sms688.com/api/open/code?number=15591234567&wait=15" \
  -H "X-Api-Key: sk_你的key"

# 4) 超时后按单号查回号码
curl -s "https://sms688.com/api/open/order?order_no=job-20261018-001" \
  -H "X-Api-Key: sk_你的key"

开放接口补充说明（2026-10-14 更新）

1. 库存口径：available_count = 上游可分配 + 本站现号

GET /api/v1/projects/market?country_id=1 返回的 available_count 已经包含本站号池里现成的号（不只是上游可分配）。也就是说：available_count > 0 就一定能下单成功，不会再出现“接口说没货、其实本站有号”的情况。 每个档位（price_tiers）也带自己的 available_count。

2. 幂等下单（强烈建议传 order_no）

POST /api/open/buy 支持传 order_no（你自己生成的单号，作为幂等键）：

• 同一个 order_no 重复请求 → 返回同一笔订单，不会重复扣费、不会重复发号；
• 请求超时了、没拿到响应 → 可以直接重试，安全；
• 不传 order_no 时，行为跟以前一样（每次都是新订单），超时重试有重复下单风险。

3. 按单号取号（超时后不用等）

GET /api/open/order?order_no=<你下单时传的单号>，或 GET /api/open/order?order_id=<我们返回的订单号>
返回该单的号码 + 接码链接 + 到期时间。下游不用再去后台手动下载 txt。

4. 订单查询（带项目名，支持翻页）

GET /api/open/orders（请求头 X-Api-Key: sk_xxx）

• 每笔订单带 item_key（项目）与 numbers（号码、接码链接、到期时间）；
• 定点拉取：?order_id=123 单笔；增量：?since_order_id=123；
• 翻页：?page=1&page_size=200 → 返回 total / has_more / next_page， 翻完全部页即可拿全号码（不再只返回最早一页）。

5. 失败语义

• 下单失败 → 该 order_no 会带失败原因，可原样重试；
• 查不到订单通常是单号传错或该单没下成功，不要用“查不到”判断失败。

接码链路建议用 GET /api/sms/live/wait?token=...&timeout=15 长轮询（等 15 秒再返回），比每秒轮询省资源、也更实时。

常见问题

API 怎么申请？

登录后在「个人资料」里可以生成 API Key，接口说明见站内 API 文档页。

批量采购有优惠吗？

批量与长期合作可以联系客服谈方案，按量沟通价格。

可以给我自己的站做上游吗？

可以。我们支持下游站点对接，用你的账号 API 取号与取码，对外域名可以隐藏上游信息。

美国接码 API 怎么收费？

按号码计费，和网页下单同价：取到号码才扣费，同一档位再取一个就再扣一次；取验证码本身不额外收费。

有没有免费测试？

可以先充少量余额、买 1-2 个号跑通流程，确认目标平台收码正常再批量采购。

美国接码 API 支持指定号段吗？

支持。下单时可以传 prefixes 指定号段；库存接口加 with_prefixes=1 可以看号段明细。号段不足时按实际可售数量返回，不会用其他号段硬凑。

取验证码要一直轮询吗？

不用。GET /api/open/code 支持 wait=0-30 秒长轮询，没码时最多等指定秒数再返回，比每秒轮询省资源，也更实时。

下单超时了怎么办？

带上同一个 order_no 原样重试；order_no 是幂等键，重试只会返回同一笔订单，不会重复扣费。也可以用 GET /api/open/order?order_no=... 查回号码。

API 有频率限制吗？

有基础限流，正常取码轮询与批量下单足够用；大客户可以联系客服提高额度。