4. 评分API接口定义：请求参数与响应结构
信用评分API的接口定义是系统对外服务的契约。本节将详细定义请求参数（用户ID、特征向量）与响应结构（评分、等级、拒绝原因），确保前后端及第三方调用方能够基于统一规范进行集成。
4.1 接口概览
| 属性 | 值 |
|---|---|
| 接口名称 | 信用评分查询 |
| HTTP方法 | POST |
| 端点路径 | /api/v1/credit/score |
| 数据格式 | JSON (UTF-8) |
| 认证方式 | API Key (Header: X-API-Key) |
4.2 请求参数定义
请求体采用JSON对象，包含两个必填字段：user_id 和 feature_vector。
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
user_id |
string | 是 | 用户在系统中的唯一标识符，长度 8-32 字符 | "USR20250321001" |
feature_vector |
array of number | 是 | 包含 12 个数值的特征向量，顺序固定，缺失值以 -1 填充 | [0.85, 0.92, 0.45, ...] |
特征向量说明：特征向量由上游特征工程模块生成，包含收入水平、历史还款率、负债比率、信用历史长度、近期查询次数等12个标准化特征。调用方需确保向量长度严格为12，且数值范围在 [-1, 1] 之间。
请求示例
{
"user_id": "USR20250321001",
"feature_vector": [0.85, 0.92, 0.45, 0.30, 0.78, 0.12, 0.65, 0.40, 0.55, 0.88, 0.22, 0.70]
}4.3 响应结构定义
响应体包含三个核心字段：score（评分）、grade（等级）、rejection_reason（拒绝原因）。
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
score |
integer | 是 | 信用评分，范围 300-850 | 720 |
grade |
string | 是 | 信用等级：AAA / AA / A / BBB / BB / B / C / D | "A" |
rejection_reason |
string | null | 否 | 当评分低于阈值时返回拒绝原因，否则为 null | "收入稳定性不足" |
评分等级对照表
| 评分区间 | 等级 | 风险描述 | 建议操作 |
|---|---|---|---|
| 800 - 850 | AAA | 极低风险 | 自动通过，额度优先 |
| 750 - 799 | AA | 低风险 | 自动通过 |
| 700 - 749 | A | 较低风险 | 自动通过 |
| 650 - 699 | BBB | 中等风险 | 人工复核 |
| 600 - 649 | BB | 较高风险 | 人工复核，建议降额 |
| 500 - 599 | B | 高风险 | 建议拒绝 |
| 400 - 499 | C | 很高风险 | 拒绝 |
| 300 - 399 | D | 极高风险 | 拒绝，标记黑名单 |
响应示例（通过）
{
"score": 720,
"grade": "A",
"rejection_reason": null
}响应示例（拒绝）
{
"score": 480,
"grade": "C",
"rejection_reason": "历史还款逾期次数超过阈值"
}4.4 评分API请求-响应流程
下图展示了从客户端发起请求到接收评分的完整数据流，包含参数校验、模型推理与结果组装三个核心阶段。
4.5 错误码与异常处理
除正常响应外，API在异常情况下返回标准HTTP状态码及错误信息。
| HTTP状态码 | 错误场景 | 响应示例 |
|---|---|---|
| 400 | 请求参数缺失或格式错误 | {"error": "feature_vector 长度必须为12"} |
| 401 | API Key 无效或缺失 | {"error": "未授权访问"} |
| 422 | 特征向量数值超出范围 | {"error": "特征值必须在 [-1, 1] 范围内"} |
| 429 | 请求频率超过限制 | {"error": "请求过于频繁，请稍后重试"} |
| 500 | 模型推理内部错误 | {"error": "评分服务内部异常"} |
注意：调用方必须处理所有错误码，特别是 422 和 429。特征向量数值越界会导致评分失真，频率限制触发后需实现指数退避重试策略。
4.6 接口契约验证清单
在接入评分API前，建议按以下清单逐项验证接口契约的完整性：
- 请求格式验证：确认
user_id为字符串且长度合规，feature_vector为数组且长度为12。 - 特征范围验证：确认所有特征值在 [-1, 1] 区间内，缺失值使用 -1 填充。
- 响应字段完整性：确认响应包含
score、grade、rejection_reason三个字段。 - 等级映射验证：确认评分与等级的映射关系与对照表一致。
- 拒绝逻辑验证：确认评分低于600时
rejection_reason不为 null。 - 错误码覆盖验证：确认所有错误场景均能返回正确的HTTP状态码和错误信息。