# 查询白名单接口 — 下游对接说明

> 本文档供**已开通权限的 API 用户 / 合作方**对接使用。  
> 用于配置「查询为空」屏蔽规则：命中后，指定人员在指定接口上的查询将返回 `1000 查询为空`。

---

## 1. 服务地址

| 环境 | 基础地址 |
|------|----------|
| 生产 | `https://api.tianyuanapi.com` |

完整路径 = 基础地址 + 下表路径，例如：

`https://api.tianyuanapi.com/api/v1/query-whitelist/entries`

---

## 2. 接口一览

| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 创建规则 | POST | `/api/v1/query-whitelist/entries` | 首次为某身份证建立屏蔽规则 |
| 追加接口 | POST | `/api/v1/query-whitelist/entries/append` | 向已有规则追加产品编码（去重合并） |

**说明：**

- 规则仅对**当前 `Access-Id` 对应账号**生效。
- 本接口为**配置类接口**，不产生业务查询、**不扣费**，也不会出现在常规 API 调用记录中。
- 规则生效后，该账号调用对应产品接口时，若命中屏蔽条件，将返回 `1000 查询为空`。

---

## 3. 鉴权

每次请求需同时满足以下三项。

### 3.1 请求头

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `Access-Id` | string | 是 | 您的 API 账号 Access-Id |
| `Whitelist-Mgmt-Key` | string | 是 | 平台单独下发的**白名单管理密钥**（与 Access Key 不同，请向商务/技术支持索取） |
| `Content-Type` | string | 是 | 固定为 `application/json` |

### 3.2 请求体加密

与业务 API 调用方式一致，外层仅传 `data`：

```json
{
  "data": "<AES-128-CBC Base64 密文>"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `data` | string | 是 | 业务参数经 Access Key 加密后的 Base64 字符串 |

- 使用您账号的 **Access Key**（16 进制字符串）进行 AES 加密。
- Access Key **仅用于本地加密**，不要写入明文 JSON。
- 服务端根据请求头 `Access-Id` 查找密钥并解密；**解密成功即完成身份校验**。

### 3.3 IP 白名单

调用方出口 IP 须已加入该账号在控制台配置的 IP 白名单（与业务 API 要求一致）。未在白名单内的 IP 将返回 `1004`。

---

## 4. 业务参数（加密前明文 JSON）

创建与追加接口的明文字段相同：

```json
{
  "name": "*",
  "id_card": "350681198611130611",
  "api_codes": ["FLXG0V4B", "JRZQ8A2D"],
  "remark": "可选备注"
}
```

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 姓名；填 `*` 表示只按身份证匹配，不校验姓名 |
| `id_card` | string | 是 | 18 位中国大陆身份证号 |
| `api_codes` | string[] | 是 | 生效的产品编码列表，见下表约束 |
| `remark` | string | 否 | 备注，最长 500 字符；追加接口传入非空时会覆盖原备注 |

### 4.1 `api_codes` 约束

| 传参方式 | 是否允许 | 示例 |
|----------|----------|------|
| 字符串数组 | 允许 | `["FLXG0V4B", "JRZQ8A2D"]` |
| 单个字符串 | 不允许 | `"FLXG0V4B"` |
| 通配 `*` | 不允许 | `["*"]` |
| 空数组 | 不允许 | `[]` |
| 非字符串元素 | 不允许 | `[123]` |

---

## 5. 创建与追加的区别

同一账号下，**同一身份证号 + 同一 `name`** 仅对应**一条**规则；多个生效接口配置在该规则的 `api_codes` 数组中。

### 5.1 创建 `POST /entries`

| 情况 | 结果 |
|------|------|
| 尚无该身份证+姓名的规则 | 创建成功 |
| 规则已存在 | 失败，`1013 规则已存在`（不会自动合并） |

### 5.2 追加 `POST /entries/append`

| 情况 | 结果 |
|------|------|
| 规则已存在 | 成功；将本次 `api_codes` 与已有列表**去重合并**（保留原顺序，新编码追加在后） |
| 本次编码均已存在 | 仍返回成功（幂等），列表不变 |
| 规则不存在 | 失败，`1014 规则不存在，请先调用创建接口` |

**示例：**

```
创建：api_codes = ["FLXG0V4B"]
追加：api_codes = ["JRZQ8A2D"]
→ 合并后为 ["FLXG0V4B", "JRZQ8A2D"]（同一条规则，非新建）

再次追加：api_codes = ["JRZQ8A2D", "FLXG2E8F"]
→ ["FLXG0V4B", "JRZQ8A2D", "FLXG2E8F"]（JRZQ8A2D 已存在则跳过）
```

### 5.3 推荐流程

1. 首次配置 → 调用**创建接口**（可一次传齐全部 `api_codes`）
2. 后续增补产品 → 调用**追加接口**（只传新增编码）
3. 创建返回 `1013` → 改调**追加接口**

---

## 6. 加密算法

与业务 API 完全一致：

1. Access Key 为 16 进制字符串，解码为 16 字节 AES 密钥
2. 采用 **AES-128-CBC**，**PKCS7** 填充
3. 每次加密随机生成 16 字节 IV，置于密文前
4. IV + 密文整体做 **Base64** 编码，放入 `data`

**加密步骤：**

```
明文 JSON → AES-128-CBC 加密 → [IV(16字节) + 密文] → Base64 → 填入 data 字段
```

**解密响应 `data` 时：** 取 Base64 解码后前 16 字节为 IV，余下为密文，用同一 Access Key 解密。

---

## 7. 响应格式

HTTP 状态码均为 `200`。以响应体 `code` 判断业务是否成功。

### 7.1 外层结构

```json
{
  "code": 0,
  "message": "业务成功",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": "<AES 加密字符串>"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | `0` 表示成功，非 `0` 见错误码表 |
| `message` | string | 结果描述 |
| `transaction_id` | string | 本次请求流水号 |
| `data` | string | 成功时返回，为规则详情的 AES 密文，需用 Access Key 解密 |

### 7.2 `data` 解密后结构

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "*",
  "id_card_masked": "350681********0611",
  "api_codes": ["FLXG0V4B", "JRZQ8A2D"],
  "status": "enabled",
  "remark": "",
  "created_at": "2026-06-18T10:00:00+08:00",
  "updated_at": "2026-06-18T10:00:00+08:00"
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | string | 规则唯一标识 |
| `name` | string | 姓名规则 |
| `id_card_masked` | string | 脱敏身份证号 |
| `api_codes` | string[] | 当前生效的产品编码列表 |
| `status` | string | `enabled` 启用 / `disabled` 禁用 |
| `remark` | string | 备注 |
| `created_at` | string | 创建时间（ISO 8601） |
| `updated_at` | string | 最近更新时间（ISO 8601） |

---

## 8. 错误码

| code | message | 说明 |
|------|---------|------|
| 0 | 业务成功 | 创建或追加成功 |
| 1001 | 接口异常 | 系统内部错误 |
| 1002 | 解密失败 | `data` 无法解密 |
| 1003 | 请求参数结构不正确 | 参数缺失、格式错误或 `api_codes` 不合法 |
| 1004 | 未经授权的IP | 调用 IP 不在账号白名单 |
| 1005 | 缺少Access-Id | 未传 `Access-Id` 请求头 |
| 1006 | 未经授权的AccessId | Access-Id 无效或账号已冻结 |
| 1010 | 缺少管理密钥 | 未传 `Whitelist-Mgmt-Key` |
| 1011 | 管理密钥无效 | 管理密钥错误 |
| 1012 | 接口未开放 | 功能未对该账号/环境开放 |
| 1013 | 规则已存在 | 创建时：该身份证+姓名规则已存在 |
| 1014 | 规则不存在 | 追加时：须先调用创建接口 |

---

## 9. 调用示例（Node.js）

```javascript
const crypto = require('crypto');

const BASE_URL = 'https://api.tianyuanapi.com';
const ACCESS_ID = '您的Access-Id';
const ACCESS_KEY = '您的AccessKey';           // 16 进制，用于加解密
const MGMT_KEY = '平台下发的Whitelist-Mgmt-Key';

function encrypt(plainText, keyHex) {
  const key = Buffer.from(keyHex, 'hex');
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv('aes-128-cbc', key, iv);
  cipher.setAutoPadding(true);
  let enc = cipher.update(plainText, 'utf8');
  enc = Buffer.concat([iv, enc, cipher.final()]);
  return enc.toString('base64');
}

function decrypt(cipherBase64, keyHex) {
  const key = Buffer.from(keyHex, 'hex');
  const buf = Buffer.from(cipherBase64, 'base64');
  const iv = buf.slice(0, 16);
  const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
  decipher.setAutoPadding(true);
  let dec = decipher.update(buf.slice(16));
  dec = Buffer.concat([dec, decipher.final()]);
  return dec.toString('utf8');
}

async function callWhitelistApi(path, payload) {
  const res = await fetch(`${BASE_URL}${path}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Access-Id': ACCESS_ID,
      'Whitelist-Mgmt-Key': MGMT_KEY,
    },
    body: JSON.stringify({
      data: encrypt(JSON.stringify(payload), ACCESS_KEY),
    }),
  });
  const json = await res.json();
  if (json.code === 0 && json.data) {
    json.decrypted = JSON.parse(decrypt(json.data, ACCESS_KEY));
  }
  return json;
}

// 创建
callWhitelistApi('/api/v1/query-whitelist/entries', {
  name: '*',
  id_card: '350681198611130611',
  api_codes: ['FLXG0V4B'],
  remark: '',
}).then(console.log);

// 追加
callWhitelistApi('/api/v1/query-whitelist/entries/append', {
  name: '*',
  id_card: '350681198611130611',
  api_codes: ['JRZQ8A2D'],
}).then(console.log);
```

---

## 10. 常见问题

### `name` 填 `*` 是什么意思？

只按**身份证号**匹配。只要业务请求中的身份证与该规则一致，无论传入什么姓名，均会返回「查询为空」。

### 与业务 API 的 Access Key 是什么关系？

- **Access Key**：加密请求/响应，证明账号身份（与业务 API 相同）。
- **Whitelist-Mgmt-Key**：平台另行下发的管理授权密钥，证明有权调用白名单配置接口。

两者缺一不可。

### 调用成功后，常规 API 调用记录里能看到吗？

不能。本接口为配置类操作，不计入业务 API 调用次数，也不扣费。

### 屏蔽何时生效？

接口返回 `code = 0` 后即生效（通常数秒内）。之后该账号调用 `api_codes` 中包含的产品且入参命中身份证（及姓名规则）时，将返回 `1000 查询为空`。

---

## 11. 联系方式

- **Access-Id / Access Key**：登录控制台 → API 密钥
- **Whitelist-Mgmt-Key**：向平台商务或技术支持申请
- **IP 白名单**：登录控制台 → API 设置中配置