国自然基金数据洞察(订阅版)
- 订阅价:¥49.00/月(平台按月结算,30 天为一个周期)
- 服务入口:
POST https://nsfc.keyandog.com/nsfc/sub/invoke(JSON,请求体带action;也可按动作.../sub/invoke/<action>) - 免费试算:
POST https://nsfc.keyandog.com/nsfc/preview(每 IP 每日 5 次)
> 订阅通道与按量付费通道完全分离:订阅走 /nsfc/sub/invoke(只认订阅凭证),
> 按量付费走 /nsfc/invoke(402 支付)。两者入口、鉴权、状态互不影响。
能力清单(订阅期内不限单个能力,按 units 计量)
| action | 能力 | 主要入参 | units |
|---|---|---|---|
search |
项目检索 | query/org/person/type/code/years/page/size |
1 |
code_map |
申请代码检索 | text 或 code |
1 |
aggregate |
分组统计 | dim(year|dept|org|type|code)+公共参数 |
2 |
keyword_trend |
关键词热度 | keywords(数组或逗号分隔,≤5)+years |
2 |
scholar |
学者画像 | name(必填)+org(消歧)+years |
2 |
org_profile |
单位画像 | org(必填)+years |
3 |
clash_check |
选题撞车检测 | query(选题描述 8-30 字)+years+可选 org/type/code |
5 |
proposal_evidence |
标书素材包 | 同 clash_check |
8 |
topic_landscape |
领域全景 | 同 clash_check |
8 |
调用方式
请求头携带订阅凭证(购买后由平台/商家下发):
curl -s -X POST 'https://nsfc.keyandog.com/nsfc/sub/invoke' \
-H 'Content-Type: application/json' \
-H 'X-Fund-Key: <订阅凭证>' \
-d '{"action":"clash_check","query":"城市热岛遥感反演","years":[2019,2023]}'
订阅入口不返回 402;不带凭证调用返回 401 SUBSCRIPTION_KEY_REQUIRED。
若确需按次计费(另一平台商品),使用按量付费入口 POST https://nsfc.keyandog.com/nsfc/invoke:
未付款返回 HTTP 402 + Payment-Needed 账单,买家侧用 alipay-bot 402-buyer-pay
支付后携 Payment-Proof 重试同一请求;订单幂等,重复请求返回 Idempotent-Replay: true。
商家侧支付与履约(供核验):服务端已实现 402 协议、
alipay.aipay.agent.payment.verify 验付与 alipay.aipay.agent.fulfillment.confirm 履约确认;
验付会校验 active、out_trade_no、金额与 resource_id,交付响应含非空 resource_id/content
并返回 Payment-Validation 回执头;履约确认成功后才标记订单完成。
返回内容与展示规则
result(结构化结论)、evidence(命中数/样例项目号/年份)、agent_context(可直接使用的中文要点)、
confidence、usage(units 与实际单价)、disclaimer。
结论优先、给数字与样例项目号;单次最多 50 条记录,不输出整批原始清单;命中过少时说明样本不足;
不承诺评审结果,保留 disclaimer。
订阅凭证与配额
订阅期内的每次调用都按能力计量 units(见上表),响应头回传余量,便于向用户展示:
X-Quota-Plan / X-Quota-Status / X-Quota-Limit / X-Quota-Used
X-Quota-Remaining / X-Quota-Reset(本周期到期时间)
| 情况 | HTTP | code | 处理 |
|---|---|---|---|
| 凭证无效 | 401 | INVALID_KEY |
提示凭证无效,去掉 X-Fund-Key 改走按次付费 |
| 订阅到期(平台不支持自动续费) | 403 | SUBSCRIPTION_EXPIRED |
提示续订;或改走按次付费 |
| 凭证被停用 | 403 | SUBSCRIPTION_DISABLED |
联系商家;或改走按次付费 |
| 本周期配额用完 | 429 | QUOTA_EXCEEDED |
告知 X-Quota-Reset 恢复时间;或改走按次付费(带 Retry-After) |
配额用完/到期时不要重复重试同一请求;参数错误与服务异常不消耗配额。
错误码
| HTTP | code | 处理 |
|---|---|---|
| 401 | INVALID_KEY |
订阅凭证无效,改用按次付费或联系商家 |
| 402 | PAYMENT_REQUIRED |
未带凭证,按 402 账单支付后重试(按次付费路径) |
| 403 | SUBSCRIPTION_EXPIRED / SUBSCRIPTION_DISABLED |
续订或改用按次付费 |
| 422 | bad_request |
参数错误(不计费、不消耗配额) |
| 429 | QUOTA_EXCEEDED |
本周期配额用完,按 X-Quota-Reset 恢复 |
| 429 | preview_quota_exhausted |
免费试算当日用完 |
| 503 | service_unavailable |
服务繁忙,本次不计费 |
参考文件
| 文件 | 内容 |
|---|---|
references/actions.md |
全部能力入参与返回字段 |
references/billing-compliance.md |
计费、幂等、订阅 Key、合规红线 |
