三网话费余额

接口说明

三网话费余额用于实时查询中国联通、中国移动、中国电信手机号的话费余额，返回运营商、归属地与当前余额信息。适合需要批量或即时掌握号码话费状态的开发者与业务系统调用，按次计费。

调用地址

https://api.xunjinlu.fun/apis/xcbill

请求方式

GET

鉴权说明

本接口必须携带密钥调用，密钥通过 Query 参数 key 传递，即在请求地址后附加 key=你的接口密钥。未携带或密钥无效时无法获取数据。

请求参数

调用地址：https://api.xunjinlu.fun/apis/xcbill，请求方式：GET。必须携带密钥，密钥以 Query 参数形式传递（key=…）。

参数取值说明：

• phone 须为 11 位官方手机号，支持中国联通、中国移动、中国电信三网号码；请填写真实号码，非 11 位或格式不符的号码无法完成查询。
• key 为调用凭证，需与请求一并提交，缺失或无效将无法获取数据。

频率限制：每分钟约 60 次。

成功响应示例

{
  "code": 200,
  "msg": "请求成功",
  "data": {
    "手机号": "13400134000",
    "运营商": "中国移动",
    "归属地": "河北 张家口",
    "余额": "133.07"
  }
}

响应字段说明

说明：data 内字段随查询号码所属运营商返回，均为字符串类型；余额 为账户可用余额，欠费情况下可能为负值或 0.00。

错误响应示例

接口在调用失败时统一返回 JSON 结构，其中 code 为业务层状态码，msg 为可读的错误描述，errcode 为具体业务错误码。HTTP 状态码始终为 200，请以响应体中的 code 与 errcode 作为判断依据。

未提供调用密钥时的响应示例：

{
  "code": 0,
  "msg": "未提供调用密钥",
  "errcode": 11001
}

密钥错误时的响应示例：

{
  "code": 0,
  "msg": "密钥错误",
  "errcode": 11002
}

积分余额不足时的响应示例：

{
  "code": 0,
  "msg": "积分余额不足",
  "errcode": 11004
}

请求过于频繁时的响应示例：

{
  "code": 0,
  "msg": "请求过于频繁",
  "errcode": 11005
}

接口维护中的响应示例：

{
  "code": 0,
  "msg": "接口维护中",
  "errcode": 11006
}

调用成功时返回 code 为 200，并携带 data 业务数据；失败时 code 为 0，data 字段不返回或为空，具体原因由 errcode 指明。

业务错误码说明

下表列出本接口在调用过程中可能返回的全部业务错误码及其含义。同一个 errcode 在所有接口中的语义保持一致。

错误码分组速查

为便于排查，可按类别理解上述错误码：

• 密钥与鉴权类：11001、11002、11003、11009、11011、11012、11023
• 计费与额度类：11004、11010、11024
• 频率与访问控制类：11005、11019
• 接口状态类：11006、11007、11008、11013、11018、11017
• 数据来源与出口代理类：11014、11015、11016、11020、11021、11022

代理类接口同样适用 11013 至 11016 以及 11017 的返回语义：当接口路径不存在、数据来源地址无效、数据来源地址不被允许、向数据来源发起请求失败，或服务整体暂不可用时，均会按上表返回对应的 errcode。

调用示例

终端 curl（bash）

curl -G "https://api.xunjinlu.fun/apis/xcbill" \
  --data-urlencode "key=你的接口调用密钥" \
  --data-urlencode "phone=13400134000"

PHP

// PHP 调用示例
$url = "https://api.xunjinlu.fun/apis/xcbill";
$params = [
    "key"   => "你的接口调用密钥",
    "phone" => "13400134000",
];

$requestUrl = $url . "?" . http_build_query($params);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $requestUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
if (isset($data["code"]) && $data["code"] == 200) {
    echo "手机号：" . $data["data"]["手机号"] . "\n";
    echo "运营商：" . $data["data"]["运营商"] . "\n";
    echo "归属地：" . $data["data"]["归属地"] . "\n";
    echo "余额：" . $data["data"]["余额"] . "\n";
} else {
    echo "请求失败：" . (isset($data["msg"]) ? $data["msg"] : "未知错误");
}

注意事项

• 密钥仅走 Query 传递：调用时把密钥放在 URL 的 key 参数中，例如 https://api.xunjinlu.fun/apis/xcbill?key=你的密钥&phone=13400134000。不要在请求体、Cookie 或其它位置额外传密钥，也不要同时使用多种传参写法。
• 密钥务必保密：key 一旦泄露，任何人都能消耗你的账户额度。请保存在服务端配置或环境变量中，不要写入前端页面、小程序代码、公开仓库或客户端可反编译的资源里；建议按业务分配独立密钥，出现异常消耗时及时更换。
• 本接口为收费接口：每次成功发起查询都会产生计费。请勿在页面加载、循环、定时任务中对同一号码反复调用，建议在业务层先做一次结果缓存或去重，避免无效请求造成浪费。
• 频率限制约为每分钟 60 次：超频可能被临时拒绝。批量查询时请控制并发并加入适当间隔，收到限流响应后应退避重试，而不是立即高频重发。
• 必须使用 HTTPS：调用地址为 https://api.xunjinlu.fun/apis/xcbill，请原样使用该域名与路径，不要改用 http、不要替换域名或补加多余后缀，否则请求无法正确路由。
• phone 必须是 11 位官方手机号：仅传数字，不要带 +86、空格、短横线或其它分隔符；号码错误会导致查询失败，但仍可能计入调用。该参数与 key 同为必填，缺一不可。
• 返回结果请做校验：正常时 code 为 200，余额位于 data.余额，为字符串形式的金额；data.手机号、data.运营商、data.归属地 用于核对号码与运营商是否与预期一致。若 code 非 200，应以 msg 作为错误提示处理，不要把异常返回当成余额 0 展示。
• 合理展示与留存：话费余额属于用户隐私信息，仅用于当前业务展示，不要在前端日志、埋点或公开页面中明文打印完整手机号与余额，服务端存储也应做必要的脱敏或权限控制。