signzg-openapi-sdk/README.md

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

# signzg-openapi-sdk 使用文档

## 概述

signzg-openapi-sdk 是一个用于对接电子签名API接口的Node.js SDK，提供了简单易用的接口调用方式，支持个人认证、企业认证和合同签署等功能。本SDK封装了底层HTTP请求，使开发者能够轻松集成电子签名功能到自己的应用中。

## 安装方法

使用npm安装:

```bash
npm install signzg-openapi-sdk
```

使用yarn安装:

```bash
yarn add signzg-openapi-sdk
```

## 快速开始

### 初始化客户端

SDK提供了三种不同类型的客户端，分别用于处理个人用户、企业用户和合同签署相关的API：

```javascript
import { PersonageClient, EnterpriseClient, ContractSignClient } from 'signzg-openapi-sdk';

// 创建个人用户客户端
const personageClient = new PersonageClient({
  applicationId: 'YOUR_APPLICATION_ID', // 应用ID
  businessId: 'YOUR_BUSINESS_ID',       // 业务ID
  baseUrl: 'API_BASE_URL',              // API基础URL
  privateKeys: 'YOUR_PRIVATE_KEY',      // 私钥
  timeout: 10000,                       // 可选：请求超时时间（毫秒）
  headers: {                            // 可选：自定义请求头
    'Custom-Header': 'value'
  }
});

// 创建企业用户客户端
const enterpriseClient = new EnterpriseClient({
  applicationId: 'YOUR_APPLICATION_ID',
  businessId: 'YOUR_BUSINESS_ID',
  baseUrl: 'API_BASE_URL',
  privateKeys: 'YOUR_PRIVATE_KEY'
});

// 创建合同签署客户端
const contractSignClient = new ContractSignClient({
  applicationId: 'YOUR_APPLICATION_ID',
  businessId: 'YOUR_BUSINESS_ID',
  baseUrl: 'API_BASE_URL',
  privateKeys: 'YOUR_PRIVATE_KEY'
});
```

## 功能模块

### 1. 个人用户服务 (PersonageClient)

个人用户服务主要提供个人实名认证相关功能。

#### 1.1 获取用户信息

```javascript
// 获取用户信息
const userInfo = await personageClient.getUserInfo({
  userId: '123456' // 用户ID
});

```

#### 1.2 获取个人认证页面

```javascript
// 获取个人认证页面（H5和PC）
const authPage = await personageClient.postPersonalAuthenticationV2({
  userPhone: '13800138000' // 用户手机号
});

```

#### 1.3 查询个人实名认证结果

```javascript
const authResult = await personageClient.queryAuthenticationResult({
  userPhone: '13800138000' // 用户手机号
});
```

#### 1.4 提交个人实名认证

```javascript
const submitResult = await personageClient.submitAuthentication({
  userName: '张三',           // 用户姓名
  idNumber: '310000199001011234', // 身份证号
  phoneCode: '123456',       // 手机验证码
  userPhone: '13800138000',  // 用户手机号
  sign: 'signature'          // 签名
});
```

### 2. 企业用户服务 (EnterpriseClient)

企业用户服务主要提供企业认证相关功能。

#### 2.1 企业入驻并发送认证链接

```javascript
const enterpriseResult = await enterpriseClient.getAddEnterpriseAuthentication({
  creditCode: '91310000XXXXXXXX', // 统一社会信用代码
  legalPerson: '张三',            // 法人姓名
  legalPhone: '13800138000',     // 法人手机号
  enterpriseName: '示例企业有限公司', // 企业名称
  callbackInterfaceUrl: 'https://example.com/callback', // 认证通过回调地址
  agentName: '李四',             // 经办人姓名
  agentPhone: '13900139000'      // 经办人手机号
});
```

#### 2.2 机构实名认证

```javascript
const authResult = await enterpriseClient.enterpriseAuth({
  operatorUserIdentifier: 'OP12345', // 经办人编号（可选）
  enterpriseName: '示例企业有限公司', // 企业名称
  enterpriseCreditCode: '91310000XXXXXXXX', // 企业社会信用代码
  LegalPersonName: '张三', // 企业法人名称
  LegalPersonCard: '310000199001011234', // 企业法人身份证
  LegalPersonPhone: '13800138000', // 企业法人手机号
  LegalPersonPhoneCode: '123456', // 企业法人手机验证码
  callbackInterfaceUrl: 'https://example.com/callback', // 认证后异步回调地址（可选）
  sign: 'signature' // 签名（可选）
});
```

#### 2.3 对公打款认证

```javascript
// 填写企业信息及对公信息
const corpResult = await enterpriseClient.getCorporateAttestation({
  operatorUserIdentifier: 'OP12345', // 经办人编号（可选）
  enterpriseName: '示例企业有限公司', // 企业名称
  enterpriseCreditCode: '91310000XXXXXXXX', // 企业社会信用代码
  legalPersonName: '张三', // 企业法人名称
  legalPersonCard: '310000199001011234', // 企业法人身份证
  legalPersonPhone: '13800138000', // 企业法人手机号
  cardNo: '6222021234567890123', // 企业对公账号
  bankName: '中国工商银行', // 银行名称
  callbackInterfaceUrl: 'https://example.com/callback', // 认证后异步回调地址（可选）
  sign: 'signature' // 签名（可选）
});

// 填写打款金额完成认证
const submitResult = await enterpriseClient.getCorporateSubmitAuthentication({
  enterpriseIdentifier: 'ENT12345', // 企业编码
  remittanceMoney: 0.35, // 打款金额
  sign: 'signature' // 签名
});

```

### 3. 合同签署服务 (ContractSignClient)

合同签署服务提供合同管理和签署相关功能。

#### 3.1 发起合同签署

```javascript

const signatoryInfos = [
    {
      userName: '李四', // 签署人姓名
      userPhone: '13900139000', // 签署人电话
      type: 0, // 类型 0-个人 1-企业
      signMode: '1', // 签署印章 1用户手绘章 2用户模板章 3企业章 4合同章 5法人章
      silenceSign: '0', // 是否需要静默签：0不需要 1需要(个人不支持静默签署)
      signNumber: 'SN12345' // 签署方编号
    },
    {
      userName: '王五', // 签署人姓名
      userPhone: '13700137000', // 签署人电话
      type: 1, // 类型 0-个人 1-企业
      enterpriseName: '合作企业有限公司', // 企业名称（type=1时必传）
      signMode: '3', // 签署印章 3企业章
      silenceSign: '1', // 是否需要静默签：0不需要 1需要
      signNumber: 'SN67890' // 签署方编号
    }
  ]
const signResult = await contractSignClient.addContractSign({
  launchType: 1, // 发起类型 0-个人 1-企业
  launchSubject: '13800138000', // 发起用户手机号
  launchName: '张三', // 发起用户姓名
  launchEnterpriseName: '示例企业有限公司', // 发起企业名称(launchType为1时必传)
  contractModelNum: 'CM12345', // 模板编号
  contractName: '服务协议', // 合同名称
  signEndTime: '2023-12-31 23:59:59', // 签署截止时间
  signatoryInfos: signatoryInfos, // 签署人信息
  signatureType: 0, // 签署类型 0网页链接 1短信链接
  inputValues: [
    {
      controlNumber: 'CN12345', // 模板控件编号
      writeContent: '合同内容示例' // 填写内容
    }
  ],
  customerOriginationNumber: 'CON12345', // 客户发起时定义的编号
});
```

#### 3.2 查询合同详情

```javascript
const contractInfo = await contractSignClient.querySignInfoByContractNum({
  contractNum: 'CONTRACT_NUMBER', // 合同编号
});

```

#### 3.3 查询合同模板

```javascript
const templateList = await contractSignClient.signTemplateList({
  isOpen: '1', // 是否启用：0-否，1-是
});
```

#### 3.4 合同发起预览

```javascript
const previewResult = await contractSignClient.launchPreviewV2({
  contractModelNum: "CM12345",         // 模板编号
  inputValuesJson: JSON.stringify([    // 模板内需填写的内容列表（JSON字符串）
    {
      controlNumber: "CN12345",        // 模板控件编号
      writeContent: "合同内容示例"      // 填写内容
    }
  ]),
  controlNumber: "CN12345",            // 模板控件编号
  writeContent: "合同内容示例",         // 填写内容
  customerOriginationNumber: "CON12345" // 客户发起时定义的编号（唯一标识）
});
```   

#### 3.5 静默签署盖章

```javascript
const signResult = await contractSignClient.signContractSign({
  customerOriginationNumber: 'CON12345', // 客户发起时定义的编号
  userPhone: '13800138000' // 发起用户手机号
});
```   




## 高级用法

### 错误处理

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

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

### 自定义请求配置

每个请求方法都支持传入第二个参数来设置特定请求的配置：

```javascript
const result = await personageClient.getUserInfo(
  { userId: 123 }, 
  { 
    timeout: 5000, // 覆盖默认超时时间
    headers: {      // 添加自定义请求头
      'Custom-Request-Header': 'value'
    }
  }
);
```

## 环境要求

- Node.js >= 14.0.0
- npm >= 6.0.0 或 yarn >= 1.0.0

## 开发与构建

```bash
# 安装依赖
npm install

# 构建
npm run build

# 代码检查
npm run lint

# 运行测试
npm run test

# 生成文档
npm run docs

# 发布
npm run release
```

## 更多资源

- [API 参考文档](./API.md) - 详细的 API 参考文档
- [更新日志](./CHANGELOG.md) - 版本更新历史

## 许可证

MIT