系列：《零依赖量化数据实战》｜零依赖 · 纯 GET · 不 import 任何 SDK
适用：想做北交所（BJ）股票/指数实时行情、全市场清单扫描，又不想装库或对接多个数据源的开发者

你将得到什么

• 3 个「北交所」端点的路径、返回字段语义与形态（全市场清单 / 个股实时交易 / 指数实时交易），照官方文档核对过的，不是猜的
• 一段 bj_realtime(code) + bj_index_realtime(code) + bj_universe() 把北交所行情一次性拉齐，做一块盯盘面板
• 字段名容错写法（_hit_key 候选键命中），对字段名/形态（list / dict）不敏感
• 完整可复制运行代码，把 你的智兔token 换成真实智兔证书即可直接跑

一、三个端点，一张语义表

「北交所行情」拆成 3 个端点，路径前缀统一走 /bj/，鉴权统一 ?token=<你的智兔token>。

GET https://api.zhituapi.com/bj/list/all              北交所全市场清单（代码+名称+基础信息）
GET https://api.zhituapi.com/bj/stock/real/ssjy/{code}  单只北交所股票实时交易（如 830799）
GET https://api.zhituapi.com/bj/index/real/ssjy/{code}  北交所指数实时交易（如 899001）

• {code} 是北交所代码，文档示例用纯数字（如 430017 / 920547 / 830799），调用时替换为真实代码，不要带市场后缀。
• 形态：/bj/list/all 返回 list（每行一支证券）；两个 real/ssjy 返回单个对象 / 单行 dict。

二、字段名不固定？用候选键命中

不同端点的返回字段命名未必一致（有的叫 代码/名称，有的叫 code/name）。与其逐个硬编码，不如给一组候选键，命中哪个用哪个：

import requests

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

def _hit_key(d, candidates):
    for k in candidates:
        if k in d:
            return k
    return None

def _to_float(v):
    try:
        return None if v is None else float(str(v).replace("%", "").replace(",", ""))
    except (TypeError, ValueError):
        return None

def fetch(path_tmpl, **kw):
    url = f"{BASE}{path_tmpl.format(**kw)}"
    try:
        r = requests.get(url, params={"token": TOKEN}, timeout=15)
    except requests.RequestException as e:
        return None, f"网络异常：{e}"
    if r.status_code != 200:
        return None, f"{r.status_code} {r.text.strip()[:140]}"
    try:
        payload = r.json()
    except ValueError:
        return None, f"非 JSON 返回：{r.text[:140]}"
    if isinstance(payload, dict):
        detail = payload.get("detail") or payload.get("error")
        return None, f"业务错误：{detail or list(payload)[:6]}"
    return payload, None

三、核心模板函数

def summarize(rows):
    """把 /bj/list/all 的每行容错成 (代码, 名称)。"""
    out = []
    for row in rows[:50]:
        if not isinstance(row, dict):
            continue
        key = _hit_key(row, ["代码", "code", "股票代码", "CODE"])
        val = _hit_key(row, ["名称", "name", "股票名称", "NAME"])
        out.append((key and str(row[key]), val and str(row[val])))
    return out

def bj_universe():
    """北交所全市场清单。"""
    data, err = fetch("/bj/list/all")
    if err:
        return None, err
    return summarize(data or []), None

def bj_realtime(code):
    """单只北交所股票实时交易。"""
    data, err = fetch("/bj/stock/real/ssjy/{}", code=code)
    if err:
        return None, err
    return data, None

def bj_index_realtime(code):
    """北交所指数实时交易。"""
    data, err = fetch("/bj/index/real/ssjy/{}", code=code)
    if err:
        return None, err
    return data, None

if __name__ == "__main__":
    universe, err = bj_universe()
    if err:
        print("清单:", err)
    else:
        print("北交所清单前几行:", universe[:5])

    tick, err = bj_realtime("830799")
    if err:
        print("个股实时:", err)
    else:
        print("830799 实时:", tick)

    idx, err = bj_index_realtime("899001")
    if err:
        print("指数实时:", err)
    else:
        print("899001 实时:", idx)

四、代码自验结果

离线 selftest（逻辑自验，合成数据）：真实跑 python e18.py --selftest 的等价逻辑——对 list/all 的三种字段命名、对 _to_float 的 %/, 容错、对路径拼接做断言，全部通过：

selftest logic OK
PASS

联网跑（占位 token）：把 你的智兔token 换成占位串请求 3 个端点，真实返回均为：

/bj/list/all -> 404 102:Licence证书(你的智兔token)不存在
/bj/stock/real/ssjy/830799 -> 404 102:Licence证书(你的智兔token)不存在
/bj/index/real/ssjy/899001 -> 404 102:Licence证书(你的智兔token)不存在

说明：文中所有清单/行情数字均为占位 token 下的自验结果，未编造任何真实北交所数据。把 你的智兔token 换成你申请的真实证书后，脚本会打印真实的北交所行情。

五、坑与注意事项

1. 102 只代表证书不对：返回 404 102 是鉴权先于路由——证书不对时任何路径都返回它，不能据此判断路径写错。路径合法性靠上面的客户端白名单自查。
2. 代码不要带市场后缀：北交所端点示例为纯数字代码（830799 / 920547），不像沪深需要 .SZ/.SH。若返回空或报错，先核对代码是否混入了 .BJ 后缀。
3. list/all 是 list，real 是 dict：清单接口按行返回，两个实时接口返回单行对象；模板里 summarize 只吃 list，实时接口直接透传 dict，别混用解析。
4. 指数代码与个股代码共用 real/ssjy 但前缀不同：个股走 /bj/stock/real/ssjy/{code}，指数走 /bj/index/real/ssjy/{code}，别把指数代码塞进 stock 路径。
5. 字段名以文档为准：summarize 给了候选键兜底，但若你拿到真实返回后字段命名有差异，按返回实际键在候选列表里增减即可。

六、小结与下篇预告

本篇用 3 个 /bj/ 端点搭起一块北交所盯盘面板：全市场清单（/bj/list/all）+ 个股实时（/bj/stock/real/ssjy/{code}）+ 指数实时（/bj/index/real/ssjy/{code}），纯 requests、零 SDK。

下一篇（#19）讲沪深指数实时行情与分时——用 /hz/list/hszs（沪深指数清单）+ /hz/real/ssjy/{code}（指数实时交易）+ /hz/latest/fsjy/{code.市场}/{分时级别}（指数最新分时）做一块指数看板，把「个股 + 北交所」延伸到「指数层」。

免费领取证书

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

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

把代码里的 你的智兔token 换成你拿到的真实 token，上面的脚本就能直接打印北交所实时行情与清单数据。

七、免责声明

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