signzg-openapi-sdk/API.md

电子签名API客户端SDK，支持个人认证、企业认证和合同签署等功能

# signzg-openapi-node-sdk API 参考文档

本文档详细介绍了 signzg-openapi-node-sdk 提供的所有 API 方法、参数和返回值。

## 目录

- [配置选项](#配置选项)
- [个人用户服务 (PersonageClient)](#个人用户服务-personageclient)
- [企业用户服务 (EnterpriseClient)](#企业用户服务-enterpriseclient)
- [合同签署服务 (ContractSignClient)](#合同签署服务-contractsignclient)
- [错误处理](#错误处理)

## 配置选项

所有客户端实例化时都需要提供配置参数：

```typescript
interface ClientConfigOptions {
   applicationId: string;   // 应用ID，必填
   businessId: string;      // 业务ID，必填
   baseUrl: string;         // API基础URL，必填
   timeout?: number;        // 请求超时时间（毫秒），可选，默认10000
   headers?: Record<string, string>; // 自定义请求头，可选
}
```

## 个人用户服务 (PersonageClient)

### 实例化

```javascript
import { PersonageClient } from 'signzg-openapi-node-sdk';

const personageClient = new PersonageClient({
  applicationId: 'YOUR_APPLICATION_ID',
  businessId: 'YOUR_BUSINESS_ID',
  baseUrl: 'API_BASE_URL'
});
```

### 方法

#### getUserInfo

获取用户信息。

```typescript
async getUserInfo(params: GetUserInfoParams): Promise<ApiResult>
```

**参数**:
- `params.userId`: 用户ID，必填参数，用于指定要查询的用户
- `params.includeFields`: 可选，指定要返回的字段，多个字段用逗号分隔
- `params.includeVerification`: 可选，是否包含用户认证信息
- `params.includeSignatures`: 可选，是否包含用户签名信息

**返回值**:
返回用户信息对象，包含以下字段：
- `userId`: 用户ID
- `name`: 用户姓名
- `gender`: 用户性别，可能值：'MALE'|'FEMALE'|'OTHER'
- `birthDate`: 出生日期（可选）
- `idCardNumber`: 身份证号码
- `phoneNumber`: 手机号码
- `email`: 电子邮件（可选）
- `address`: 地址（可选）
- `avatar`: 头像URL（可选）
- `registerTime`: 注册时间
- `lastLoginTime`: 最后登录时间（可选）

**示例**:
```javascript
const userInfo = await personageClient.getUserInfo({
  userId: '123456',
  includeVerification: true,
  includeSignatures: true
});
```

#### postPersonalAuthenticationV2

获取个人认证页面接口（H5 和 PC）。

```typescript
async postPersonalAuthenticationV2(params: { userPhone: string; [key: string]: any }): Promise<any>
```

**参数**:
- `params.userPhone`: 用户手机号，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回认证页面相关信息

**示例**:
```javascript
const authPage = await personageClient.postPersonalAuthenticationV2({
  userPhone: '13800138000'
});
```

#### queryAuthenticationResult

个人实名信息认证结果查询。

```typescript
async queryAuthenticationResult(params: { userPhone: string; [key: string]: any }): Promise<any>
```

**参数**:
- `params.userPhone`: 用户手机号，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回认证结果信息

**示例**:
```javascript
const authResult = await personageClient.queryAuthenticationResult({
  userPhone: '13800138000'
});
```

#### submitAuthentication

个人实名认证接口。

```typescript
async submitAuthentication(params: { 
  userName: string;
  idNumber: string;
  phoneCode: string;
  userPhone: string;
  sign: string;
  [key: string]: any 
}): Promise<any>
```

**参数**:
- `params.userName`: 用户姓名，必填
- `params.idNumber`: 身份证号，必填
- `params.phoneCode`: 手机验证码，必填
- `params.userPhone`: 用户手机号，必填
- `params.sign`: 签名，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回认证提交结果

**示例**:
```javascript
const submitResult = await personageClient.submitAuthentication({
  userName: '张三',
  idNumber: '310000199001011234',
  phoneCode: '123456',
  userPhone: '13800138000',
  sign: 'signature'
});
```

## 企业用户服务 (EnterpriseClient)

### 实例化

```javascript
import { EnterpriseClient } from 'signzg-openapi-node-sdk';

const enterpriseClient = new EnterpriseClient({
  applicationId: 'YOUR_APPLICATION_ID',
  businessId: 'YOUR_BUSINESS_ID',
  baseUrl: 'API_BASE_URL'
});
```

### 方法

#### getAddEnterpriseAuthentication

企业入驻并发送认证链接。

```typescript
getAddEnterpriseAuthentication(params: {
  creditCode: string;
  legalPerson: string;
  legalPhone: string;
  callbackInterfaceUrl: string;
  agentName: string;
  agentPhone: string;
  enterpriseName: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.creditCode`: 企业统一社会信用码，必填
- `params.legalPerson`: 企业法人名称，必填
- `params.legalPhone`: 企业法人手机号，必填
- `params.callbackInterfaceUrl`: 企业认证通过回调地址，必填
- `params.agentName`: 经办人姓名，必填
- `params.agentPhone`: 经办人手机号，必填
- `params.enterpriseName`: 企业名称，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回企业认证相关信息

**示例**:
```javascript
const enterpriseResult = await enterpriseClient.getAddEnterpriseAuthentication({
  creditCode: '91310000XXXXXXXX',
  legalPerson: '张三',
  legalPhone: '13800138000',
  enterpriseName: '示例企业有限公司',
  callbackInterfaceUrl: 'https://example.com/callback',
  agentName: '李四',
  agentPhone: '13900139000'
});
```

## 合同签署服务 (ContractSignClient)

### 实例化

```javascript
import { ContractSignClient } from 'signzg-openapi-node-sdk';

const contractSignClient = new ContractSignClient({
  applicationId: 'YOUR_APPLICATION_ID',
  businessId: 'YOUR_BUSINESS_ID',
  baseUrl: 'API_BASE_URL'
});
```

### 方法

#### addContractSign

指定签署方和签署内容发起签署。

```typescript
addContractSign(params: Record<string, any>): Promise<any>
```

**参数**:
- `params`: 合同签署相关参数

**返回值**:
- 返回合同签署结果

**示例**:
```javascript
const signResult = await contractSignClient.addContractSign({
  // 合同签署相关参数
});
```

#### createContractSign

发起合同签署（静默签）。

```typescript
createContractSign(params: Record<string, any>): Promise<any>
```

**参数**:
- `params`: 静默签署相关参数

**返回值**:
- 返回静默签署结果

**示例**:
```javascript
const directSignResult = await contractSignClient.createContractSign({
  // 静默签署相关参数
});
```

#### withdrawContract

撤回合同。

```typescript
withdrawContract(params: {
  contractNum: string;
  userPhone: string;
  withdrawReason: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractNum`: 合同编号，必填
- `params.userPhone`: 用户手机号，必填
- `params.withdrawReason`: 撤回原因，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回合同撤回结果

**示例**:
```javascript
const withdrawResult = await contractSignClient.withdrawContract({
  contractNum: 'CONTRACT_NUMBER',
  userPhone: '13800138000',
  withdrawReason: '合同信息有误，需要修改'
});
```

#### cancelContract

解约合同。

```typescript
cancelContract(params: {
  contractNum: string;
  userPhone: string;
  relieveReason: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractNum`: 合同编号，必填
- `params.userPhone`: 用户手机号，必填
- `params.relieveReason`: 解约原因，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回合同解约结果

**示例**:
```javascript
const cancelResult = await contractSignClient.cancelContract({
  contractNum: 'CONTRACT_NUMBER',
  userPhone: '13800138000',
  relieveReason: '双方协商一致解约'
});
```

#### agreeCancelContract

同意解约合同。

```typescript
agreeCancelContract(params: {
  contractNum: string;
  userPhone: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractNum`: 合同编号，必填
- `params.userPhone`: 用户手机号，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回同意解约结果

**示例**:
```javascript
const agreeResult = await contractSignClient.agreeCancelContract({
  contractNum: 'CONTRACT_NUMBER',
  userPhone: '13800138000'
});
```

#### refuseCancelContract

拒绝解约合同。

```typescript
refuseCancelContract(params: {
  contractNum: string;
  userPhone: string;
  refuseReason: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractNum`: 合同编号，必填
- `params.userPhone`: 用户手机号，必填
- `params.refuseReason`: 拒绝解约原因，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回拒绝解约结果

**示例**:
```javascript
const refuseResult = await contractSignClient.refuseCancelContract({
  contractNum: 'CONTRACT_NUMBER',
  userPhone: '13800138000',
  refuseReason: '不同意解约原因'
});
```

#### signTemplateList

查询合同模板。

```typescript
signTemplateList(data: {
  isOpen?: '0' | '1';
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `data.isOpen`: 是否启用：0-否，1-是，可选
- `data.[key: string]`: 其他可选参数

**返回值**:
- 返回合同模板列表

**示例**:
```javascript
const templateList = await contractSignClient.signTemplateList({
  isOpen: '1'
});
```

#### launchPreview

合同发起预览填。

```typescript
launchPreview(params: {
  launchType: '0' | '1' | 0 | 1;
  launchSubject: string;
  launchEnterpriseName?: string;
  signEnterpriseName: string;
  contractModelNum: string;
  contractName: string;
  inputValues: string;
  customerOriginationNumber: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.launchType`: 发起类型：0-个人，1-企业，必填
- `params.launchSubject`: 发起用户手机号，必填
- `params.launchEnterpriseName`: 发起企业名称（launchType为1时必传），可选
- `params.signEnterpriseName`: 静默签署企业名，必填
- `params.contractModelNum`: 模板编号，必填
- `params.contractName`: 合同名称，必填
- `params.inputValues`: 模板填写内容（多个值用逗号分隔，按文档填写框顺序对应），必填
- `params.customerOriginationNumber`: 客户定义的发起编号，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回预览数据

**示例**:
```javascript
const previewResult = await contractSignClient.launchPreview({
  launchType: '0',
  launchSubject: '13800138000',
  signEnterpriseName: '签署企业名称',
  contractModelNum: 'TEMPLATE_NUMBER',
  contractName: '示例合同',
  inputValues: '值1,值2,值3',
  customerOriginationNumber: 'CUSTOM_NUMBER'
});
```

#### signTemplateDetails

查询模板详情。

```typescript
signTemplateDetails(params: {
  contractModelNum: string;
  sign: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractModelNum`: 模板编号，必填
- `params.sign`: 签名，必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回模板详情

**示例**:
```javascript
const templateDetails = await contractSignClient.signTemplateDetails({
  contractModelNum: 'TEMPLATE_NUMBER',
  sign: 'signature'
});
```

#### launchPreviewV2

合同发起预览填（V2版本）。

```typescript
launchPreviewV2(params: {
  contractModelNum: string;
  inputValuesJson: string;
  controlNumber: string;
  writeContent: string;
  customerOriginationNumber: string;
  [key: string]: any;
}): Promise<any>
```

**参数**:
- `params.contractModelNum`: 模板编号，必填
- `params.inputValuesJson`: 模板内需填写的内容列表（JSON字符串），必填
- `params.controlNumber`: 模板控件编号，必填
- `params.writeContent`: 填写内容，必填
- `params.customerOriginationNumber`: 客户发起时定义的编号（唯一标识），必填
- `params.[key: string]`: 其他可选参数

**返回值**:
- 返回预览数据

**示例**:
```javascript
const previewResult = await contractSignClient.launchPreviewV2({
  contractModelNum: 'TEMPLATE_NUMBER',
  inputValuesJson: JSON.stringify([{
    controlNumber: 'CONTROL_1',
    writeContent: '内容1'
  }]),
  controlNumber: 'CONTROL_1',
  writeContent: '内容1',
  customerOriginationNumber: 'CUSTOM_NUMBER'
});
```

## 错误处理

SDK 内部会对常见的 HTTP 错误进行处理，但建议在调用 API 时使用 try/catch 进行错误捕获：

```javascript
try {
  const result = await personageClient.getUserInfo({ /* 参数 */ });
  // 处理成功响应
} catch (error) {
  console.error('API 调用失败:', error.message);
  // 处理错误
}
```

错误类型包括：
- 401: 授权失败，需要重新登录
- 403: 没有权限访问该资源
- 404: 请求的资源不存在
- 500: 服务器内部错误
- 网络错误: API无响应，请检查网络连接
- 请求配置错误: 请求参数或配置有误