黑名单检测接口对接文档

服务名称：黑名单检测
接口版本：v1.0

1. 接口概述

1.1 接口能力

黑名单检测接口提供基于证件号和/或手机号的黑名单实时查询能力，聚合多种数据源，按生效 source 判定是否命中，并返回：

• 整体是否命中（data.hit）
• 系统订单号（data.orderId）
• 是否计费（data.billable）
• 分数据源命中详情（data.hitSources，按租户配置决定是否返回）

1.2 业务场景

本接口为信贷业务提供黑名单风险筛查能力，主要面向现金贷场景下的申请人风险识别。命中黑名单建议拒绝该申请人的业务请求。

2. 接口基本信息

2.1 环境地址

完整请求地址 = Base URL + 请求路径，例如测试环境：

https://data-gateway-test.creditkernel.ai/api/v1/blacklist_check

3. 鉴权与签名

当前接入模式仅支持 API Key + 请求签名。标准接入方式为通过数据服务网关接入，请求依次经过网关的认证、限流、配额、权限校验后，转发至黑名单检测服务。

3.1 接入凭据

签名认证开始前，请确认已收到以下两项凭据：

• X-API-Key（明文身份标识）：通过请求头发送给网关，可视为接入方身份。
• 签名密钥 secret：与 X-API-Key 唯一对应，仅用于在你的服务端计算签名，严禁出现在前端代码、客户端、URL、日志、git 提交中。

两项凭据由我方生成并通过安全渠道一次性下发，请妥善保管；如怀疑泄漏请立即联系我方更换。

3.2 请求头参数

每次请求须携带以下请求头：

请求未携带有效 X-API-Key 或签名头时，将被直接拒绝。

3.3 签名计算规范

canonical = METHOD + "\n" + RAW_PATH + "\n" + sortedQuery + "\n" + bodySha256 + "\n" + timestamp + "\n" + nonce
signature = Base64( HMAC_SHA256(secret, canonical) )

完整计算逻辑见 3.5 签名示例代码。以下为代码中未体现的关键要点：

• RAW_PATH：保留 percent-encoding，不做 URL 解码
• JSON body 须先做 JCS 规范化（RFC 8785），Java 推荐 io.github.erdtman:java-json-canonicalization:1.1
• secret 按 UTF-8 字节直接作为 HMAC 密钥，不要做 Base64 解码
• signature 使用标准 Base64（含 +、/、=），不是 URL-safe Base64
• timestamp / nonce：见 3.4

3.4 timestamp 与 nonce

• X-Timestamp：Unix 秒级时间戳（UTC）。必须使用秒（13 位毫秒时间戳会被拒）。服务端允许时钟偏差 ±180 秒，超出将被拒绝（返回 401）。客户端机器时间应与标准时间保持同步（建议启用 NTP）。
• X-Nonce：每次请求唯一的随机串，用于防重放。每次请求都生成新的 nonce，绝不复用；建议使用 UUIDv4 等高强度随机来源。重试场景必须重新生成 nonce 并重新签名。

3.5 签名示例

以下 Java 代码展示签名计算的核心逻辑：

// 1. JSON body 做 JCS 规范化
String canonicalBody = new JsonCanonicalizer(body).getEncodedString();

// 2. 计算 bodySha256（小写 hex）
String bodySha256 = sha256Hex(canonicalBody.getBytes(StandardCharsets.UTF_8));

// 3. 拼接 canonical（无 query 时 sortedQuery 为空字符串，\n 不可省）
String canonical = method + "\n"
        + rawPath + "\n"
        + sortedQuery + "\n"
        + bodySha256 + "\n"
        + timestamp + "\n"
        + nonce;

// 4. HMAC-SHA256 + 标准 Base64
String signature = Base64.getEncoder().encodeToString(
        hmacSha256(secret.getBytes(StandardCharsets.UTF_8),
                   canonical.getBytes(StandardCharsets.UTF_8)));

自验对照值（使用固定输入计算，你的实现应得到相同结果）：

3.6 签名校验失败排查

签名校验失败时，网关返回 HTTP 401，常见原因：

1. 客户端时间未与标准时间同步，超出 ±180 秒窗口。
2. canonical 拼接顺序错误或缺少空行（无 query 时第 3 行为空）。
3. JSON body 未做 JCS 规范化。
4. secret 被误做 Base64 解码（应直接用 UTF-8 字节）。
5. signature 使用了 URL-safe Base64（应使用标准 Base64）。
6. nonce 在重试时复用了旧值。

4. 请求参数

4.1 请求体（Request Body）

请求体为 JSON 对象，字段如下：

4.2 证件类型与格式要求

idType 必须为以下枚举之一（大小写敏感），非法值返回业务 BAD_REQUEST（idType is invalid）：

DriverLicense、NATIONALID、HealthID、PostalID、Passport、VotersCard、TINID、SSS、PRC、GSIS、UMID

说明：平台不强制校验 idNumber 的字符格式；但为提高命中率与数据一致性，建议按下列格式准备证件号：

4.3 校验规则

以下为请求参数的校验规则：

1. args 不可为 null；且至少包含一个非空字段：idNumber 或 phoneNumber。
2. 当 idNumber 存在时，idType 必传且必须属于 4.2 枚举。
3. idNumber 仅支持明文传输。
4. phoneNumber 默认明文；明文须符合 4.4 格式。平台会对手机号做菲律宾号码归一（去非数字字符，剥离 63 国家码或前导 0，归一为 9 开头的 10 位本体）。
5. 请求未携带有效 X-API-Key 或签名头时，网关将直接拒绝请求。

4.4 可选：手机号加密传输

本接口默认采用明文传输手机号，推荐接入方使用明文方式调用。

如需加密传输，仅手机号（phoneNumber）支持加密，证件号（idNumber）始终为明文。通过 args.phoneNumberEncryptType 指定加密方式。

使用 MD5 或 SHA256 时，须先将手机号标准化为 9xxxxxxxxx（10 位纯数字）后再计算哈希值。若哈希无效或无法通过校验，请求将被拒绝。

手机号相关校验失败发生在网关层，响应结构为网关错误响应（code 为 GATEWAY_BAD_REQUEST），不是业务层 BAD_REQUEST。见 6.5.4。

5. 请求示例

5.1 明文手机号（含可选 sourceCodes）

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <Your API Key>" \
  -H "X-Timestamp: <epoch_seconds>" \
  -H "X-Nonce: <random_nonce>" \
  -H "X-Signature: <Your Signature>" \
  -d '{
    "requestId": "14db1297-651a-4af7-b80c-33c5d59cb2c4",
    "args": {
      "idType": "UMID",
      "idNumber": "011188130034",
      "phoneNumber": "9674885469"
    }
  }' \
  "https://data-gateway-test.creditkernel.ai/api/v1/blacklist_check"

5.2 MD5 手机号（可选，见 4.4）

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <Your API Key>" \
  -H "X-Timestamp: <epoch_seconds>" \
  -H "X-Nonce: <random_nonce>" \
  -H "X-Signature: <Your Signature>" \
  -d '{
    "requestId": "14db1297-651a-4af7-b80c-33c5d59cb2c4",
    "args": {
      "idType": "UMID",
      "idNumber": "011188130034",
      "phoneNumber": "e10adc3949ba59abbe56e057f20f883e",
      "phoneNumberEncryptType": "MD5"
    }
  }' \
  "https://data-gateway-test.creditkernel.ai/api/v1/blacklist_check"

5.3 SHA256 手机号（可选，见 4.4）

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <Your API Key>" \
  -H "X-Timestamp: <epoch_seconds>" \
  -H "X-Nonce: <random_nonce>" \
  -H "X-Signature: <Your Signature>" \
  -d '{
    "requestId": "14db1297-651a-4af7-b80c-33c5d59cb2c4",
    "args": {
      "idType": "UMID",
      "idNumber": "011188130034",
      "phoneNumber": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b",
      "phoneNumberEncryptType": "SHA256"
    }
  }' \
  "https://data-gateway-test.creditkernel.ai/api/v1/blacklist_check"

6. 响应说明

标准接入（网关接入）模式下，本接口存在两种响应结构：

• 网关层错误响应：请求在网关侧（认证、限流、配额、权限、路由、手机号加密校验等）被拦截时返回，结构为 {timestamp, path, status, code, message, requestId}，HTTP 状态码为非 2xx。
• 业务层响应：请求通过网关校验后进入业务处理，返回结构为 {success, code, message, requestId, data}。

6.1 业务层响应字段

6.1.1 hitSources 结构

hitSources 为以 source 编码为 key 的对象，例如：

{
  "source1": { "hit": false, "blacklistTime": null },
  "source2": { "hit": true, "blacklistTime": "2025-10-20" }
}

若租户被配置为不返回 hitSources，成功响应中将不包含该字段；data.hit / data.billable / data.orderId 仍会返回。

测试环境默认返回所有source的命中情况详情； 经过测试结果分析,上生产前租户告知服务方使用哪些源

6.2 网关层错误响应字段

6.3 计费规则

计费原则：仅命中黑名单时计费，未命中及各类错误均不计费。

6.4 状态码说明

6.4.1 业务状态码

Charge 列含义：pay = 命中时计费，free = 不计费。详见 6.3 计费规则。

6.4.2 网关状态码（常见）

429（限流/配额超限）与 503（下游不可用）为可重试错误，接入方可根据自身业务实现重试逻辑。

6.5 响应示例

6.5.1 成功响应（命中）

{
  "success": true,
  "code": "SUCCESS",
  "message": "",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "hit": true,
    "orderId": "BL20260611143303916be007480370d4d2784c2dcf625a2fc04",
    "billable": true,
    "hitSources": {
      "source1": { "hit": false, "blacklistTime": null },
      "source2": { "hit": true, "blacklistTime": "2025-10-20" }
    }
  }
}

6.5.2 成功响应（未命中）

{
  "success": true,
  "code": "SUCCESS",
  "message": "",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "hit": false,
    "orderId": "BL20260611143303916be007480370d4d2784c2dcf625a2fc04",
    "billable": false,
    "hitSources": {
      "source1": { "hit": false, "blacklistTime": null },
      "source2": { "hit": false, "blacklistTime": null }
    }
  }
}

6.5.3 业务参数错误响应

{
  "success": false,
  "code": "BAD_REQUEST",
  "message": "idType is required when idNumber is provided",
  "requestId": "eef65760-12bd-4414-a8eb-25483de36012",
  "data": null
}

常见业务参数错误提示（code 均为 BAD_REQUEST，以 message 区分）：

以上多种参数错误共用同一业务状态码 BAD_REQUEST，仅靠 message 文本区分。对接方如需程序化区分具体错误类型，需对 message 做字符串匹配。

6.5.4 网关手机号参数错误响应

手机号明文/哈希格式错误、加密类型非法、哈希校验失败等，由网关拦截，示例：

{
  "timestamp": "2026-06-14T04:53:10.972Z",
  "path": "/api/v1/blacklist_check",
  "status": 400,
  "code": "GATEWAY_BAD_REQUEST",
  "message": "phoneNumber format invalid for PLAIN",
  "requestId": "1d13ad16-9988"
}

常见网关手机号相关 message：

6.5.5 API Key / source 权限错误响应

{
  "success": false,
  "code": "FORBIDDEN",
  "message": "header X-API-KEY is not allowed",
  "requestId": "eef65760-12bd-4414-a8eb-25483de36012",
  "data": null
}

sourceCodes 越权示例 message：

requested sourceCodes are out of tenant allowed scope: [source9]

6.5.6 网关鉴权错误响应（401）

{
  "timestamp": "2026-05-13T10:37:05.612Z",
  "path": "/api/v1/blacklist_check",
  "status": 401,
  "code": "GATEWAY_UNAUTHORIZED",
  "message": "签名校验失败",
  "requestId": "60afbeb9-8"
}

6.5.7 网关配额超限响应（429）

{
  "timestamp": "2026-06-14T03:59:43.869Z",
  "path": "/api/v1/blacklist_check",
  "status": 429,
  "code": "GATEWAY_QUOTA_EXHAUSTED",
  "message": "租户调用总配额已用尽",
  "requestId": "..."
}

6.5.8 网关限流响应（429）

{
  "timestamp": "2026-06-14T04:53:10.972Z",
  "path": "/api/v1/blacklist_check",
  "status": 429,
  "code": "GATEWAY_RATE_LIMITED",
  "message": "请求过于频繁",
  "requestId": "1d13ad16-9988"
}

7. 限流与配额

网关提供两层流量控制：

• QPS 限流：基于令牌桶算法，按租户+客户端+路由维度限制每秒请求数。超限返回 GATEWAY_RATE_LIMITED（429）。
• 总配额：按租户维度控制累计调用总量，跨实例共享。耗尽返回 GATEWAY_QUOTA_EXHAUSTED（429）。

具体 QPS 上限与配额总量由租户签约约定，如有调整需求请联系我方。

8. 术语表（Glossary）