对外 API
独立命名空间 /open/v1,面向小程序、外部合作方与其他系统的只读接口。
版本 v0.1(草案):已实现并上线 4 个只读端点,测试通过。本文只写对外承诺的接口;站内内部契约不是对外接口,两者不要混用。
一、定位与边界
- 对外只开只读能力:字典归一、字典查询、候选人评分查询、需求匹配查询。
- 写操作(改分、推进阶段、录访谈、发起匹配)不对外,走内部系统或人工。
- 对外接口走独立命名空间
/open/v1,与站内/api分开:后者用浏览器会话 Cookie,前者用 API Key。
二、认证
请求头携带 Bearer 形式的 API Key:
Authorization: Bearer tk_live_xxxxxxxx
- Key 绑定一个服务身份与一组 scope(对应内部权限点,只读子集)。
- 缺少 scope 返回
403 {code:"forbidden"};Key 无效或过期返回401 {code:"invalid_key"}。 - 联系方式等敏感字段默认脱敏;需要原文须单独申请
candidates:view_contactscope。 - Key 只存哈希;明文只在签发时显示一次。
三、统一返回信封
所有成功响应遵循同一外层结构:
{
"data": { },
"meta": { "schema_version": "1.0", "summary": "可选的人类可读摘要" },
"page": { "total": 120, "next_token": "..." },
"evidence": [ { "quote": "...", "source": "..." } ],
"next_actions": [],
"warnings": []
}
错误响应:
{ "code": "invalid_body", "message": "参数错误", "field_errors": [ { "field": "kind", "message": "必填" } ], "hint": "kind 取 school/company/position/city" }
四、v1 只读端点(4 条)
4.1 字段归一
POST /open/v1/resolve
{ "kind": "school", "text": "北林" }
返回 data:{status, confidence, code, label, alternatives[], source}。
status 取值为 resolved / ambiguous / pending / non_entity。
ambiguous 时 alternatives 给候选,由调用方选择,不自动拍板。
4.2 字典查询
GET /open/v1/dict/{type}?q=&page_token=&limit=
type:schools / companies / positions / industries / cities / skills- 返回
items[](code、label、关键属性)与page.total - 只返回启用中的条目;不做分页外全量导出
4.3 候选人评分查询
GET /open/v1/candidates/{id}/score
返回最新一条已发布评分:final_score、tier、primary_type、directions、review_reasons。
不含原始简历、联系方式、访谈全文;评分是 AI 产物,人工校准后以校准值为准。
4.4 需求匹配查询
GET /open/v1/demands/{id}/matches?limit=
返回预匹配队列:candidate_id、脱敏姓名、score、band、coverage、why_like[]。
只读已生成的预匹配结果,不触发重算。信息不足时 band=insufficient,如实返回,不假报分数。
五、分页、限流与幂等
- 分页:统一
page_token/next_token,不使用 offset 深翻。 - 限流:按 Key 每分钟请求数与并发上限;超限
429 {code:"rate_limited", hint:"retry_after_seconds"}。 - 幂等:只读接口天然幂等;若后续开写接口,必须带
Idempotency-Key。
六、版本与兼容
- 路径带版本
/open/v1;新增字段不升版,删除或改语义升/open/v2。 - 弃用提前 30 天在响应头
Deprecation/Sunset标注。 - 契约为唯一事实源:OpenAPI 由代码契约生成,不手写第二份。
七、错误码
| code | HTTP | 含义 |
|---|---|---|
invalid_key | 401 | Key 无效或过期 |
forbidden | 403 | 缺少 scope |
invalid_body | 400 | 参数缺失或类型错(带 field_errors) |
not_found | 404 | 资源不存在或无权查看 |
rate_limited | 429 | 超过配额 |
internal | 500 | 服务内部错误 |
八、签发与调用
在服务器(或能连 TALENT_DATABASE_URL 的机器)签发,明文只显示一次:
# 签发与查看(明文只显示一次)
OPEN_API_DSN='postgres://...' openkey issue --name 小程序只读 --scopes dict:view,candidates:view,clients:view
openkey list
openkey disable --id 3
调用示例:
curl -s https://talent.founduai.com/open/v1/dict/schools?limit=2 \
-H "Authorization: Bearer tk_xxx"
curl -s -X POST https://talent.founduai.com/open/v1/resolve \
-H "Authorization: Bearer tk_xxx" -H 'Content-Type: application/json' \
-d '{"kind":"school","text":"北京林业大学"}'
curl -s https://talent.founduai.com/open/v1/candidates/1/score -H "Authorization: Bearer tk_xxx"
curl -s https://talent.founduai.com/open/v1/demands/1/matches -H "Authorization: Bearer tk_xxx"
九、落地路径(实现侧)
- 契约层增加
Surfaces标记:http / cli / mcp / agent / external,只把external的条目投影到/open/v1。 - 新增 API Key 表与中间件:Key → scope 集合 → 复用现有
auth.RequirePoint。 - 新增
internal/openapi生成器:从契约导出 OpenAPI 3.1,人读文档由它派生,避免漂移。 - 先只读 4 条上线;写接口按需再评。
十、已定决策
- Key 由管理侧用
openkey签发,明文只返回一次,库里只存 sha256。 - 小程序 v1 只读;写操作不进对外面。
- 配额按 Key 每分钟,默认 120,可由
OPENV1_RATE_PER_MIN调整。 - 批量查询(按 id 列表取评分)后置到 v1.1。