测吉凶：5 分钟接入指南（手机号/车牌号/QQ号/公司名）
# 测吉凶：5 分钟接入指南（手机号/车牌号/QQ号/公司名）
> 接口/接入点：测吉凶 apiCode=1617（1617-1/2/3/4） · 免费服务 · 请求方式 POST/GET · 返回格式 JSON · 适用人群：新注册用户、想把趣味功能塞进自己产品的开发者 · 阅读时间：约 5 分钟
## 核心要点
- 注册 ShowAPI 后取 AppKey，四个接入点共用同一把 AppKey，仅 URL 路径末位 `1617-N` 不同。
- 每个接入点**只传 1 个业务参数**（`mobile` / `carNo` / `qq` / `companyName`），其余交给 AppKey 鉴权。
- 返回业务数据都在 `showapi_res_body.expList` 里，它是**字符串数组**，按「前缀：内容」逐条展示即可。
## Why：这跟我有什么关系
你在做社交 App、活动页、或者只是想给自己的网站加个「测测你的号码吉凶」小彩蛋？测吉凶接口把周易数理的吉凶分析封装成了标准 HTTP 接口，免费、按次计、无需自建算法。注册即有免费档位，几行代码就能跑通，是成本最低的趣味功能试点。
## What：前置条件与接口速览
| 项 | 说明 |
|------|------|
| 接口地址 | `https://route.showapi.com/1617-N?appKey=YOUR_APPKEY`（N=1 手机号 / 2 车牌号 / 3 QQ号 / 4 公司名） |
| 请求方式 | POST 或 GET，表单 `application/x-www-form-urlencoded` |
| 鉴权 | AppKey 作为 query 参数 `appKey` |
| 计费 | 免费服务，按次计（实测 `showapi_fee_num=1`），受账户免费档位限制 |
| 返回格式 | JSON，业务数据在 `showapi_res_body` |
| 集成能力 | MCP（Cherry Studio/ChatBox）、OpenAPI 3.0 YAML/JSON |
前置条件：① 已注册 ShowAPI 账号；② 在[控制台](https://www.showapi.com/console#/myApp)拿到 AppKey；③ 开发环境能发起 HTTPS 请求。
## How：从注册到第一个调用
下面以**手机号测吉凶（1617-1）**为例，三步跑通。把 `YOUR_APPKEY` 换成真实 AppKey 即可。
### Python（requests）
```python
import requests
url = "https://route.showapi.com/1617-1"
params = {"appKey": "YOUR_APPKEY"}
data = {"mobile": "13770000000"} # 手机号测吉凶的必填参数
try:
r = requests.post(url, params=params, data=data, timeout=15)
r.raise_for_status()
body = r.json()["showapi_res_body"]
if body.get("ret_code") != "0":
print("接口返回失败：", body.get("remark"))
else:
print("remark:", body.get("remark"))
for line in body.get("expList") or []:
print("-", line)
except requests.RequestException as e:
print("请求异常：", e)
```
### cURL
```bash
curl -X POST "https://route.showapi.com/1617-1?appKey=YOUR_APPKEY" \
-H "content-type: application/x-www-form-urlencoded" \
-d "mobile=13770000000"
```
### Node.js（fetch）
```javascript
const url = "https://route.showapi.com/1617-1?appKey=YOUR_APPKEY";
const body = new URLSearchParams({ mobile: "13770000000" });
try {
const res = await fetch(url, { method: "POST", body, signal: AbortSignal.timeout(15000) });
const json = await res.json();
const b = json.showapi_res_body;
if (b.ret_code !== "0") { console.log("失败：", b.remark); }
else { (b.expList || []).forEach((line) => console.log("-", line)); }
} catch (e) { console.error("请求异常：", e); }
```
切换其他接入点只需改两处：URL 末位 `1617-N`，以及 `data` 里的参数名（车牌号用 `carNo`、QQ 用 `qq`、公司名用 `companyName`）。
## 返回示例与解析
实测 1617-1 返回（已精简）：
```json
{
"showapi_res_code": 0,
"showapi_res_id": "6a97b736fb638c36633456ba",
"showapi_fee_num": 1,
"showapi_res_body": {
"ret_code": "0",
"remark": "查询成功！",
"title": "",
"expList": [
"号码：13770000000",
"数理：第81数",
"签语：最极之数，还本归元，能得繁业，发达成功",
"吉凶：吉",
"详解：主人的性格类型：[自我牺牲/性格被动型]，其具体表现为：习惯于无条件付出……"
]
}
}
```
- `showapi_res_code`：系统级状态码，`0` 表示通道正常。
- `showapi_fee_num`：本次消耗计费次数（免费档位内扣减）。
- `showapi_res_body.ret_code`：业务结果，`"0"` 为成功，其他为失败，失败看 `remark`。
- `expList`：**字符串数组**，每条以「前缀：」开头，直接逐行渲染即可。
## 进阶 / 边界
- **`title` 字段恒为空字符串**（四个接入点实测均如此），页面展示不用依赖它。
- 公司名接入点（1617-4）**可能返回无 `expList`**（仅 `ret_code`+`remark`），务必做空数组兜底，详见[公司名测吉凶专篇](https://www.showapi.com/guides/fortune-company-guide-1617)。
- 免费档位有调用量限制，正式上线前确认档位额度，避免超限报错。
## FAQ
**Q：四个接入点要四把 AppKey 吗？**
不需要。同一账号的 AppKey 对所有接入点通用，区别只在请求 URL 的 `1617-N` 路径。
**Q：返回里的 expList 是数组还是字符串？**
实测是**字符串数组**（如 `["号码：1377…","数理：第81数",…]`）。注意 OpenAPI 文档曾把它标成 `string`，以实测为准。
**Q：免费接口为什么还会扣 showapi_fee_num？**
免费指「注册默认可调用、有档位额度」，每次调用仍按 1 次计费从免费额度中扣减，超额需升级档位。
**Q：GET 和 POST 都能用吗？参数怎么传？**
都可以，均用表单 `application/x-www-form-urlencoded`；GET 时参数拼到 query（与 appKey 同处），POST 时放 body。
## 相关能力 / 下一步阅读
- [测吉凶返回字段全解：ret_code、remark 与 expList 数组一文读懂](https://www.showapi.com/guides/fortune-response-fields-1617)
- [手机号测吉凶：如何解析号码数理、签语与性格暗示？](https://www.showapi.com/guides/fortune-mobile-guide-1617)
- [做一个号码测吉凶小工具：HTML+JS 前端 Demo 实战](https://www.showapi.com/guides/fortune-web-demo-1617)
- **本系列共 13 篇**：查看[测吉凶指南总目录](https://www.showapi.com/guides/fortune-guides-1617)
