运营商三要素实名认证：5 分钟完成第一条实名校验
idcard-phone-auth-quickstart-1389 # 运营商三要素实名认证：5 分钟完成第一条实名校验
> **接口**：运营商三要素 - 运营商手机号实名认证 · **接入点**：1389-1 · **apiCode**：1389
> **请求方式**：POST · **返回格式**：JSON · **计费**：按次（ret_code=0 时扣费，具体档位以官方说明为准）
> **适用人群**：新注册用户、初级开发者
> **阅读时间**：8 分钟
> **最后实测核对**：2026-09-07
---
## 核心要点
- 只需传三个字段（姓名 + 身份证号 + 手机号），接口返回认证成功或失败，以及可选的手机号归属地信息。
- 鉴权通过 URL query 参数 `appKey` 传递，无需 Header。
- 错误码 `code=0` 表示认证成功，`code=1` 表示认证失败，另有 6 种错误场景需排查。
---
## 为什么用这个接口
用户在电商平台注册时填了手机号，你需要确认这个手机号确实是这个人名下登记的——这是最常见的实名校验场景。运营商三要素接口一次调用就能拿到结果，不用自己维护任何号段库或运营商数据。
另一个常见用法：风控系统发现异常登录，需要二次验证用户身份，可以直接调这个接口确认手机号与身份证是否匹配。
---
## 前置条件
1. 在 [ShowAPI 控制台](https://www.showapi.com/console#/myApp) 注册账号，获取 `appKey`。
2. 在接口详情页确认已购买相应套餐（按次计费，具体档位以官方说明为准）。
---
## 接口速览
| 项目 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/1389-1` |
| 请求方式 | POST |
| Content-Type | `application/x-www-form-urlencoded` |
| 鉴权方式 | URL query 参数 `appKey` |
| 是否需要登录态 | 否（仅 appKey 鉴权） |
| 响应格式 | JSON |
---
## 请求参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| idCard | String | 是 | 手机号实名对应的身份证号 |
| name | String | 是 | 手机号实名对应的姓名 |
| phone | String | 是 | 三网手机号 |
| needBelongArea | String | 否 | 是否返回手机号归属地信息，默认 `true` |
> `needBelongArea` 不传时默认为 `true`，返回归属地信息；传 `false` 则只返回认证结果，不返回归属地。
---
## 第一次调用
### Python（requests）
```python
import requests
import time
APPKEY = "YOUR_APPKEY" # 替换为你的真实 AppKey
url = "https://route.showapi.com/1389-1"
params = {
"appKey": APPKEY,
"idCard": "11010119900307421X", # 示例身份证号，实际请使用测试号或授权数据
"name": "张三", # 示例姓名
"phone": "13800138000", # 示例手机号
"needBelongArea": "true"
}
try:
resp = requests.post(url, data=params, timeout=10)
resp.raise_for_status()
data = resp.json()
# 系统层检查
if data.get("showapi_res_code") != 0:
print(f"系统调用失败: {data.get('showapi_res_error')}")
else:
body = data.get("showapi_res_body", {})
ret_code = body.get("ret_code")
code = body.get("code")
msg = body.get("msg", "")
print(f"业务结果 code={code}, msg={msg}")
# 认证成功（code=0）时查看归属地
if code == 0 and "belongArea" in body:
ba = body["belongArea"]
print(f"归属地: {ba.get('prov')}{ba.get('city')}")
print(f"运营商: {ba.get('name')} (type={ba.get('type')})")
print(f"号段: {ba.get('num')}")
except requests.exceptions.Timeout:
print("请求超时（超过 10 秒），请检查网络或联系接口方")
except Exception as e:
print(f"请求异常: {e}")
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1389-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "idCard=11010119900307421X&name=张三&phone=13800138000&needBelongArea=true"
```
### Node.js（fetch）
```javascript
const APPKEY = "YOUR_APPKEY"; // 替换为你的真实 AppKey
const url = `https://route.showapi.com/1389-1?appKey=${APPKEY}`;
const params = new URLSearchParams({
idCard: "11010119900307421X",
name: "张三",
phone: "13800138000",
needBelongArea: "true"
});
try {
const resp = await fetch(url, {
method: "POST",
headers: { "content-type": "application/x-www-form-urlencoded" },
body: params,
signal: AbortSignal.timeout(10000) // 10 秒超时
});
const data = await resp.json();
if (data.showapi_res_code !== 0) {
console.log(`系统调用失败: ${data.showapi_res_error}`);
} else {
const body = data.showapi_res_body || {};
const code = body.code;
const msg = body.msg || "";
console.log(`业务结果 code=${code}, msg=${msg}`);
if (code === 0 && body.belongArea) {
const ba = body.belongArea;
console.log(`归属地: ${ba.prov}${ba.city}`);
console.log(`运营商: ${ba.name} (type=${ba.type})`);
console.log(`号段: ${ba.num}`);
}
}
} catch (err) {
if (err.name === "TimeoutError") {
console.log("请求超时（超过 10 秒），请检查网络或联系接口方");
} else {
console.log(`请求异常: ${err.message}`);
}
}
```
---
## 返回示例（2026-09-07 实测）
以下为认证成功时的真实返回结构（示例数据已脱敏）：
```json
{
"showapi_res_error": "",
"showapi_res_code": 0,
"showapi_res_id": "60740ce48d57ba8f1c10fb44",
"showapi_res_body": {
"ret_code": 0,
"order": "6ddaf1ec67a343dc814c833ff0ae855f",
"code": 0,
"belongArea": {
"num": 1362068,
"prov": "山西",
"name": "移动神州行卡",
"provCode": "140000",
"type": 1,
"city": "临汾市"
},
"msg": "认证成功"
}
}
```
### 返回字段说明
| 字段 | 类型 | 说明 |
|------|------|------|
| `showapi_res_code` | Number | 系统层状态码，0 表示调用成功 |
| `showapi_res_error` | String | 系统层错误信息，成功时为空白 |
| `showapi_res_body.ret_code` | Number | 业务层状态码，0 表示调用成功（扣费） |
| `showapi_res_body.code` | Number | **业务认证结果码**，见下方错误码表 |
| `showapi_res_body.msg` | String | 认证结果提示信息 |
| `showapi_res_body.belongArea` | Object | 归属地信息（needBelongArea=true 时返回） |
| `belongArea.prov` | String | 省名 |
| `belongArea.city` | String | 市名 |
| `belongArea.name` | String | 运营商名称（如"移动神州行卡"） |
| `belongArea.num` | Number | 号段 |
| `belongArea.provCode` | Number | 省别编码，本省身份证的前几位编码 |
| `belongArea.type` | Number | 运营商类型：1=移动 2=电信 3=联通 4=广电 |
| `showapi_res_body.order` | String | 渠道订单号 |
---
## 错误码快速对照
| code 值 | 含义 | 处理建议 |
|---------|------|---------|
| 0 | 认证成功 | 正常流程，可继续业务 |
| 1 | 认证失败（三要素不匹配） | 告知用户信息有误，允许重新输入 |
| 2 | 无该手机号记录 | 该手机号未实名认证，考虑引导用户绑定真实号码 |
| 11 | 手机号、身份证或者姓名为空 | 检查参数是否遗漏 |
| 12 | 身份证校验错误 | 身份证号格式不正确，引导用户修正 |
| 13 | 手机号校验错误 | 手机号格式不正确，引导用户修正 |
| 21 | 渠道升级暂停服务 | 联系 ShowAPI 客服 |
| 22 | 渠道维护暂停服务 | 联系 ShowAPI 客服 |
详细排查见 → [运营商三要素实名认证：完整错误码对照表](https://www.showapi.com/guides/idcard-phone-auth-response-codes-1389)
---
## 进阶：只查认证不查归属地
如果业务只需要知道"是否匹配"，不需要归属地信息，可以传 `needBelongArea=false` 减少返回数据量：
```python
params["needBelongArea"] = "false"
```
---
## FAQ
**Q1：接口返回 code=1 是什么原因？**
运营商三要素实名认证接口 code=1 表示"认证失败"，即传入的姓名、身份证号、手机号三者与运营商记录不匹配。请引导用户检查输入信息是否有误后重新提交。
**Q2：needBelongArea 传 false 后 belongArea 字段还会返回吗？**
不会。needBelongArea=false 时，`belongArea` 字段不会出现在返回 JSON 中。
**Q3：接口支持港澳台手机号吗？**
文档未明确说明。建议先用测试号码验证，或在控制台咨询客服。
**Q4：同一组参数重复调用会重复扣费吗？**
按文档表述"ret_code=0 时扣费"，每次调用成功均会扣费。如需避免重复扣费，请参考 → [缓存策略文章](https://www.showapi.com/guides/idcard-phone-auth-cache-cost-1389)。
**Q5：调用频率有限制吗？**
文档未明确说明 QPS 限制。高并发场景建议先小流量测试，或联系 ShowAPI 客服确认。
---
## 下一步阅读
- [完整错误码对照表](https://www.showapi.com/guides/idcard-phone-auth-response-codes-1389) —— code=1 时怎么排查
- [注册实名校验集成方案](https://www.showapi.com/guides/idcard-phone-auth-scenario-integration-1389) —— 业务层如何设计
- [三要素 vs 二要素 vs 四要素方案对比](https://www.showapi.com/guides/idcard-phone-auth-comparison-1389) —— 选型决策参考
---
**- 本系列共 6 篇**：查看[运营商三要素实名认证指南总目录](https://www.showapi.com/guides/idcard-phone-auth-guides-1389)
