系列：《零依赖量化数据实战》｜零依赖 · 纯 GET · 不 import 任何 SDK
适用：想用 Python 把沪深个股的公司治理（高管/董事会/监事会）、分红/增发/解禁、季度利润现金流，与实时行情、五档盘口、涨跌停/集合竞价一次拉齐的量化爱好者；数据由智兔数服提供，不依赖任何行情终端。

1. 你将得到什么

• 12 个官方接口的最小可用封装，分三组：
• 公司面（8）：/hs/gs/{ljgg|ljds|ljjs|jnff|jnzf|jjxs|jdlr|jdxj}/{code} —— 历届高管 / 董事会 / 监事会、近年分红 / 增发 / 解禁、近一年季度利润 / 现金流。
• 实时盘口（2）：/hs/real/time/{code}（实时行情）、/hs/real/five/{code}（五档盘口）。
• 涨跌停与竞价（2）：/hs/lup/limit/{code}（涨跌停表现）、/hs/lup/auction/{code}（集合竞价表现），st/et/lt 控制区间与条数。
• 一个对字段名不敏感的抽取函数：季度数据按「截止日期」倒序取最新一条。

2. 端点语义表

GET https://api.zhituapi.com/hs/gs/ljgg/000001.SZ?token=你的智兔token     -> 历届高管
GET https://api.zhituapi.com/hs/gs/ljds/000001.SZ?token=你的智兔token     -> 历届董事会
GET https://api.zhituapi.com/hs/gs/ljjs/000001.SZ?token=你的智兔token     -> 历届监事会
GET https://api.zhituapi.com/hs/gs/jnff/000001.SZ?token=你的智兔token     -> 近年分红（公告日期倒序）
GET https://api.zhituapi.com/hs/gs/jnzf/000001.SZ?token=你的智兔token     -> 近年增发
GET https://api.zhituapi.com/hs/gs/jjxs/000001.SZ?token=你的智兔token     -> 解禁限售（解禁日期倒序）
GET https://api.zhituapi.com/hs/gs/jdlr/000001.SZ?token=你的智兔token     -> 近一年季度利润（截止日期倒序）
GET https://api.zhituapi.com/hs/gs/jdxj/000001.SZ?token=你的智兔token     -> 近一年季度现金流（截止日期倒序）

GET https://api.zhituapi.com/hs/real/time/000001.SZ?token=你的智兔token   -> 实时行情
GET https://api.zhituapi.com/hs/real/five/000001.SZ?token=你的智兔token   -> 实时五档盘口

GET https://api.zhituapi.com/hs/lup/limit/000001.SZ?token=你的智兔token&st=20240101&et=20241231&lt=30
  -> 涨跌停表现（仅涨跌停相关字段）
GET https://api.zhituapi.com/hs/lup/auction/000001.SZ?token=你的智兔token&st=20240101&et=20241231&lt=30
  -> 集合竞价表现

鉴权：token 走查询参数；{code} 必须带市场后缀（如 000001.SZ）；lup 的 st/et 格式 YYYYMMDD 或 YYYYMMDDhhmmss，lt 取最近 N 条。数据来自 智兔数服（www.zhituapi.com）。

3. 字段名不固定？用候选键命中

公司面返回的「公告日期」可能叫 公告日期 / date，「分红」可能叫 分红 / dividend，「截止日期」可能叫 截止日期 / end / 报告期。统一候选键命中：

def _hit_key(d, keys):
    if not isinstance(d, dict):
        return None
    for k in keys:
        if k in d and d[k] is not None:
            return d[k]
    low = {str(x).lower(): x for x in d.keys()}
    for k in keys:
        kl = k.lower()
        if kl in low:
            return d[low[kl]]
    return None

4. 核心模板函数

import sys, requests

BASE = "https://api.zhituapi.com"
TOKEN = "你的智兔token"  # 占位，换成你申请的真实 token

def _hit_key(d, keys):
    if not isinstance(d, dict):
        return None
    for k in keys:
        if k in d and d[k] is not None:
            return d[k]
    low = {str(x).lower(): x for x in d.keys()}
    for k in keys:
        kl = k.lower()
        if kl in low:
            return d[low[kl]]
    return None

def _to_float(v):
    try:
        return None if v is None else float(v)
    except (TypeError, ValueError):
        return None

def _get(path, params=None):
    p = dict(params or {})
    p["token"] = TOKEN
    try:
        r = requests.get(f"{BASE}{path}", params=p, timeout=10)
    except Exception as e:
        return None, f"网络异常：{e}"
    if r.status_code != 200:
        return None, f"{r.status_code} {r.text.strip()[:140]}"
    try:
        return r.json(), None
    except Exception:
        return None, f"非 JSON：{r.text.strip()[:140]}"

# 公司治理 / 分红 / 增发 / 解禁 / 季度利润现金流（8 个）
def fetch_gs(kind, code="000001.SZ"):
    return _get(f"/hs/gs/{kind}/{code}")

# 实时行情 / 五档盘口（2 个）
def fetch_realtime(kind, code="000001.SZ"):
    return _get(f"/hs/real/{kind}/{code}")

# 涨跌停 / 集合竞价（2 个，st/et/lt 查询参数）
def fetch_lup(kind, code="000001.SZ", st="20240101", et="20241231", lt=30):
    return _get(f"/hs/lup/{kind}/{code}", {"st": st, "et": et, "lt": lt})

def latest_quarter(rows):
    """季度利润/现金流：按截止日期倒序取首条，候选键命中。"""
    if not isinstance(rows, list) or not rows:
        return None
    def sc(x):
        return str(_hit_key(x, ["截止日期", "end", "date", "报告期"]) or "")
    rows = sorted(rows, key=sc, reverse=True)
    return rows[0]

def selftest():
    # 合成数据仅逻辑自验，非真实行情
    dividends = [
        {"公告日期": "2024-06-01", "分红": 10.0},
        {"date": "2024-08-01", "dividend": 20.0},
    ]
    d = sorted(dividends, key=lambda x: str(_hit_key(x, ["公告日期", "date"]) or ""), reverse=True)
    assert _to_float(_hit_key(d[0], ["分红", "dividend"])) == 20.0
    q = latest_quarter([
        {"截止日期": "2024-03-31", "利润": 1.0},
        {"end": "2024-06-30", "profit": 2.0},
    ])
    assert _to_float(_hit_key(q, ["利润", "profit"])) == 2.0
    five = {"bp1": 9.8, "sp1": 10.2}
    assert _to_float(_hit_key(five, ["bp1", "买一", "buy1"])) == 9.8
    assert _to_float(_hit_key(five, ["sp1", "卖一", "sell1"])) == 10.2
    print("selftest PASS")

if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] == "--selftest":
        selftest()
    else:
        for kind in ("ljgg", "ljds", "ljjs", "jnff", "jnzf", "jjxs", "jdlr", "jdxj"):
            print(f"gs.{kind} ->", fetch_gs(kind))
        for kind in ("time", "five"):
            print(f"real.{kind} ->", fetch_realtime(kind))
        for kind in ("limit", "auction"):
            print(f"lup.{kind} ->", fetch_lup(kind))

5. 代码自验结果

离线 selftest（合成数据，仅验证逻辑，不含任何真实行情）：

selftest PASS

联网实测（占位 token，真实返回）：

--- 联网实测（占位 token，预期 404 102:Licence证书不存在）---
gs.ljgg -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.ljds -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.ljjs -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.jnff -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.jnzf -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.jjxs -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.jdlr -> (None, '404 102:Licence证书(你的智兔token)不存在')
gs.jdxj -> (None, '404 102:Licence证书(你的智兔token)不存在')
real.time -> (None, '404 102:Licence证书(你的智兔token)不存在')
real.five -> (None, '404 102:Licence证书(你的智兔token)不存在')
lup.limit -> (None, '404 102:Licence证书(你的智兔token)不存在')
lup.auction -> (None, '404 102:Licence证书(你的智兔token)不存在')

把 TOKEN = "你的智兔token" 换成你申请的真实 token，上述函数即可打印沪深公司面数据。本文未编造任何真实数值。

6. 坑与注意事项

1. 102 不代表路径对：404 102 是「证书不存在」（鉴权先于路由），路径合法与否要靠客户端白名单自查。
2. 代码必须带市场后缀：写 000001 会路由错误，必须 000001.SZ / 600000.SH。
3. 公司面字段名中英文混用：「公告日期」可能是 公告日期/date，「分红」可能是 分红/dividend，务必候选键命中。
4. 季度数据取最新一条：jdlr/jdxj 返回多期，按「截止日期」倒序取首条才是最近季度；字段名可能是 截止日期/end/报告期。
5. lup 是盘后更新：涨跌停/集合竞价数据交易日盘后更新，非交易时段取不到当日数据。

7. 小结与下篇预告

本篇把「沪深公司治理 + 分红/增发/解禁 + 季度利润现金流 + 实时盘口 + 涨跌停/竞价」拧成了 12 个零依赖接口的最小封装，重点解决了代码带市场后缀、公司面字段名中英文混用、季度数据取最新一条三个坑，配候选键命中即可一行出公司面快照。

下一篇计划写 #28《沪深A股市场指标与资金流向》：讲解如何用官方接口拉取沪深A股的市场指标（连续涨跌、涨跌幅排名、流通市值、市盈率、市净率、ROE）与资金流向（行业/板块/个股净流入、主力连续流入）数据。

8. 免责声明

本文仅演示公开数据接口的用法，所有代码示例均以占位 token 自验，未含任何真实数据；文中合成数据仅为逻辑自验用途，不构成投资建议，亦不承诺收益。

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

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

把代码里的 你的智兔token 换成你拿到的真实 token，上面的脚本就能直接打印沪深公司面数据。