凭证中台对接文档

## 1. 概述

本文档介绍如何对接凭证中台，实现凭证任务的提交、回调处理等功能。凭证中台提供凭证生成、管理、查询等能力，业务系统通过HTTP接口与中台进行交互。

## 2. 配置说明

在业务系统的配置文件中添加以下配置：

```yaml
certificate:
  # 凭证中台认证地址
  auth-url: http://172.16.10.5:49999/auth/oauth2/token
  # 凭证中台客户端ID，由中台分配
  auth-username: your_client_id
  # 凭证中台客户端密钥，由中台分配
  auth-password: your_client_secret
  # 凭证任务提交地址
  submit-url: http://172.16.10.5:49999/cert/task/submit
  # 凭证任务模板代码，由中台分配
  template-code: CERT_TEMPLATE_001
  # 凭证任务回调地址，业务系统提供（如不需要回调可传空字符串或null）
  callback-url: https://your-system.com/notify/certificateTask/callback
  # 中台通讯AES密钥，由中台分配
  aes-key: your_aes_key_32bytes
```

## 3. 接口说明

### 3.1 获取认证Token

**接口地址：** `certificate.auth-url`

**请求方式：** POST

**认证方式：** Basic Auth

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| grant_type | String | 是 | 固定值：client_credentials |

**响应示例：**

```json
{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}
```

### 3.2 提交凭证任务

**接口地址：** `certificate.submit-url`

**请求方式：** POST

**请求头：**

| Header名 | 类型 | 必填 | 说明 |
|----------|------|------|------|
| Authorization | String | 是 | 认证Token，格式：`Bearer {token}` |
| Content-Type | String | 是 | 固定值：`application/octet-stream` |
| X-Request-Time | String | 是 | 请求时间戳（毫秒） |
| X-Sign | String | 是 | 请求签名 |

**请求体（加密前）：**

```json
{
  "templateCode": "CERT_TEMPLATE_001",
  "requestData": {
    "businessIdentify": "ORDER_20240101001",
    "customerName": "张三",
    "amount": 10000.00,
    "orderDate": "2024-01-01"
  },
  "callbackUrl": "https://your-system.com/notify/certificateTask/callback",
  "initiatorName": "李四",
  "initiatorMobile": "13800138000"
}
```

**请求体字段说明：**

| 字段名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| templateCode | String | 是 | 凭证模板编码 |
| requestData | JsonNode | 是 | 请求数据（账单或凭证的快照数据） |
| callbackUrl | String | 否 | 回调地址 |
| initiatorName | String | 否 | 发起人名称（客户经理姓名） |
| initiatorMobile | String | 否 | 发起人手机（客户经理手机号） |

**注意事项：**
- `requestData`中不能包含`时间戳`相关参数，相同参数但时间戳不同的凭证会失去唯一性
- 如需使用中台对账功能，需要在`requestData`中指定`businessIdentify`字段作为业务唯一标识

**响应示例（解密后）：**

```json
{
    "code": 0,
    "msg": null,
    "data": null,
    "requestId": "1995669670298464256",
    "ok": true
}
```

### 3.3 凭证任务回调

**接口地址：** 业务系统提供的回调地址

**请求方式：** POST

**请求头：**

| Header名 | 类型 | 必填 | 说明 |
|----------|------|------|------|
| Content-Type | String | 是 | 固定值：`application/octet-stream` |

**请求体（解密后）：**

```json
{
  "id": "1991031895215308802",
  "trackId": "1991031891446943744",
  "templateCode": "wxPayOrderCertificate_19613189488383xxxxx",
  "requestData": {
    "successTime": "2025-08-15 08:49:28",
    "outTradeNo": "20250815208xxx",
    "openid": "oJsiGwIEQ9kJPGBwK49VSgFf6xxx",
    "nickname": "戴xx",
    "subMchid": "1665545xxx",
    "merchantName": "湖南豆秒汽车服务有限公司",
    "amount": "1000.00",
    "amountToChinese": "壹仟元整",
    "description": "戴xx,************297030,还海南豆秒融资担保有限公司",
    "businessIdentify": "20250815208557",
  },
  "certificateCode": "c4b735ee899d72ed333384f9fcb920aed63fbeb1b75e6196955956c3da61a6de3e01d0cf6651ccdd5072",
  "certificatePdfUrl": "https://wwobs-test.obs.cn-north-4.myhuaweicloud.com/certificate/202511/c4b735ee899d72ed333384f9fcb920aed63fbeb1b75e6196955956c3da61a6de3e01d0cf6651ccdd5072/34e141bc373d4864a54558a1157ec0c4_20251118103354.pdf",
  "callbackUrl": "http://localhost:9996/pay/notify/certificateTask/callback",
  "clientId": "Ww827b97c1ca3e47469039c436f40xxxxx",
  "status": "COMPLETED",
  "failedReason": null,
  "initiatorName": null,
  "initiatorMobile": null,
  "createTime": "2025-11-19 14:32:50"
}
```

**回调字段说明：**

| 字段名 | 类型 | 说明 |
|--------|------|------|
| trackId | String | 跟踪ID（提交任务时返回的requestId） |
| certificateCode | String | 凭证编码 |
| certificatePdfUrl | String | 凭证PDF地址 |
| status | String | 状态：PENDING/PROCESSING/COMPLETED/FAILED |
| failedReason | String | 失败原因（仅失败时有值） |

## 4. 数据结构

### 4.1 任务实体（Task）

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 主键ID |
| trackId | String | 请求ID |
| templateCode | String | 模板编码 |
| requestData | JsonNode | 请求数据 |
| certificateCode | String | 证书编码 |
| certificatePdfUrl | String | 凭证地址 |
| status | Status | 状态 |
| failedReason | String | 失败原因 |
| initiatorName | String | 发起人名称 |
| initiatorMobile | String | 发起人手机 |
| createTime | LocalDateTime | 创建时间 |
| updateTime | LocalDateTime | 更新时间 |

**状态枚举（Status）：**

| 枚举值 | 说明 |
|--------|------|
| PENDING | 待处理 |
| PROCESSING | 处理中 |
| COMPLETED | 处理完成 |
| FAILED | 处理失败 |

## 5. 加密机制

### 5.1 加密算法

凭证中台支持AES和RSA两种加密算法，推荐使用AES。

### 5.2 签名生成规则

签名生成步骤：

1. 对Query参数进行MD5哈希（如有）
2. 对请求体进行MD5哈希
3. 合并两个哈希结果
4. 对合并结果再次进行MD5
5. 将结果转为Hex字符串，拼接请求时间戳和客户端ID
6. 使用加密算法对拼接字符串进行加密

### 5.3 请求流程

1. 获取认证Token（建议缓存到Redis，有效期-60秒）
2. 组装请求数据
3. 生成请求时间戳
4. 生成签名
5. 加密请求体
6. 发送请求
7. 解密响应

## 6. 示例代码

[【附件】example.zip](/media/attachment/2026/01/example.zip)

## 7. 注意事项

1. **异步处理**：建议将凭证任务提交方法设置为异步或使用try-catch捕获异常，避免偶发异常影响原业务

2. **Token缓存**：认证Token建议缓存到Redis，有效期设置为`expires_in - 60`秒，避免频繁请求认证接口

3. **时间戳处理**：`requestData`中不能包含`时间戳`相关参数，相同参数但时间戳不同的凭证会失去唯一性

4. **业务唯一标识**：如需使用中台对账功能，需要在`requestData`中指定`businessIdentify`字段作为业务唯一标识

5. **回调地址**：如不需要回调，`callbackUrl`参数可传空字符串或null

6. **超时设置**：建议设置合理的请求超时时间（如20秒）

7. **异常处理**：建议对凭证任务提交过程进行异常捕获和日志记录，便于问题排查

8. **数据一致性**：建议在业务系统中维护任务状态，通过回调更新任务状态和凭证信息