运营商在网状态查询 API
企业系统里经常会遇到这样一种情况：用户注册时留下的手机号还在数据库里，但短信发不出去，电话也联系不上。 这并不一定意味着用户主动失联。 手机号在使用过程中可能出现很多状态：正常在网、停机、在网但不可用、销号、关机，或者暂时无法判断。对系统来说，如果只是把手机号分成“有”和“没有”，就很难知道问题到底发生在哪里。 因此，在发送通知、维护客户资料或者处理长期未活跃号码时，可以先查询手机号当前的运营商在网状态，再决定后续业务流程。 ## 一、手机号“存在”不等于号码还能正常使用 很多业务系统保存手机号后，很少再检查号码后续有没有变化。 但一串手机号能够通过格式校验，只能说明它看起来像一个有效手机号，并不能证明这个号码当前还能正常使用。 例如，同一个手机号可能处于： |状态|可以怎么理解| | --- | --- | |正常在网|当前号码处于在网状态| |停机|号码当前处于停机状态| |在网不可用|号码仍在网，但当前不可正常使用| |空号（销号）|当前号码已不在网| |关机|当前处于关机状态| |未知|当前无法进一步确定具体状态| 这几个状态在业务上的含义并不一样。 例如“停机”和“销号”都可能表现为暂时联系不上，但前者并不等于号码已经注销。如果系统把所有联系失败的号码直接标记成“无效手机号”，就可能过早清理仍有恢复可能的用户资料。 ## 二、查询逻辑并不复杂，关键是状态怎么判断 在系统实现上，可以把号码状态查询放在短信触达、客户资料维护或者号码清洗流程之前。 返回格式为 JSON，请求方式不限。 请求参数只有两个： |参数|必填|类型|说明| | --- | --- | --- | --- | |key|是|string|接口调用凭证| |phone|是|string|需要查询的手机号| 例如后端拿到手机号后，提交 `phone` 和调用凭证，再读取接口返回的状态字段即可。 核心返回字段包括： |字段|说明| | --- | --- | |phone|手机号| |isp|运营商| |desc|状态描述| |status|在网状态| |outline_status|不在网时的细分状态| |outline_desc|不在网状态描述| |province|省份| |city|城市| |zipcode|邮编| 真正需要重点处理的是 `status` 和 `outline_status` 两层关系。 ## 三、status=1 不应该直接写成“无效号码” 当前接口首先通过 `status` 判断号码是否在网： |status|含义| | --- | --- | |0|在网| |1|不在网| 如果返回： `status = 0` 说明当前号码处于在网状态。 如果返回： `status = 1` 则还需要继续读取 `outline_status`。 当前细分状态包括： |outline_status|状态| | --- | --- | |1|停机| |2|在网不可用| |3|空号（销号）| |4|关机| |5|未知| 例如返回： ```javascript { "code": 1, "msg": "操作成功", "data": { "phone": "18577881111", "isp": "联通", "desc": "不在网", "status": 1, "outline_status": 3, "outline_desc": "空号(销号)", "province": "广西", "city": "南宁市", "zipcode": "530000" } } ``` 这时候系统能得到的不只是“不在网”，还可以进一步知道当前属于“空号（销号）”。 所以程序里不建议只写： `status == 1 → 无效号码` 更合理的是： `status == 1 → 继续判断 outline_status` 这样停机、销号、关机和在网不可用就不会被混成同一种状态。 ## 四、业务系统为什么要区分这些状态？ 假设企业正在处理一批长期未活跃用户。 其中两个手机号都联系不上： A 用户返回“停机”。 B 用户返回“空号（销号）”。 如果只看“短信失败”或者“电话打不通”，两者没有明显区别。 但从号码状态来看，情况并不一样。 停机号码后续仍然可能恢复使用，而销号表示当前号码已经不在网。因此，系统可以根据自己的业务规则，对不同状态采用不同处理方式。 例如客户资料中可以增加： - 手机号 - 当前运营商 - 号码状态 - 状态检测时间 当号码状态发生变化时，再进入企业自己的后续处理流程。 这里需要注意，接口能确认的是**号码状态**，不能直接推断用户已经流失、主动注销账号或者不再希望接收通知。 ## 五、运营商和地区字段怎么用？ 除了状态字段，接口还会返回运营商和地区信息。 `isp` 可以返回： - 移动 - 联通 - 电信 - 广电 同时还包括： - `province` - `city` - `zipcode` 这些信息可以作为手机号基础数据的一部分保存。 不过，地区字段更适合作为号码相关的归属信息理解，不应该直接当成用户当前所在位置。 另外，如果业务涉及携号转网，也不建议只根据手机号段自行判断当前运营商。号码发生携号转网后，传统号段与当前运营商可能不再完全一致。 因此，如果系统真正需要当前运营商信息，读取接口返回的 `isp` 会比自己长期维护号段规则更直接。 ## 六、接入时最容易混淆的几类异常 第一，格式正确不等于号码正常在网。 手机号正则校验只能判断输入格式，不能判断停机、销号或关机。 第二，查询失败不能等同于号码不在网。 当前服务级错误码包括： |错误码|说明| | --- | --- | |212301|缺少必要参数| |212302|查询失败| 如果返回 212302，只能说明本次查询没有正常完成，不能把号码直接标记成“停机”或“销号”。 第三，系统级错误应该和业务状态分开处理。 例如： |错误码|说明| | --- | --- | |10001|错误的请求 KEY| |10002|该 KEY 无请求权限| |10003|KEY 过期| |10004|未知的请求源| |10005|被禁止的 IP| |10006|被禁止的 KEY| |10007|请求超过次数限制| |10008|接口维护| 这些属于接口调用层面的异常，不应该写入用户的号码状态。 正式接入时，可以把流程拆成： 请求是否成功 → 是否返回业务结果 → 判断 `status` → 必要时继续判断 `outline_status` 这样排查问题时会清楚很多。 ## 写在最后 数据库里存在一个手机号，并不代表这个号码今天仍然能够正常联系。 正常在网、停机、在网不可用、空号（销号）、关机和未知状态，对业务系统来说代表的是不同情况。 号码状态查询真正解决的，是把原本模糊的“为什么联系不上”，拆成可以被程序识别和处理的状态。 接入时，先通过 `status` 判断是否在网，再结合 `outline_status` 识别具体情况，同时把运营商和查询时间作为辅助信息保存。这样在客户资料维护、短信通知和号码清洗时，就不需要只依赖一次发送失败来判断一个手机号是否还能使用。
