📚 课程目录第3章信用评分API基础

3. 信用评分API基础：RESTful API设计原则与常见端点

在开始回放验证之前，必须理解信用评分API的底层设计哲学与接口契约。本章将聚焦RESTful架构在评分场景下的落地方式，并拆解申请评分、行为评分等核心端点的请求/响应结构。

3.1 RESTful API设计原则在评分场景中的映射

信用评分API遵循REST（Representational State Transfer）风格，将评分模型封装为资源，通过标准HTTP方法进行操作。以下表格对比了通用REST原则与评分API的具体实现：

REST原则	评分API实现	示例
资源导向	将“评分申请”视为资源，而非RPC调用	`POST /v1/credit-scores/applications`
无状态	每次请求携带完整上下文（如客户ID、产品类型）	请求体包含 `customer_id`、`product_code`
统一接口	使用标准HTTP动词 + JSON格式	`GET` 查询评分记录，`POST` 发起评分
可缓存	评分结果支持短时缓存（如TTL=5分钟）	响应头 `Cache-Control: max-age=300`
分层系统	网关层、评分引擎层、数据源层分离	API Gateway → 评分服务 → 特征数据库

回放验证要点： 无状态原则意味着回放时不能依赖会话保持。每次回放请求必须独立构造完整的请求体，包括时间戳、客户标识等上下文字段。

3.2 常见信用评分API端点详解

信用评分API通常按业务阶段划分为三大类：申请评分、行为评分和催收评分。本课程重点覆盖前两类。

3.2.1 申请评分端点（Application Scoring）

申请评分用于新客户准入决策，通常在客户提交贷款申请时调用。典型端点设计如下：

POST /v1/credit-scores/applications
Content-Type: application/json

{
  "request_id": "REQ-20250321-001",
  "customer": {
    "customer_id": "CUST-10086",
    "id_type": "ID_CARD",
    "id_number": "110101199001011234"
  },
  "product": {
    "product_code": "PERSONAL_LOAN",
    "loan_amount": 50000,
    "loan_term_months": 12
  },
  "extra_features": {
    "channel": "ONLINE_APP",
    "device_fingerprint": "FP-abc123"
  }
}

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "REQ-20250321-001",
  "score": 725,
  "decision": "APPROVE",
  "reason_codes": ["R01", "R03"],
  "score_card_version": "v2.3.1",
  "timestamp": "2025-03-21T10:30:00Z"
}

申请评分端点的关键字段说明：

字段	类型	说明	回放验证关注点
`request_id`	string	幂等键，防止重复评分	相同request_id应返回相同结果
`score`	integer	评分值，范围300-850	与历史回放记录精确匹配
`decision`	string	决策结果：APPROVE/REJECT/REVIEW	决策逻辑是否与回放一致
`reason_codes`	array	拒绝或降额原因码	原因码顺序和内容需一致

3.2.2 行为评分端点（Behavior Scoring）

行为评分用于存量客户的风险动态监控，基于还款、消费、查询等行为数据定期更新评分。典型端点设计：

POST /v1/credit-scores/behaviors
Content-Type: application/json

{
  "request_id": "BEH-20250321-001",
  "customer_id": "CUST-10086",
  "observation_date": "2025-03-20",
  "behavior_data": {
    "total_repayment_amount": 12000,
    "overdue_days_max": 0,
    "credit_utilization_rate": 0.35,
    "recent_inquiry_count_30d": 2
  }
}

响应示例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "request_id": "BEH-20250321-001",
  "behavior_score": 680,
  "score_trend": "STABLE",
  "risk_level": "LOW",
  "next_review_date": "2025-04-20",
  "timestamp": "2025-03-21T12:00:00Z"
}

  申请评分 vs 行为评分核心差异：
  数据来源：申请评分依赖外部征信+申请表；行为评分依赖内部交易流水。
更新频率：申请评分一次性；行为评分按月/按周周期性更新。
回放策略：申请评分回放需固定时间点；行为评分回放需对齐观察日期。

3.3 评分API的通用架构模式

下图展示了信用评分API的典型分层架构，回放验证工具需要模拟客户端请求，穿透网关直达评分引擎：

3.4 端点版本管理与幂等性设计

信用评分API必须支持版本演进，同时保证回放验证时历史版本可追溯。常见版本策略：

URI版本控制： /v1/credit-scores/applications → /v2/credit-scores/applications
请求头版本控制： Accept: application/vnd.credit-score.v2+json
幂等性保障： 使用 request_id 作为幂等键，相同ID重复请求返回首次结果

回放验证陷阱： 如果API版本升级导致评分逻辑变化，回放时需明确指定版本号。未指定版本的回放请求可能被路由到最新版，造成结果偏差。

3.5 端点参数对比速查表

以下表格汇总了申请评分与行为评分端点的参数差异，便于回放脚本编写时快速对照：

参数维度	申请评分	行为评分
请求路径	`/v1/credit-scores/applications`	`/v1/credit-scores/behaviors`
核心标识	`customer_id` + `product_code`	`customer_id` + `observation_date`
特征来源	征信报告、申请表	内部交易流水、还款记录
评分频率	一次性（申请时）	周期性（月/周）
响应决策	APPROVE / REJECT / REVIEW	风险等级 + 趋势标记
缓存策略	短缓存（5-15分钟）	长缓存（1-7天）

3.6 回放验证的端点适配策略

在回放验证中，需要将历史录制的请求重新发送到目标端点。以下是适配策略的步骤列表：

端点映射： 将录制时的端点路径映射到当前测试环境的对应路径（如 /v1/credit-scores/applications → /test/v1/credit-scores/applications）。
请求体清洗： 移除时间敏感字段（如 timestamp）或替换为回放时的固定值。
幂等键复用： 保留原始 request_id，确保重复回放不会产生副作用。
版本对齐： 检查录制时的API版本，在回放请求头中显式声明。
响应比对： 将回放响应与录制响应进行字段级比对，重点关注 score、decision、reason_codes。

实战建议： 在回放脚本中为每个端点编写独立的适配器函数，将录制请求转换为当前环境可执行的请求。这样当端点版本升级时，只需修改适配器逻辑，无需重写整个回放流程。