API 接入

写脚本、接自己的系统、接自动化工具的人看这一页。只用网页可以跳过。

先拿一个 Token

到账户中心的 API Token 一节创建：填个名称、选权限（只读 / 读写）、填有效天数（留空 = 永久）。

明文只显示一次

创建成功后立刻复制保存。离开或刷新页面就再也看不到了，丢了只能吊销重建。

Token 形如 wm_ 开头的一串。

档位	能建几个	权限
免费	0	—
BASIC	1	只读
PRO	5	只读 + 读写
ULTRA	不限	只读 + 读写

怎么带

放在请求头里：

Authorization: Bearer wm_你的token

bash

curl -H "Authorization: Bearer wm_你的token" \
     "https://你的站点地址/api/v1/deposits/search?bank_name=××银行&limit=20"

Token 只能访问接口，不能当登录用

拿 Token 去打开网页是不行的，它只对 /api/ 开头的路径有效。

能调什么

用途	路径
查报价	`/api/v1/deposits/search`、`/api/v1/deposits/stats`
查需求（SKU）	`/api/v1/sku/search`、`/api/v1/sku/{sku_hash}/bills`
推荐	`/api/v1/recommend-bills/query`、`/stats`、`/score`、`/allocate`
看板数据	`/api/v1/dashboard/...`
指标查询 PRO	`/api/v1/semantic-layer/...`
管理自己的 Token	`/api/v1/tokens`

完整的参数说明在 /docs，用 Token 也能打开。

网页上能筛的，接口上基本也能筛

/api/v1/deposits/search 的查询参数和存单查询页的筛选项是对应的：bank_name、amount_min、amount_max、date_from、date_to、deposit_method、product_type、customer_type、term_days_min、term_days_max、order_by、order。

最省事的办法：在网页上把筛选调对，点复制筛选链接，把地址栏里的参数照搬到接口调用上。

返回的数据同样按档位来

接口不是绕过档位限制的后门。网页上被脱敏的字段，接口返回里同样被处理：

sender 在免费档和 BASIC 返回 张*** 这种形式
raw_line 在这两档返回 null（字段还在，值是空的，别以为是数据缺失）
时间范围、翻页上限、SKU 报价深度，和网页上完全一致

详见不同档位能看到什么。

限流和配额

两道限制，性质不同：

每分钟请求上限

免费	BASIC	PRO	ULTRA
30 次	60 次	120 次	300 次

超了返回 429。退避重试即可，别原地打转硬撞。

每日配额

只对推荐类接口计数：

免费	BASIC	PRO	ULTRA
5 次	50 次	500 次	5000 次

配额是按人算的，不是按 Token 算的

你名下所有 Token 的调用合并计数。建五个 Token 不会让配额变成五倍。

调用推荐类接口时，响应头里会带上剩余量，照着它控制节奏：

X-Quota-Limit: 5000
X-Quota-Remaining: 4873
X-Quota-Reset: 2026-09-14T00:00:00+08:00

每天零点重置。

错误怎么读

出错时返回体是这个形状：

json

{
  "detail": {
    "error": "tier_required",
    "tier": "basic",
    "message": "该功能需要 Pro 及以上档位"
  }
}

error 以 tier_ 开头的，都是档位或配额问题，不是你的参数写错了：

error	意思
`tier_required`	当前档位不够
`tier_paid_required`	需要付费状态（试用不算）
`tier_daily_quota_exceeded`	今日配额用完，等次日零点
`tier_rate_limit_exceeded`	每分钟请求超限，退避重试

写客户端时建议这么判

统一检查 detail.error 是不是以 tier_ 开头。是的话就不用重试参数，直接报给使用者看 message。

几条建议

时间参数写成 YYYY-MM-DD，所有时间都是北京时间
分页别一次拉太大，limit 给 50–100 比较稳
Token 别写进代码仓库，走环境变量
长期不用的 Token 吊销掉，账户中心能看到每个 Token 的「最后使用」时间

API 接入 ​

先拿一个 Token ​

怎么带 ​

能调什么 ​

返回的数据同样按档位来 ​

限流和配额 ​

每分钟请求上限 ​

每日配额 ​

错误怎么读 ​

几条建议 ​