快速开始
欢迎使用 Credit Kernel 开放 API。本文说明通用接入方式、请求签名、以及统一的返回约定。完成账号开通后，请按左侧各产品文档完成联调。
1. 简介
Credit Kernel 数据服务面向信贷与风控场景，提供黑名单查询、证件识别、证件真伪检测、薪资单识别等能力。接入方通过 HTTPS 调用 API，使用平台下发的凭据完成认证。
建议阅读顺序：
- 本文「快速开始」（凭据、签名、返回码）
- 对应产品接口文档（路径、入参、出参）
- 联调通过后切换生产环境地址（以开通邮件为准）
2. 名词说明
| 术语 | 说明 |
|---|---|
| API Key | 请求头 X-API-Key，标识调用方身份 |
| Secret | 签名密钥，仅用于服务端计算签名，不得下发到 App / 浏览器 |
| Status / code | 业务或网关返回状态；请以状态码做分支判断，文案仅供参考，可能调整 |
| 计费标记 | 部分接口返回是否计费（如 PAY / FREE，或命中才计费），以各产品文档为准 |
3. 接入步骤
- 申请试用或商务开通，获得测试账号与凭据（API Key、Secret）。
- 按本文完成签名实现，用右侧代码示例做一次验签自检。
- 按产品文档构造业务请求，确认成功与失败的返回结构。
- 注意限流与配额；超限时按返回码退避重试。
- 正式上线前切换生产网关地址，并妥善保管生产 Secret。
4. 请求签名（经数据网关的接口）
经 数据服务网关 调用的接口（如证件真伪检测等），须在请求头携带签名。黑名单等产品若在文档中约定了独立验签方式，以该产品文档为准。
4.1 凭据
| 凭据 | 用途 |
|---|---|
X-API-Key |
明文身份标识，放在请求头 |
| Secret | 仅用于 HMAC 计算，禁止写入前端、客户端、日志或代码仓库 |
4.2 请求头
| 请求头 | 必填 | 说明 |
|---|---|---|
Content-Type |
是 | JSON 请求固定为 application/json |
X-API-Key |
是 | 平台分配的 Key |
X-Timestamp |
是 | Unix 秒级时间戳（勿用毫秒） |
X-Nonce |
是 | 每次请求唯一的随机串，防重放 |
X-Signature |
是 | Base64(HMAC-SHA256(secret, canonical)) |
4.3 签名串
canonical =
METHOD + "\n" +
RAW_PATH + "\n" +
sortedQuery + "\n" +
bodySha256 + "\n" +
timestamp + "\n" +
nonce
signature = Base64( HMAC-SHA256(secret, canonical) )
要点：
METHOD大写；RAW_PATH为问号前的原始路径（保留百分号编码）。- 无 query 时
sortedQuery为空字符串，但仍占一行（两个换行之间为空）。 - JSON Body：先按 RFC 8785（JCS）规范化，再算 SHA-256（小写 hex）。
- 空 Body：
bodySha256固定为
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。 - Secret 按 UTF-8 原文参与 HMAC，不要先做 Base64 解码。
X-Signature为标准 Base64（含+/=），非 URL-Safe。
4.4 请求示例
curl -X POST "https://data-gateway-test.creditkernel.ai/api/v1/blacklist_check" \
-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: <Base64 HMAC>" \
-d '{"requestId":"<uuid>","args":{"idType":"UMID","idNumber":"011145131134","phoneNumber":"9674315469"}}'
完整可运行的 Java 示例工程文件可由对接同学另行提供；右侧「代码示例」展示常用 curl，便于复制联调。
4.5 自检向量（可选）
若实现与下列结果一致，说明 JCS / HMAC / Base64 已正确：
| 项 | 值 |
|---|---|
| path | /api/v1/blacklist_check |
| timestamp | 1779340359 |
| nonce | n-550e8400-e29b-41d4-a716-446655440000 |
| bodySha256 | 2a3afc39ddc0f44fe7fb0f119e87e32f2da21ce970b5aabb1088f7ff7c27e00b |
| signature | T7k4ytsf0rHYG6Y5/PQkgTqZKORdhDAmF55ksZxs0rw= |
（样例 Key / Secret 仅用于算法自检，生产请使用正式下发值。）
5. 返回结果与状态码
请优先根据 状态码 / status / code 编写业务逻辑，不要依赖提示文案的固定措辞。
5.1 网关层常见 HTTP 状态
| HTTP | 含义 | 建议处理 |
|---|---|---|
| 200 | 请求已被网关受理；业务成败看 Body | 解析业务字段 |
| 401 | 鉴权失败（Key / 签名 / 时间窗 / 重放） | 核对签名与时钟，更换 nonce |
| 403 | 无权限或账号禁用 | 联系对接同学 |
| 429 | 触发限流 | 退避重试 |
| 5xx | 服务端异常 | 有限次重试后告警 |
5.2 业务 Body 常见字段
不同产品字段名可能略有差异，常见形态如下：
| 字段 | 说明 |
|---|---|
status / code |
业务状态：成功、参数错误、余额不足等 |
msg / message |
说明文案，仅供展示与排查 |
data |
业务数据对象；失败时可能为 null |
request_id / requestId |
请求跟踪号，反馈问题时请一并提供 |
| 计费相关 | 如 pricing_strategy、hit 是否计费等，见各产品文档 |
5.3 业务状态示例（示意）
| 状态 | 说明 |
|---|---|
SUCCESS / success / 1 |
调用成功（是否计费见产品规则） |
ERROR |
服务端错误 |
EMPTY_PARAMETER_ERROR / 参数为空 |
必填缺失 |
PARAMETER_ERROR |
参数格式不合法 |
INSUFFICIENT_BALANCE |
余额或配额不足 |
SERVICE_BUSY |
繁忙或超限，请稍后重试 |
IAM_FAILED |
身份鉴权失败 |
各产品若定义了专属错误码表，以产品文档为准；上表用于统一理解「用状态码分支」的接入习惯。
5.4 注意事项
- 成功状态也可能因产品规则产生费用，或未命中不计费——以产品「计费说明」为准。
- Message 文案可能迭代，不要用全文匹配 Message 做判断。
- 重试时务必重新生成
X-Nonce与X-Signature。
6. 请求参数约定
| 约定 | 说明 |
|---|---|
| 请求地址 | 见各产品「请求地址」；测试 / 生产域名以开通通知为准 |
| 必填参数 | 未标注可选的均为必填 |
| 可选参数 | 文档中标明「可选」；省略时使用默认值 |
| 文件 / 图片 | 注意大小、格式与清晰度要求（见产品文档） |
7. 下一步
请从左侧选择已开通的产品文档继续阅读，例如「黑名单查询」「证件识别」「证件真伪检测」「薪资单识别」。如需变更开通范围，请联系客户经理。