NexSms官方博客
对接接码 API，真正要写的只有四个动作：鉴权并取一次可用配置 → 申请号码 → 等验证码 → 结单或取消。剩下的工作量几乎全花在后两步的异常分支上——轮询多快、等多久、没收到码怎么退额、换号怎么不卡住整条流水线。
下面按这条链路走一遍。各家平台字段名不同（getNumber / getStatus / setStatus 是比较常见的一套），但阶段划分和你要处理的状态是通用的。具体 Endpoint、鉴权头格式和 JSON 字段，以你所用平台开发者后台的文档为准，别照抄别家的参数名。
第一步：鉴权之外，先确认这个国家这个应用现在有号
带 API Key 校验是最基本的，但只做这一步不够。上线前和每次批量任务启动前，还要拉一次可用配置：账户余额、支持的国家列表、支持的目标服务列表。
原因很实际——国家和库存是会变的。你代码里写死的那个国家代码，今天可能正好没号。把这份配置当成运行时数据缓存几分钟，比硬编码要稳。
第二步：取号时真正要存的是订单号，不是手机号
取号接口一般传两个关键参数：国家代码，和目标应用标识（你要在哪个平台收码）。返回里给你一个手机号和一个订单 ID（常见叫 activation_id）。
这里最容易犯的错是把手机号当主键。后面查状态、确认完成、取消退款，接口认的全是订单 ID，手机号只是填进目标平台表单的展示值。取号成功后第一件事就是落库：订单 ID、号码、国家、目标应用、取号时间戳、当前状态。
还有一点：取号成功不等于这个号能用。号码提交到目标平台之后才知道对方收不收——有的平台当场就提示号码不受支持，那是你的业务失败，不是接码平台的失败，日志里要分开记。
第三步：收码——轮询 3 到 5 秒一次，超时按目标平台的码有效期定
拿码有两种方式。
轮询：带订单 ID 周期性调 getStatus，间隔建议 3–5 秒。调太密很容易撞上平台的频率限制被临时封 Key，尤其并发几十单的时候——限流通常按账号算总量，不是按单算。调太稀则拖长每单占用时间，并发一上来就堵。
Webhook：平台把短信原文和解析出的验证码推给你，省掉轮询开销，但你得自己处理重复推送和乱序，落库时按订单 ID 做幂等。
超时时间别拍脑袋。参考目标平台验证码本身的有效期，常见是 3–5 分钟；你等 10 分钟拿到的码，填进去多半也过期了。到点就走取消分支，别让一个单子吊着整条队列。
另外，拿到短信原文后自己再解析一次验证码，别完全依赖平台给的 code 字段。目标平台改了短信模板，解析结果就可能是空的，原文还在你就还有的救。
第四步：结单——收到要确认，没收到要主动取消
收到码且业务侧验证通过，调 setStatus 一类的接口标记完成，订单关闭。
没收到码，主动调取消接口释放号码，多数平台会把额度退回。不取消的代价不只是少退那点钱，而是这个订单可能一直挂着，你的重试逻辑会一直以为它还在等。
有的平台还有等待重发（STATUS_WAIT_RESEND）这类状态，意思是让你去目标平台点一次重新发送，订单继续有效。遇到它别直接取消重开单——换号重来的成本比重发一次高得多。
状态机至少要覆盖这几类返回
- 等待收码（STATUS_WAIT_CODE）：继续轮询，直到超时。
- 接收成功（STATUS_OK，带验证码文本）：走结单。
- 已取消已退款（STATUS_CANCEL）：订单终结，按业务决定要不要换号重试。
- 等待重发（STATUS_WAIT_RESEND）：提示或触发目标平台重发，不要立刻弃单。
- 库存不足（NO_NUMBERS）：换国家或退避几秒重试，这是最常见的静默降级场景。
- 余额不足（NO_BALANCE）：必须告警，不要静默重试——重试一万次也不会有号。
原则是：号不可用就换号，账不可用就停下来喊人。这两类混用同一套重试，就会出现半夜空转几小时的情况。
这段代码按短效写还是按长效写，动手前先定
这是唯一会改变代码结构的决定。
短效按量号码：用完即止，有效期很短，收码确认后订单自动关闭。API 侧就是标准的一次性生命周期——取号、收码、结单，号码不归你，之后找不回来。适合一次性注册、彼此互不关联的验证。
长效号码：如果业务后面还有换绑、二次验证登录、几天内多次收码，短效号一释放就没法找回，等于账号失去了恢复通道。这种情况要在设计阶段就选可续费的长效号，并在自己的系统里维护持有状态和到期时间——到期前续费才继续持有。对应的代码不是取号逻辑，而是一张号码资产表加一个到期提醒。
NexSMS 两类都有：短效号码按量计费、用完即止；长效精品号码是真实运营商本土号码（实体卡与 eSIM，不是虚拟落地号），有效期内不限次接码、可续费；网页端能实时看码，也提供开发者 API。两种号的计费口径和续费条件在功能与号码类型说明页上，先照你的业务是「单次」还是「要复收」去对照。想先手动跑一遍流程再写代码，免费公共号码页不用注册，可以看看短信到达是什么样——但公共号所有人都能看到，只适合演练，不能用来收真实账号的码。
选号这一步的判断依据，可以参考短效号码和长效精品号码怎么选；长效号的续费节奏见长效号码到期前怎么续费才不断号。
换号和换国家：容错写在业务层，不要指望 API 保证
一个号码能不能通过某个平台的验证，由那个平台当时的风控规则决定，接码 API 这边给不了保证。所以自动化流程里留两个口子：
换号重试的次数上限。同一个目标平台连续失败 2–3 次就该停。继续换号，往往是同一类号码在被同一条规则挡，纯属烧额度。
换国家的降级路径。允许配置国家优先级列表，库存不足或连续失败时按序降级。
失败原因一定要分开记：接码平台没给出号、给了号但目标平台不收、号码正常但码没到。这三类处理方式完全不同，混成一个笼统的失败率，你什么都调不出来。第三类的排查顺序可以参考提交号码后一直没收到短信。
上线前过一遍这几条
- 订单 ID 落库了吗？能不能只靠它重建所有在途单的状态？
- 轮询间隔是全局节流的，还是每个线程各调各的？
- 超时时间和目标平台的码有效期对得上吗？
- 超时、异常、进程重启这三种情况，都会走到取消分支吗？
- 余额告警和库存降级是两套独立逻辑吗？
- 短信原文存了吗？只存解析后的 code，模板一变你就瞎了。
最容易漏的是进程重启。跑批机器重启一次，内存里那些在途订单没人管了——号码占着、额度不退、状态永远停在等待。所以订单状态必须在数据库里，不能只在内存里。
评论(0)