
## 说明

### 1. **API 概述**
Clear Junction 的 API 旨在让你的组织能够无缝对接其各类金融产品。通过这个API，你可以实现：
- 实时支付处理服务（如SEPA、SWIFT、FPS等多种国际支付通道）
- 给客户提供虚拟IBAN（vIBAN）服务
- 多币种国际结算能力

API 是基于 REST 架构，使用 HTTPS 通道，消息格式为 JSON。

---

### 2. **账户类型**
Clear Junction 目前提供四种账户类型：
1. **Current Account（活期账户）**
2. **Collection Account（收款账户）**
3. **Correspondent Account（代理账户）**
4. **E-money Account（电子货币账户）**

根据你的业务需求和资质，还可能开通 vIBAN（虚拟IBAN）或 Wallet（电子钱包）等功能。

---

### 3. **认证方式**
API 使用自定义的认证流程，基于 API Key。请求时需在 HTTP Header 中传递以下信息：

| Header         | 说明                              |
|---------------|-----------------------------------|
| Date          | 发送请求时客户端服务器的时间       |
| X-API-KEY     | API 用户标识（uuid），由CJ提供     |
| Authorization | 请求签名，用于验证请求的合法性      |

#### **签名计算流程**
- 签名（REQUEST SIGNATURE）由 X-API-KEY、Date、RequestBody 和一个只有你知道的 apiPassword（API 密码）生成。
- 服务器会用相同方式校验签名，若不一致则拒绝请求。

---

### 4. **HTTP 响应码说明**
| 状态码 | 说明                                   |
|-------|----------------------------------------|
| 200   | 请求成功                               |
| 201   | 已创建新实体（如新账户、交易等）        |
| 400   | 请求参数有误，无法处理                  |
| 401   | 未通过认证（签名校验未通过）            |
| 404   | 找不到资源（如账户/交易不存在）         |
| 409   | 请求体校验错误（缺字段、日期格式错误等）|
| 500   | 服务器内部错误                         |

#### 错误信息
- 除了 HTTP 状态码外，响应体还会有详细的 JSON 格式错误对象列表，说明具体出错原因。

---

### **总结理解**
- Clear Junction API 主要用于国际支付、收款、账户管理等金融服务的系统接口。
- 接口安全性高，采用 API Key + 自定义签名机制进行认证。
- 支持多种国际支付通道和多种账户类型，响应和错误处理机制清晰。
- 适合金融科技、跨境支付、企业财务等场景。

如果你要对接这个API，重点需要明白认证方式和如何生成签名，以及如何处理各种返回结果和异常。


## 接入示例

![[Pasted image 20250511184143.png]]

API调用方与Clear Junction服务器之间的认证步骤。具体流程如下：

1. **Client（客户端）** 发送API请求到 **Clear Junction**，在请求头中包含：
   - **Date**
   - **X-API-KEY**
   - **Authorization**（签名）

2. **Clear Junction** 服务器接收到请求后，会用相同的签名生成算法（基于 X-API-KEY、Date、RequestBody、apiPassword）来计算签名。

3. 服务器将自己生成的签名与客户端请求头中的 **Authorization** 签名进行对比。

4. 如果签名一致，认证通过，请求被处理。
   - 如果签名不一致，返回401 Unauthorized（未授权）错误。


当然可以！下面是用 Node.js 实现 Clear Junction API 认证签名生成和请求的完整示例。

### 假设
- 你已获得 `xApiKey`（API用户标识, uuid）
- 你有分配的 `apiPassword`（API 密码）
- 你要向 Clear Junction 某个接口（比如 `https://api.clearjunction.com/v1/example`）发起 POST 请求，带有 JSON 请求体

---

## 1. 安装依赖

```bash
npm install axios crypto
```

---

## 2. 签名算法实现

根据说明，签名是基于 `X-API-KEY`, `Date`, `RequestBody`, 和 `apiPassword` 组合计算的。具体算法未给出，通常如下：

- 将这些参数按指定顺序拼接为字符串
- 用 `apiPassword` 进行 HMAC-SHA256 加密
- 将结果作为 Authorization header

**⚠️ 实际算法以官方文档为准，以下为常见实现方式，供参考。**

---

## 3. 完整代码示例

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

// 参数（请替换为你的实际值）
const xApiKey = 'your-x-api-key-uuid';
const apiPassword = 'your-api-password';
const url = 'https://api.clearjunction.com/v1/example';

// 请求体
const requestBody = {
  // 你的请求内容
  amount: 100,
  currency: 'EUR',
  beneficiary: 'example'
};

// 当前时间，格式为 HTTP 标准时间字符串
const date = new Date().toUTCString();

// 1. 生成签名字符串（具体顺序和分隔符请参考官方文档，这里假设为直接拼接）
const stringToSign = xApiKey + date + JSON.stringify(requestBody) + apiPassword;

// 2. 计算 HMAC-SHA256 签名
const signature = crypto
  .createHmac('sha256', apiPassword)
  .update(stringToSign)
  .digest('hex');

// 3. 组装请求头
const headers = {
  'Content-Type': 'application/json',
  'Date': date,
  'X-API-KEY': xApiKey,
  'Authorization': signature
};

// 4. 发送请求
axios.post(url, requestBody, { headers })
  .then(response => {
    console.log('Response:', response.data);
  })
  .catch(error => {
    if (error.response) {
      console.error('Error:', error.response.status, error.response.data);
    } else {
      console.error('Error:', error.message);
    }
  });
```

---

## 说明

- **stringToSign** 的拼接顺序和方式需要根据 Clear Junction 官方文档确认，这里是常见做法。
- **crypto.createHmac('sha256', apiPassword)** 用于生成 HMAC-SHA256 签名。
- **Date** 头需为标准 HTTP 时间字符串（如 `Wed, 12 Jun 2024 09:00:00 GMT`）。
- **Authorization** 头为最终的签名值。