紫微斗数排盘API如何集成到传统文化网站？从出生表单到命盘可视化
# 紫微斗数排盘API如何集成到传统文化网站？从出生表单到命盘可视化
> 接口/接入点：紫微斗数排盘（apiCode=1647，接入点 1） · 免费 · 返回 JSON · 适用人群：站长、全栈工程师、文化类 SaaS 产品经理 · 阅读时间约 10 分钟
## 核心要点
- 前端收集「阳历出生时间 + 性别」→ 后端转发接口（AppKey 放服务端，避免泄露）→ 拿到 `result` 渲染十二宫表格。
- 命盘天然按 `(time, gender)` 稳定，适合做服务端缓存，省免费额度。
- 十二宫顺序固定，前端用循环渲染即可，无需硬编码宫位。
## Why：网站为什么要接这个接口
传统文化类网站、公众号小工具、命理研究平台常需要「输入生日即出命盘」的交互。手写排盘算法成本高、易错；直接调易源紫微斗数 API，你只需做表单 + 渲染，半天就能上线一个可用功能。本文给一条从输入到展示的完整链路。
## What：集成前速览
| 项目 | 内容 |
|------|------|
| 接口地址 | `https://route.showapi.com/1647-1?appKey={your_appKey}` |
| 必填参数 | `time`（阳历 `yyyy-MM-dd HH`）、`gender`（`m`/`f`） |
| 返回命盘 | `showapi_res_body.result`（含 `wx`/`pan` 等） |
| 鉴权注意 | AppKey 必须放**服务端**，前端只传用户输入 |
## How：前端表单 + 后端转发 + 渲染
### 步骤 1：前端表单（HTML）
```html
<form id="form">
<label>阳历出生时间：<input name="time" type="datetime-local" required></label>
<label>性别：
<select name="gender">
<option value="m">男</option>
<option value="f">女</option>
</select>
</label>
<button type="submit">排盘</button>
</form>
<table id="pan"></table>
```
### 步骤 2：服务端转发（Node.js 示例，AppKey 不暴露给前端）
```javascript
// 服务端：把 datetime-local 的 "1993-10-27T06:00" 转成 "1993-10-27 06"
app.post("/api/ziwei", async (req, res) => {
const time = req.body.time.replace("T", " ").slice(0, 13); // yyyy-MM-dd HH
const body = new URLSearchParams({ time, gender: req.body.gender });
const data = await (await fetch(
`https://route.showapi.com/1647-1?appKey=${process.env.SHOWAPI_APPKEY}`,
{ method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" }, body }
)).json();
const resBody = data.showapi_res_body;
if (resBody.ret_code !== 0) return res.status(400).json({ error: resBody.remark });
res.json(resBody.result);
});
```
> 用 POST 时 `datetime-local` 值是 `1993-10-27T06:00`，需把 `T` 换成空格并截到小时。GET 同理，注意空格编码为 `%20`。
### 步骤 3：前端渲染十二宫
```javascript
form.onsubmit = async (e) => {
e.preventDefault();
const fd = new FormData(form);
const r = await (await fetch("/api/ziwei", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify(Object.fromEntries(fd)),
})).json();
pan.innerHTML = r.pan.map(p => `
<tr><td>${p.palace}</td><td>${p.main.join("、")}</td>
<td>${p.bLimit}</td><td>${p.branch}</td></tr>`).join("");
};
```
## 返回示例与解析
后端拿到的 `result` 结构与 [返回字段全解](https://www.showapi.com/guides/ziwei-doushu-response-fields-1647) 一致：`wx`（五行局）、`pan`（12 宫数组，每宫 `palace`/`main`/`assist`/`twelve`/`bLimit`/`sLimit`/`branch`）。直接对 `pan` 做 `map` 渲染即可。
## 进阶 / 边界
- **AppKey 切勿进前端代码**：放服务端环境变量，前端只发用户输入，避免 key 泄露与被盗刷。
- **缓存是必选项**：相同 `(time, gender)` 命盘不变，服务端用 `key = sha256(time+gender)` 缓存（详见 [缓存策略](https://www.showapi.com/guides/ziwei-doushu-cache-cost-1647)），免费额度能撑更久。
- **字段顺序固定**：`pan` 顺序为命宫→兄弟→夫妻→子女→财帛→疾厄→迁移→仆役→事业→田宅→福德→父母，可直接按数组下标或 `palace` 字段定位。
- **合规边界**：接口定位为研究参考工具，页面应注明「传统文化研究参考，结果仅供参考」，不提供算命承诺。
## FAQ
**Q1：前端能直接调接口吗？**
A：技术上能（GET 把 AppKey 拼 URL），但会把 AppKey 暴露给用户，极易被盗刷。务必走后端转发，AppKey 留服务端。
**Q2：datetime-local 怎么转成接口要的格式？**
A：该控件值是 `1993-10-27T06:00`，把 `T` 替换为空格并截取到小时即得 `1993-10-27 06`，符合 `yyyy-MM-dd HH`。
**Q3：十二宫渲染时要不要按宫位排序？**
A：不需要。`pan` 数组已按固定十二宫顺序排列（命宫在前），直接循环渲染即可，或用 `palace` 字段做映射。
**Q4：免费额度不够用怎么办？**
A：先做缓存（同生日不重复调用），再评估是否需提升档位（见 [免费 API 档位说明](https://www.showapi.com/free-api)）。架构层见 [高并发排盘架构](https://www.showapi.com/guides/ziwei-doushu-high-concurrency-1647)。
## 相关能力 / 下一步阅读
- [紫微斗数排盘API参数指南：time 阳历格式与 gender 性别的正确传法](https://www.showapi.com/guides/ziwei-doushu-params-guide-1647)
- [紫微斗数排盘API返回字段全解：五行局、十二宫、主星一文读懂](https://www.showapi.com/guides/ziwei-doushu-response-fields-1647)
- [免费档位限制下，如何设计缓存策略节省紫微斗数排盘调用成本？](https://www.showapi.com/guides/ziwei-doushu-cache-cost-1647)
- **本系列共 12 篇**：查看[紫微斗数排盘 API 指南总目录](https://www.showapi.com/guides/ziwei-doushu-guides-1647)
