FirstCentral 征信接入方案
适用范围：MVP 阶段由 crs 统一封装 FirstCentral Credit Bureau REST API v2，供进件、授信风控、客户档案查询个人征信结果。
业务对象：尼日利亚个人消费信贷客户，均为自然人。
接入口径：只接 Consumer / Individual 个人征信；Commercial / Business 企业征信不纳入 MVP。
职责边界：crs 不做征信报告数据解析，只负责三方接口调用、票据管理、原始结果保存、查询状态和元数据记录。
1. 接入结论
- 主接流程：
login 取票据 -> ConnectConsumerMatch 用 BVN 匹配个人主体 -> consumerreports 拉个人征信报告 -> crs 保存原始报告和查询元数据，返回给风控/客户档案消费。
- 主选产品：
ProductID=50，即 Xscore Consumer Detailed Credit，包含详细信用报告和 Xscore 评分。
- 建议同步接入：
GetXScoreConsumerFullCreditBinaryReport，用于保存 PDF / 二进制原件，便于审计和人工复核。
- 不接产品：Commercial 企业报告、Basic Trace、Prime 等低优先级个人报告，除非后续风险策略或商务报价另行确认。
2. 账号与环境
| 环境 | Base URL | 账号 |
|---|
| UAT | https://uat.firstcentralcreditbureau.com/firstcentralrestv2/ | 以测试材料或供应商提供为准 |
| Live | https://online.firstcentralcreditbureau.com/firstCentralrestv2 | Username：PIXEFINANCEAPI；Password：PIXEFINANCE@123 |
注意：
- 账号密码属于生产凭证，代码中只读取配置中心 / 密钥库，不允许硬编码。
/login 返回的 DataTicket 有效期为 5 小时；crs 应缓存票据，并在过期或调用返回认证失败时重新登录。
3. 对接流程
sequenceDiagram
participant App as 业务编排/进件
participant CRS as crs
participant FC as FirstCentral
participant Risk as 风控
participant Cust as 客户档案
App->>CRS: 发起征信查询(customerId, BVN, purpose)
CRS->>FC: POST /login
FC-->>CRS: DataTicket
CRS->>FC: POST /ConnectConsumerMatch(BVN, ProductID)
FC-->>CRS: ConsumerID, EnquiryID, MatchingEngineID
CRS->>FC: POST /consumerreports(productid=50)
FC-->>CRS: Xscore 详细报告
CRS->>FC: POST /GetXScoreConsumerFullCreditBinaryReport
FC-->>CRS: 报告原件
CRS->>CRS: 保存原始报告、查询元数据、缓存有效期
CRS-->>Risk: 返回查询状态和原始报告引用
CRS-->>Cust: 归档原始报告和查询记录
3.1 登录取票据
- 接口：
POST /login
- 入参：
username、password
- 出参：
DataTicket
crs 处理：
- 按供应商 + 环境缓存票据。
- 缓存过期时间建议设置为 4 小时 50 分钟，避免贴近 5 小时边界失败。
- 可用
/ValidateTicket 做主动校验，但正常调用不必每次校验。
3.2 个人主体匹配
- 接口：
POST /ConnectConsumerMatch
- 推荐检索方式：BVN。
- BVN 检索时，
ConsumerName、DateOfBirth、Accountno 传空串。
- 关键入参：
| 字段 | 说明 |
|---|
DataTicket | 登录票据 |
EnquiryReason | 查询理由，固定：Application for Credit by a borrower |
Identification | 客户 BVN |
ProductID | 与后续报告产品保持一致，主选 50 |
| 字段 | 用途 |
|---|
ConsumerID | 后续报告请求的主体 ID |
EnquiryID | 后续报告请求必传 |
MatchingEngineID | 后续报告请求的 SubscriberEnquiryEngineID |
MatchingRate | 匹配置信度，供多匹配场景判断 |
3.3 拉取个人征信报告
- 推荐接口：
POST /consumerreports
- 主选产品：
productid=50
- 关键入参映射：
| 报告请求字段 | 来源 |
|---|
consumerID | ConnectConsumerMatch.MatchedConsumer[].ConsumerID |
EnquiryID | ConnectConsumerMatch.MatchedConsumer[].EnquiryID |
consumerMergeList | 单主体传同一个 ConsumerID；多主体合并时用逗号拼接 |
SubscriberEnquiryEngineID | ConnectConsumerMatch.MatchedConsumer[].MatchingEngineID |
productid | 报告产品，主选 50 |
consumerreports 可按 productid 返回不同个人报告，非二进制报告都优先通过该通用接口接入，避免每个产品单独写一套适配。
3.4 报告原件存档
- 接口：
POST /GetXScoreConsumerFullCreditBinaryReport
- 用途：保存 FirstCentral 原始报告，支撑审计、人工复核、客诉追溯。
- 联调待确认：返回是 base64 字符串还是二进制流；
crs 需要统一存储为文件对象，并在征信查询记录中保存文件引用。
3.5 可选 KYC（暂不考虑）
- 接口：
POST /GetConsumerKYCVerificationReport
- 产品：
ProductID=66
- 用途：BVN KYC 备选能力。
- MVP 默认不替代 Dojah KYC；仅作为征信供应商附带能力预留，是否启用由风控和产品确认。
4. 数据产品清单
4.1 MVP 建议接入
| ProductID | 产品 | 接口 | 用途 | MVP 取舍 |
|---|
| 50 | Xscore Consumer Detailed Credit | /consumerreports 或 /GetXScoreConsumerFullCreditReport | 个人详细征信 + Xscore 评分 | 主接 |
| 50 | Xscore Consumer Detailed Credit Binary | /GetXScoreConsumerFullCreditBinaryReport | 报告 PDF / 二进制原件 | 建议接 |
4.2 个人报告备选
| ProductID | 产品 | 接口 | 说明 |
|---|
| 43 | Consumer Basic Trace | /GetConsumerBasicTraceReport | 基础轨迹信息，信息量不足，暂不接 |
| 44 | Consumer Basic Credit | /GetConsumerBasicCreditReport / /GetConsumerBasicCreditBinaryReport | 基础信用报告，暂不接 |
| 45 | Consumer Detailed Credit | /GetConsumerFullCreditReport | 详细信用报告但不含 Xscore，报价更优时可替代 50 |
| 63 | Consumer Prime | /GetConsumerPrimeReport | 暂不接 |
| 64 | Xscore Consumer Prime | /GetXScoreConsumerPrimeReport | 暂不接 |
| 70 | iScore | /GetiScoreReport / /GetiScoreBinaryReport | 另一套评分产品，可作为风险策略备选 |
待风险确认后再确认最终产品范围
4.3 不接产品
| ProductID | 产品 | 原因 |
|---|
| 46 | Commercial Basic Credit | 企业征信，不符合个人消费信贷 MVP 范围 |
| 47 | Commercial Full Credit | 企业征信，不符合个人消费信贷 MVP 范围 |
4.4 实际拉取结果参考
使用 BVN 22533184864、查询理由固定为 Application for Credit by a borrower 拉取个人产品后的实际产出如下。这里的“可获得解析数据”表示 FirstCentral 返回了可结构化的 JSON 报告数据，解析动作由风控 / 数据消费方完成，crs 只保存原始响应和文件引用。
| ProductID | 产品 | 可获得解析数据 | PDF 原件 | 实际情况 |
|---|
| 43 | Consumer Basic Trace | 是 | 否 | 有 JSON 结构摘要；无 PDF 接口产物 |
| 44 | Consumer Basic Credit | 是 | 是 | 有 JSON 结构数据，也保存了 PDF |
| 45 | Consumer Detailed Credit | 是 | 否 | 有 JSON 结构摘要；无 PDF 产物 |
| 50 | Xscore Consumer Detailed Credit | 是 | 是 | 有 JSON 结构数据，也保存了 PDF |
| 63 | Consumer Prime | 是 | 否 | 有 JSON 结构摘要；无 PDF 产物 |
| 64 | Xscore Consumer Prime | 是 | 否 | 有 JSON 结构摘要；无 PDF 产物 |
| 70 | iScore | 是 | 是 | 有 JSON 结构数据，也保存了 PDF |
| 66 | KYC Verification | 否 | 否 | 返回 Customer not found，无可解析报告数据 |
5. 风控可解析的数据
crs 不解析以下字段。ProductID=50 的报告字典显示，返回结构以 XScore Consumer Full Credit 为核心，风控或数据消费方可按需解析以下数据块：
| 数据块 | 关键字段 | 风控用途 |
|---|
Scoring | TotalConsumerScore、RepaymentHistoryScore、TotalAmountOwedScore、TypesOfCreditScore、LengthOfCreditHistoryScore、NoOfAcctScore、Description | 信用评分、风险等级、评分卡变量 |
PersonalDetailsSummary | ConsumerID、BankVerificationNo、BirthDate、Gender、Surname、FirstName、手机号 | 身份核验、客户档案补全 |
CreditAccountSummary | TotalMonthlyInstalment、TotalOutstandingdebt、TotalAccountarrear、Amountarrear、TotalAccounts、TotalNumberofJudgement、TotalNumberofDishonoured | 负债、多头、逾期、司法和退票负面 |
AccountRating | 各类账户 Good / Bad 数量 | 账户结构和负面账户计数 |
CreditAgreementSummary | SubscriberName、OpeningBalanceAmt、CurrentBalanceAmt、AmountOverdue、PerformanceStatus、AccountStatus、LoanDuration | 逐笔贷款表现、当前逾期和在贷负债 |
AccountMonthlyPaymentHistory | M01 到 M24、MH01 到 MH24 | 最近 24 个月还款表现 |
EnquiryHistoryTop | DateRequested、SubscriberName、EnquiryReason | 近期征信查询次数 |
EmploymentHistory / AddressHistory | 雇主、职业、地址 | 辅助信息，不作为强规则唯一依据 |
crs 落库建议：
- 原始响应完整保存，便于风控重放、字段解析和问题排查。
- 不建设征信字段标准化表，不抽取评分、负债、逾期、账户数、还款历史等风控变量。
- 报告查询记录保存供应商、产品、请求目的、
EnquiryID、ConsumerID、MatchingEngineID、查询时间、缓存有效期、调用状态和错误码。
7. 需要注意的问题
- 生产环境禁止使用
Test / Test Run 作为 EnquiryReason，必须使用 CBN 批准的查询理由。
- 每次报告请求必须传
SubscriberEnquiryEngineID，其值来自匹配接口返回的 MatchingEngineID。
- BVN 是推荐检索方式；姓名 + 出生日期、手机号、驾照号可能返回多条候选，MVP 不建议作为主路径。
- 多匹配时不要默认全部合并。必须结合
MatchingRate、姓名、生日、BVN、手机号等规则确认同一人后，再构造 consumerMergeList。
DataTicket 5 小时有效，crs 要处理票据过期、重登、重试和并发刷新，避免高并发时重复登录。- 征信查询有成本，应按客户 + 产品 + 查询目的配置缓存有效期；有效期内优先复用，过期后再请求 FirstCentral。
- 原始报告可能是 XML / CDATA，也可能由 REST 包一层 JSON，联调时需确认最终返回格式；
crs 只保存原始内容和文件引用。
- 报告中的历史字段和金额字段可能为空、格式不一致或包含废弃字段；字段解析和容错由风控/数据消费方处理。
- 生产凭证、原始征信报告、BVN 和个人身份信息均为敏感数据，需要脱敏日志、访问审计、加密存储和权限控制。
- FirstCentral 可作为 Credit Registry 的备用或并行征信源；风控侧如需跨供应商标准字段，应在风控/数据层完成映射，不放在
crs。
8. 联调验收
- 能通过 live / UAT 配置切换完成登录、票据缓存、票据失效重登。
- 用 BVN 成功完成
ConnectConsumerMatch，并保存 ConsumerID、EnquiryID、MatchingEngineID。
- 用
ProductID=50 成功拉取报告，并能保存原始报告、二进制原件和查询元数据。
- 客户档案可通过
crs 查询记录关联到 FirstCentral 原始报告。
- 生产查询理由使用 CBN 批准值，不出现
Test。
- 商业线接口不被业务调用，MVP 只开放个人征信能力。