📋 一、运营商二要素和三要素 API 是什么

用户在办理手机号入网时，运营商会登记对应的姓名和身份证号。运营商二要素/三要素核验 API 通过调用运营商权威数据，将用户提交的信息与入网登记信息进行比对，返回核验结论。

核验的核心作用是确认：用户声称的身份信息，是否确实对应其使用的手机号。

这类接口适用于需要进行用户实名信息一致性核验的业务场景，例如用户注册、实名认证和业务办理前的信息校验等。

🔍二、二要素和三要素有什么区别

二要素和三要素的区别在于每次核验所需提交的信息项数。

核验类型对比

怎么选择

• ✅ 已有姓名和手机号 → 使用姓名+手机号二要素接口
• ✅ 已有手机号和身份证号 → 使用手机号+身份证号二要素接口
• ✅ 三项信息都有 → 可根据业务核验要求选择三要素接口

两种二要素接口各有适用场景，可根据业务实际收集到的字段灵活选择。

📊 三、接口返回什么：res 状态码说明

所有核验接口统一使用 res 字段表示核验结果。

res=3 是常见的正常返回结果，不应视为接口故障。建议在业务逻辑中单独处理该情况，引导用户确认手机号是否仍处于正常使用状态。

🎫 四、运营商二要素 API 接口说明

4.1 姓名 + 手机号二要素

接口地址：

https://www.tanshuapi.com/market/detail-121

请求方式： GET / POST

请求参数

请求示例

https://www.tanshuapi.com/market/detail-121?key=YOUR_API_KEY&name=张三&mobile=13800138000

返回示例

{
    "code": 1,
    "msg": "操作成功",
    "data": {
        "name": "张三",
        "mobile": "13015566219",
        "res": 1,
        "description": "一致"
    }
}

4.2 手机号 + 身份证号二要素

接口地址：

https://www.tanshuapi.com/market/detail-121

请求方式： GET / POST

请求参数

请求示例

https://www.tanshuapi.com/market/detail-121?key=YOUR_API_KEY&mobile=13800138000&idcard=110101199001011234

返回示例

{
    "code": 1,
    "msg": "操作成功",
    "data": {
        "idcard": "110101199001011234",
        "mobile": "13015566219",
        "res": 2,
        "description": "不一致"
    }
}

🔧 五、运营商三要素 API 接口说明

接口地址：

https://www.tanshuapi.com/market/detail-110

请求方式： GET / POST

请求参数

请求示例

https://www.tanshuapi.com/market/detail-110?key=YOUR_API_KEY&name=张三&idcard=110101199001011234&mobile=13800138000

返回示例

{
    "code": 1,
    "msg": "操作成功",
    "data": {
        "name": "张三",
        "idcard": "41132819950207719X",
        "mobile": "13010002547",
        "res": "3",
        "description": "无记录",
        "sex": "",
        "birthday": "",
        "address": ""
    }
}

三要素额外返回字段

三要素接口在核验结果之外，还可能返回以下字段：

以上字段仅在核验通过（res=1）且运营商数据可查时返回。若 res=2 或 res=3，字段可能为空。如果业务需要获取性别、生日等信息，需结合自身业务逻辑处理空值情况。

📝 六、返回字段完整说明

⚠️ 七、常见错误码

服务级错误码

系统级错误码

排错建议： 如果请求失败，先根据服务级错误码判断是否参数有误，再检查 API Key 状态、请求来源及调用次数限制。

💬 八、实际业务中怎么选择二要素还是三要素

场景 A：用户注册时核验手机号归属

用户在注册流程中填写了姓名和手机号，需要验证该手机号是否与该姓名匹配。此时使用姓名+手机号二要素接口即可。

场景 B：实名信息一致性核验

业务流程中需要同时确认用户的姓名、身份证号和手机号是否一致时，可使用三要素接口进行核验。相比二要素，三要素同时核验三项信息，适用于信息要求更完整的业务场景。

场景 C：已有身份证号和手机号，缺少姓名

用户在其他流程中已完成实名认证，平台已持有身份证号和手机号，仅需验证这两项信息是否关联。此时使用手机号+身份证号二要素接口。

场景 D：业务办理前的信息确认

用户提交业务申请时，如果平台需要进一步确认姓名、身份证号和手机号之间的一致性，可调用三要素接口进行信息核验，适用于需要同时核对三项身份信息的业务流程。

🎯 九、常见问题 FAQ

Q1：接口支持哪些运营商的手机号？

支持中国移动、中国联通、中国电信三大运营商，以及携号转网用户。

Q2：有没有免费额度可以测试？

支持申请 API Key 后进行接口测试，具体额度以探数平台实际规则为准。

Q3：res=3（无记录）是什么原因？

res=3 表示运营商无对应手机号的入网记录。建议引导用户确认手机号是否仍正常使用，并检查提交的信息是否正确。

Q4：核验结果返回不一致，是否说明用户身份造假？

不一定。不一致可能由多种原因造成，例如：用户近期更换了手机号但未更新运营商信息、输入错误、姓名使用生僻字或繁体字等。建议结合其他验证手段综合判断，而非仅凭一次核验结果直接定性。

🔑 十、接口速查表