全部文章

基础 URL 换好了,接下来呢?机器人迁移到 handler_api.php 的检查清单

如果你的机器人已经在对接 sms-activate 风格的 API,那么迁移到我们的 handler_api.php 只需要先改配置里的一行:基础地址。端点只有一个,请求用 GET 方法发到 /stubs/handler_api.php,方法名也还是熟悉的那些。难点藏在旧集成里写死的各种假设中:超时、轮询频率、国家 ID、退款逻辑。下面这份检查清单,建议你单独开一个密钥来走一遍,同时让生产流量继续按旧方案运行。

哪些方法保持一致

我们兼容 sms-activate 的 API 覆盖了机器人的主流程 getPrices → getNumber → getStatus → setStatus,以及围绕它的查询类调用:

  • getBalance:密钥所绑定账户的余额;
  • getCountries 和 getServicesList:国家列表和服务列表;
  • getPrices:各服务、各国家的价格;
  • getNumber:为指定服务购买号码;
  • getStatus:激活状态和验证码;
  • setStatus:3 再次请求验证码,6 完成激活,8 取消。

如果你的机器人还调用了其他方法,或者给 setStatus 传了其他值,请在迁移前找到代码里的这些位置,并在测试环境里确认机器人拿到响应后会怎么处理。

机器人逻辑里要检查什么

  1. 国家和服务代码。不要把旧配置里的 ID 直接照搬过来:先拉取 getCountries 和 getServicesList,再和机器人里写死的值逐一核对。
  2. 验证码等待计时。激活时限按服务单独设定,目前均为 1 小时。如果所有服务共用一个常量,机器人要么提前放弃激活,要么还在轮询一个已经关闭的激活。请为每个服务单独计时,并在测试环境里核对各自的时限。
  3. 取消。购买后的第一分钟内,setStatus=8 不会成功。如果机器人一出错就立即取消订单,请加上 60 秒后重试的逻辑。
  4. 请求配额。每个密钥的上限是每分钟 600 次请求。机器人靠轮询 getStatus 来拿验证码,配额的大头就花在这里。三十个激活每秒轮询一次,每分钟就是 1800 次请求,是上限的三倍。同样三十个激活改成每五秒轮询一次,每分钟是 360 次,还能给 getPrices 和 getBalance 留出余量。
  5. 退款。如果到时限结束验证码仍未收到,款项会自动退回;在收到验证码之前取消,也会自动退款。退款只退到账户的内部余额,不会退回银行卡或钱包。收到短信后即视为服务已完成,这类订单不退款。如果你自己有按订单记账的系统,请按这些规则核对一遍。
  6. 再次获取验证码。发送 setStatus=3 后,机器人应回到 getStatus 轮询,而不是关闭激活。
  7. 币种。价格和余额都以美元计算。如果机器人配置里的价格阈值是按卢布等其他货币设定的,请重新换算。
  8. 并发订单。并发上限取决于账户信誉。在后台可以看到当前上限、已占用数量,以及近 7 天收到验证码的订单占比。如果机器人先把号码“囤着备用”,之后又大批取消,就会拉低这个占比。

面向软件作者的 softId

如果你在分发自己的软件,可以把它接入合作伙伴计划。申请需要人工审核,通常不超过一天,审核通过后你会拿到 software_id。软件在购买号码时通过 softId 参数传入这个值,软件作者就能从其用户的每次激活中获得价格 5% 的分成,不设上限。用户用自己的账户付款,他们看到的价格不变。这个参数是可选的:不传的话,API 照常工作。

密钥和测试环境演练

在后台的“API”栏目里,可以创建多个带名称的密钥。密钥字符串只显示一次,我们只保存它的指纹,所以创建后请立刻把密钥存入机密管理工具。如果密钥丢了,就新建一个,并撤销旧的。请求上限按密钥计算,所以测试环境里的测试不会占用生产机器人的配额。

演练步骤:

  1. getBalance:密钥有效,能看到余额。第 3 到 5 步需要余额至少够两次激活。
  2. getPrices:你需要的“服务 + 国家”组合有价格。
  3. getNumber:号码已分配,机器人保存了激活 ID。
  4. getStatus:机器人按生产环境的频率轮询,并且不超出上限。
  5. 第二个号码:再买一个号码,等一分钟后发送 setStatus=8。订单金额应退回余额。

后台会显示每个密钥的最后使用日期。切换之后,看这个日期就能确认请求已经来自生产密钥,而测试密钥已经没有动静,可以撤销了。

先从后台的“API”栏目开始:创建一个名字类似“测试”的密钥,用它按你自己的服务和国家跑一遍 getBalance → getPrices → getNumber,跑完之后再去改生产配置里的地址和密钥。

一分钟拿到第一个号码

注册一分钟,充值两分钟,验证码 20 秒到达。

购买号码
没有订阅费第一小时内可取消退款