系列：《跨市场数据实战》｜连载项目 · 纯 GET 取数 · 仅依赖 requests
适用：想做「港股通杠杆资金监控 / 某只标的两融加减速」、但被 /hitc 七个端点绕晕的读者；数据由智兔数服提供。本篇给 /hitc（今日交易提示、融资融券总量、融资融券明细、大宗交易、解禁限售、打新收益、历史分红）共 7 个端点的分组地图、一套字段容错归一化代码、以及一个把「两融总量变动」和「单标的两融明细」叠在一起的实战模板，全部只依赖 requests，所有示例均为演示数据，不构成收益承诺。

1. 你将得到什么

读完这一篇，你能拿走四样东西：

1. 一张分组地图：/hitc 7 个端点，知道「今日提示 / 两融总量 / 两融明细 / 大宗交易 / 解禁限售 / 打新收益 / 历史分红」分别敲哪个门；
2. 一套字段容错代码：两融明细字段名分散，_hit_key + _to_float 带候选键兜底；
3. 一个追踪模板：用 trace_margin 把「全市场两融概览」和「某只标的两融明细」一次性拉出来，看杠杆是加还是减；
4. 五个真实踩坑点，尤其是「两融数据 T+1 才出」这个节奏陷阱。

代码全部自包含，复制进 .py 直接能跑，不依赖 numpy / pandas。

2. 本篇取数约定

• 全部接口都是 GET + query 参数，token 放在查询串里（?token=xxx），不放 header；
• 统一基址 https://api.zhituapi.com；
• 代码块里的 你的智兔token 是占位符，换成你的 token 即可；
• /hitc/* 七个端点均不带路径参数，日期类维度由上游按「上一个交易日」或「前后 15 天」窗口返回；
• 所有接口路径均取自官方文档。
• 数据来自 智兔数服（www.zhituapi.com）：零 SDK、纯 GET、免费版即可起步。

3. 7 个端点一组看

注意：rzrqzl / rzrqmx / dzjy 三个都有「上一交易日」的节奏——当天的数据要第二天才出，别在盘中调这几个端点当实时数据用。

4. 核心模板函数

import requests, time

BASE = "https://api.zhituapi.com"
TOKEN = "你的智兔token"

# ---------- 1. 字段容错与类型归一 ----------
def _hit_key(d, *cands, default=None):
    if not isinstance(d, dict):
        return default
    for c in cands:
        if c in d and d[c] not in (None, "", "-", "null"):
            return d[c]
    low = {str(k).lower(): v for k, v in d.items()}
    for c in cands:
        v = low.get(str(c).lower())
        if v not in (None, "", "-", "null"):
            return v
    return default


def _to_float(v, default=None):
    try:
        if v in (None, "", "-", "null", "None"):
            return default
        return float(v)
    except (TypeError, ValueError):
        return default


# ---------- 2. 统一请求 ----------
def _get(path, params=None, timeout=10, retries=2, backoff=0.6, default=None):
    q = {"token": TOKEN}
    if params:
        q.update(params)
    last = ""
    for i in range(retries + 1):
        try:
            r = requests.get(BASE + path, params=q, timeout=timeout)
            if r.status_code == 200:
                try:
                    return r.json()
                except ValueError:
                    return default
            last = "HTTP %s %s" % (r.status_code, (r.text or "").strip()[:80])
        except Exception as e:
            last = "%s: %s" % (type(e).__name__, e)
        if i < retries:
            time.sleep(backoff * (i + 1))
    return {"_error": last}


# ---------- 3. 两融明细归一 ----------
def norm_margin(rows):
    out = []
    for r in rows or []:
        out.append({
            "代码":     _hit_key(r, "dm", "code", default="-"),
            "名称":     _hit_key(r, "mc", "name", default="-"),
            "融资余额":  _to_float(_hit_key(r, "rzye", "融资余额", "rzmre")),
            "融券余额":  _to_float(_hit_key(r, "rqye", "融券余额")),
            "融券卖出量": _to_float(_hit_key(r, "rqmcl", "融券卖出量")),
        })
    return out


# ---------- 4. 取数封装 ----------
def fetch_jrts():   return _get("/hitc/jrts", default=[])
def fetch_rzrqzl(): return _get("/hitc/rzrqzl", default=[])
def fetch_rzrqmx(): return _get("/hitc/rzrqmx", default=[])
def fetch_dzjy():   return _get("/hitc/dzjy", default=[])
def fetch_jjxs():   return _get("/hitc/jjxs", default=[])
def fetch_dxsy():   return _get("/hitc/dxsy", default=[])
def fetch_lsfh():   return _get("/hitc/lsfh", default=[])


# ---------- 5. 实战：追踪某只标的两融加减速 ----------
def trace_margin(code="00700"):
    """全市场两融概览 + 该标的两融明细"""
    zl = fetch_rzrqzl()
    mx = norm_margin(fetch_rzrqmx())
    hit = [r for r in mx if str(r["代码"]).upper() == str(code).upper()]
    return {"全市场两融概览": zl, "该标的明细": hit}


# ---------- 6. 校验 ----------
def run_check():
    global fetch_rzrqmx
    assert _hit_key({"DM": "00700", "mc": "腾讯"}, "dm") == "00700"
    assert _to_float("-") is None and _to_float("3.2") == 3.2

    fake_mx = [{"dm": "00700", "mc": "腾讯", "rzye": "120.5", "rqye": "1.2"},
               {"dm": "09988", "mc": "阿里", "rzye": "80.0", "rqye": "2.5"}]
    nm = norm_margin(fake_mx)
    assert nm[0]["代码"] == "00700" and nm[0]["融资余额"] == 120.5

    # 无网环境：用假数据模拟 trace_margin 过滤
    def _fake_mx():
        return fake_mx
    _orig = fetch_rzrqmx
    fetch_rzrqmx = _fake_mx
    tr = trace_margin("00700")
    fetch_rzrqmx = _orig
    assert tr["该标的明细"][0]["名称"] == "腾讯"

    print("校验通过")


if __name__ == "__main__":
    run_check()
    print("-" * 62)
    for name, path in [("今日交易提示", "/hitc/jrts"),
                       ("融资融券总量", "/hitc/rzrqzl"),
                       ("融资融券明细", "/hitc/rzrqmx"),
                       ("大宗交易", "/hitc/dzjy"),
                       ("解禁限售", "/hitc/jjxs"),
                       ("打新收益", "/hitc/dxsy"),
                       ("历史分红", "/hitc/lsfh")]:
        data = _get(path, default=[])
        if isinstance(data, dict) and "_error" in data:
            print("%-10s %-16s -> %s" % (name, path, data["_error"][:52]))
        else:
            print("%-10s %-16s -> %d 条" % (name, path, len(data)))

5. 跑通示例

把上面的代码复制到本地，填入你的 token 即可直接运行：它会请求对应接口、拉取真实数据，并输出归一化后的结构化字典（各字段含义见前文各小节）。

6. 坑与注意事项

坑 1：rzrqzl / rzrqmx / dzjy 都是 T+1，不是盘中实时。
这三个端点返回的是「上一个交易日」的数据，当天数据要第二天才出。盘中调它们看到的是昨天的两融，别当成实时杠杆信号。

坑 2：rzrqmx 是全市场明细列表，单标的要自己过滤。
它不接收某个股票代码参数，返回所有股票的两融明细；trace_margin 在本地按代码（大小写不敏感）过滤。_hit_key 的候选键覆盖 dm/code，过滤前先确认上游返回的是哪种键名。

坑 3：rzrqzl 与 rzrqmx 口径不同。
zl 是两市两融概览（一条汇总），mx 是逐股明细（多条）；想看单标的必须把 mx 过滤出来，zl 给不出个股权细。

坑 4：jjxs（解禁限售）是前后 15 天窗口。
它覆盖「当前交易日前后约 15 天」已/将解禁，不是某一天全部解禁；做减持压力测算时按窗口取数，别误当全量。

坑 5：dxsy（打新收益）是近四年汇总。
它返回的是近几年（约四年）打新收益数据，时间跨度大，做年度对比要自行按年份拆分，别直接首尾相减当「今年收益」。

7. 小结与下篇预告

本篇把 /hitc 7 个端点打通，给出 norm_margin（两融明细归一）与 trace_margin（全市场概览 + 单标的两融明细）两个核心函数。两融数据 T+1 才出、明细需本地按代码过滤、解禁/打新是窗口汇总，是这套杠杆资金接口最容易踩错的地方。

下一篇计划写 #07《港股资金流与板块轮动：13个接口定位主力去向》：用 /higg（个股资金流，6）+ /hizj（资金路线图，5）+ /hibk（港股通板块，2）定位当日主力净流入最高的板块与个股，输出板块轮动热力。

8. 免责声明

本文仅演示港股通两融类接口的取数与归一化方法，所有代码示例均为演示数据，未含任何真实两融数值，不构成投资建议，亦不承诺收益。

免费领取证书
数据来自 智兔数服（www.zhituapi.com）：零 SDK、纯 GET、免费版即可起步。

领取路径：进入 www.zhituapi.com → 点击「请求证书」→「证书获取」→「免费版」（邮箱验证 3 步即可拿到 token）。

把代码里的 你的智兔token 换成你拿到的真实 token，上面的脚本就能直接打印某只港股通标的两融明细与全市场两融概览。