# 印尼支付行为画像查询接口

## 接口概览

| 接口 | 路径 | 说明 |
|---|---|---|
| V1 特征 | `POST /api/v1/fortispay/payment-feature` | 返回 V1 版 536 个特征字段（6 模块） |
| V2 特征 | `POST /api/v1/fortispay/payment-feature-v2` | 返回 V2.2 版 606 个特征字段（6 模块，不含综合评分） |
| V2 评分 | `POST /api/v1/fortispay/payment-feature-v2-score` | 返回 V2.2 版 15 个综合评分字段（overall_score 模块） |

三个接口调用**同一三方 API**，入参、缓存、日志相同，仅响应 `data.result` 字段过滤规则不同。

---

## 公共信息

| 项目 | 说明 |
|---|---|
| 请求格式 | `application/json; charset=UTF-8` |
| 响应格式 | `application/json` |

### 请求头部

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Content-Type | String | Y | `application/json` |
| X-Request-Id | String | N | 网关请求唯一标识ID，用于全链路追踪，原样回显在响应头中 |
| X-Language | String | N | 语言标识，传 `en` 返回英文结果，不传默认英文 |

### 响应头部

| 参数 | 类型 | 说明 |
|---|---|---|
| X-Request-Id | String | 回显请求头中的 X-Request-Id，未传则自动生成 32 位 UUID |
| X-Session-Id | String | 三方服务返回的唯一会话标识（Fortispay responseId） |

### 请求体

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | String | Y | 用户姓名 |
| id_card | String | Y | 身份证号，支持明文或 MD5 密文 |
| mobile | String | Y | 手机号（带国家码），支持明文或 MD5 密文 |
| encrypt_algo | String | N | 加密算法。**不传**表示明文，服务端原样透传给三方；传入 `MD5` 表示已加密，直接透传 |

### 请求示例

```json
{
  "name": "ABCXYZ",
  "id_card": "3201190108990002",
  "mobile": "6285887456612"
}
```

> id_card、mobile 传明文时无需传 encrypt_algo，服务端原样透传给三方。

```json
{
  "name": "ABCXYZ",
  "id_card": "cf0ab15098ab149e5273dd82f2c737e6",
  "mobile": "bd82af6340240c43175a80aedf7e6eef",
  "encrypt_algo": "MD5"
}
```

> id_card、mobile 传密文时必须传 encrypt_algo="MD5"。

### 错误响应

错误响应与三方接口响应保持相同结构，其中 `data` 中 `status=0`、`result=null`：

```json
{
  "code": "503",
  "message": "External API unreachable after 1 attempts",
  "responseId": "a1b2c3d4e5f6789012345678abcdef01",
  "data": {
    "status": 0,
    "result": null
  }
}
```

| HTTP状态码 | code | 说明 |
|---|---|---|
| 400 | 400 | 请求参数校验失败 |
| 502 | 502 | 三方 API HTTP 错误 |
| 503 | 503 | 三方 API 网络不可达 |
| 500 | 500 | 服务内部未知异常 |

---

## 一、V1 特征接口

`POST /api/v1/fortispay/payment-feature`

### 响应说明

`data.result` 只保留 V1.xlsx 中的 536 个字段，6 个模块：

| 模块 | 字段数 | 说明 |
|---|---|---|
| `app_behavior` | 90 | 申请行为变量 |
| `loan_behavior` | 140 | 放款行为变量 |
| `repay_behavior` | 150 | 还款行为变量 |
| `time_structure` | 46 | 行为时间结构变量 |
| `delinq_monitor` | 50 | 逾期行为监控 |
| `flow_anomaly` | 60 | 资金流量异常监控变量 |

### 完整调用示例

```bash
curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'
```

---

## 二、V2 特征接口

`POST /api/v1/fortispay/payment-feature-v2`

### 响应说明

`data.result` 保留 V2.2.xlsx 中的 606 个特征字段（6 模块，不含综合评分）：

| 模块 | 字段数 | 相比 V1 新增 |
|---|---|---|
| `app_behavior` | 90 | — |
| `loan_behavior` | 150 | +10（`credit_to_apply_rate_by_org_cnt_day*`） |
| `repay_behavior` | 190 | +40（还款与放款/申请的交叉比率） |
| `time_structure` | 46 | — |
| `delinq_monitor` | 70 | +20（逾期与申请/还款的交叉比率） |
| `flow_anomaly` | 60 | — |

> 注意：比率类字段类型为 `float`（V1 中为 `Int`）。

### 完整调用示例

```bash
curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature-v2 \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'
```

---

## 三、V2 评分接口

`POST /api/v1/fortispay/payment-feature-v2-score`

### 响应说明

`data.result` 只保留 V2.2.xlsx 中 `overall_score` 模块的 15 个字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `recent_risk_level_v1` ~ `v5` | Int | 申请人即时风险资质等级 V1~V5 |
| `mid_risk_level_v1` ~ `v5` | Int | 申请人阶段风险资质等级 V1~V5 |
| `long_risk_level_v1` ~ `v5` | Int | 申请人长效风险资质等级 V1~V5 |

### 成功响应示例

```json
{
  "code": "0",
  "message": "success",
  "responseId": "0b5a09b6ea7d77dbbbb92e05dc9744ad",
  "data": {
    "status": 1,
    "result": {
      "overall_score": {
        "recent_risk_level_v1": 7,
        "recent_risk_level_v2": 70,
        "recent_risk_level_v3": 8,
        "recent_risk_level_v4": 18,
        "recent_risk_level_v5": 35,
        "mid_risk_level_v1": 46,
        "mid_risk_level_v2": 47,
        "mid_risk_level_v3": 30,
        "mid_risk_level_v4": 87,
        "mid_risk_level_v5": 51,
        "long_risk_level_v1": 36,
        "long_risk_level_v2": 37,
        "long_risk_level_v3": 13,
        "long_risk_level_v4": 16,
        "long_risk_level_v5": 89
      }
    }
  }
}
```

### 完整调用示例

```bash
curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature-v2-score \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'
```

---

## 缓存说明

三个接口共享同一套缓存。缓存以原始三方响应存储，命中缓存后按接口版本过滤 `result` 字段返回。同一用户查询任意接口后，其他接口命中缓存均无需再次调用三方。