API接口调用详解 - 开放签电子签百科

API基础概念

什么是API？

API（Application Programming Interface）是应用程序编程接口，为不同软件系统之间的通信提供了标准化的方式。在开放签平台中，API允许您的应用程序通过编程方式使用电子签名服务。

核心特性：

RESTful架构设计
JSON数据格式
HTTP/HTTPS协议
标准状态码返回

API工作原理

1 客户端发起HTTP请求

2 服务器验证请求合法性

3 处理业务逻辑

4 返回JSON格式响应

开放签API接口概览

📡 API基础信息

API地址：

https://api.kaifangqian.com/v1/

数据格式：

application/json

字符编码：

UTF-8

协议支持：

HTTPS (推荐)

🔧 核心API接口

POST /documents/sign

创建签署任务

创建新的文档签署任务，支持单个或批量签署

主要参数：

document_name - 文档名称
signers - 签署人信息
template_id - 模板ID
callback_url - 回调地址

响应示例：

{"code": 0, "data": {"task_id": "12345", "sign_url": "https://..."}}

GET /documents/sign/{task_id}/status

查询签署状态

查询指定签署任务的当前状态和进度

返回状态：

pending - 待签署
signing - 签署中
completed - 已完成
cancelled - 已取消

响应数据：

{"code": 0, "data": {"status": "completed", "signers": [...]}}

GET /documents/sign/{task_id}/download

下载签署文件

下载完成签署的文档文件，支持PDF和ZIP格式

请求参数：

format - 文件格式（pdf/zip）
watermark - 是否添加水印

返回内容：

二进制文件流，需正确处理Content-Type

POST /auth/token

获取访问令牌

通过API密钥获取访问令牌，用于后续API调用

认证方式：

API Key认证
Bearer Token
OAuth 2.0

令牌有效期：

默认2小时，需在过期前刷新

API认证方式

API Key认证（推荐）

使用方法：

在开放签控制台获取API Key
在请求Header中添加认证信息
使用Bearer Token方式传递

curl -H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
https://api.kaifangqian.com/v1/documents/sign

安全特性：

256位AES加密
IP白名单限制
请求频率限制
完整的访问日志

注意事项：请妥善保管API Key，避免在客户端代码中暴露。

HMAC签名认证

使用HMAC-SHA256算法对请求进行签名，确保请求完整性和防篡改。

签名参数：

timestamp - 请求时间戳
nonce - 随机字符串
signature - HMAC签名

signature = HMAC-SHA256(
secret_key,
method + url + timestamp + nonce
)

优势特点：

防止请求篡改
抵御重放攻击
时间窗口验证
适合高安全场景

请求参数详解

📋 通用参数

参数名	类型	必填	说明
timestamp	number	是	Unix时间戳，秒级
format	string	否	响应格式，支持json/xml
language	string	否	国际化语言，zh-CN/en-US
version	string	否	API版本号

📄 创建签署任务参数详解

基础文档信息：

document_name

文档名称，支持中文，最大100字符

document_content

文档内容，Base64编码的文件内容

document_type

文档类型：pdf/doc/docx/html

签署人配置：

signers[].name

签署人姓名，最大50字符

signers[].email

签署人邮箱，用于接收签署通知

signers[].phone

手机号，用于短信验证

完整请求示例：

{
  "document_name": "企业合同签署.pdf",
  "document_content": "data:application/pdf;base64,JVBERi0xLjQKJcTl8uXrp/Og0MTGCjEgMCBvYmoKPDwKL1R5cGUgL0NhdGFsb2cKL1BhZ2VzIDIgMCBSCj4+CmVuZG9iago...",
  "document_type": "pdf",
  "signers": [
    {
      "name": "张三",
      "email": "zhangsan@example.com",
      "phone": "13800138000",
      "order": 1,
      "sign_fields": [
        {
          "field_name": "签名",
          "field_type": "signature",
          "x": 100,
          "y": 200,
          "width": 200,
          "height": 50
        },
        {
          "field_name": "日期",
          "field_type": "date",
          "x": 320,
          "y": 200,
          "width": 120,
          "height": 30
        }
      ]
    }
  ],
  "callback_url": "https://your-app.com/webhook/sign-result",
  "expire_time": 86400
}

API响应格式

📊 标准响应格式

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": "2024011500001",
    "sign_url": "https://sign.kaifangqian.com/...",
    "expire_time": 1642243200
  },
  "timestamp": 1642240000,
  "request_id": "req_abc123"
}

错误响应：

{
  "code": 40001,
  "message": "参数验证失败",
  "data": null,
  "errors": [
    {
      "field": "email",
      "message": "邮箱格式不正确"
    }
  ],
  "timestamp": 1642240000,
  "request_id": "req_def456"
}

📋 HTTP状态码说明

HTTP状态码	业务状态码	说明	解决方案
200	0	请求成功	正常处理响应数据
400	4xxxx	请求参数错误	检查请求参数格式和必填项
401	40101	认证失败	检查API Key或签名
403	40301	权限不足	检查账号权限和配额
429	42901	请求频率超限	降低请求频率或申请扩容
500	5xxxx	服务器内部错误	联系技术支持

错误处理与重试机制

⚠️ 常见错误类型

认证错误：

40101 - API Key无效

检查API Key是否正确，是否过期

40102 - 签名验证失败

检查HMAC签名算法和密钥

参数错误：

40001 - 必填参数缺失

检查API文档中的必填参数

40002 - 参数格式错误

检查数据类型和格式要求

🔄 智能重试机制

重试策略：

网络超时：指数退避重试（1s, 2s, 4s, 8s）
服务器错误（5xx）：最大重试3次
认证错误（401/403）：不重试，检查认证信息
参数错误（4xx）：不重试，修正参数后重发

最佳实践：实现指数退避算法，避免对服务器造成过大压力。

重试示例代码：

def call_api_with_retry(api_func, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            return api_func()
        except APIError as e:
            if e.code in [401, 403]:
                raise e  # 不重试认证错误
            if attempt == max_retries:
                raise e
            time.sleep(2 ** attempt)

API调用最佳实践

性能优化建议

请求优化：

使用连接池减少TCP连接开销
启用HTTP/2支持多路复用
合理设置请求超时时间
批量操作减少API调用次数

响应优化：

使用缓存减少重复请求
异步处理非关键业务逻辑
合理使用分页查询
压缩传输数据减小带宽

安全最佳实践

密钥管理：

API Key不在客户端代码中暴露
定期轮换API Key
使用环境变量存储敏感信息
实施最小权限原则

传输安全：

强制使用HTTPS协议
验证SSL证书有效性
使用HMAC签名防篡改
实施请求限流保护

监控和日志记录

关键指标监控：

API响应时间和成功率
错误率和错误类型分布
请求频率和并发量
用户使用模式分析

日志记录策略：

记录完整的请求和响应
敏感信息脱敏处理
结构化日志格式
按重要性设置日志级别

SDK集成和代码示例

📦 支持的SDK语言

Python

pip install kaifangqian

Java

Maven/Gradle

Node.js

npm install kaifangqian

PHP

Composer

🐍 Python SDK使用示例

# 安装SDK
pip install kaifangqian

# 初始化客户端
from kaifangqian import OpenSignClient

client = OpenSignClient(
    api_key="your_api_key",
    api_secret="your_api_secret"
)

# 创建签署任务
task = client.create_sign_task(
    document_name="企业合同.pdf",
    document_content="base64_encoded_content",
    signers=[
        {
            "name": "张三",
            "email": "zhangsan@example.com",
            "phone": "13800138000"
        }
    ]
)

print(f"签署链接: {task.sign_url}")

# 查询签署状态
status = client.get_sign_status(task.task_id)
print(f"签署状态: {status.status}")

常见问题解答

Q: API调用频率有什么限制？

A: 标准版API限制为每分钟100次请求，企业版可申请更高的并发限制。如需提升限制，请联系客服进行商务洽谈。

Q: 如何处理文件上传大小限制？

A: 单个文档大小限制为10MB。如果需要处理更大的文档，建议使用分片上传功能或先将文档上传到云存储，然后在API中引用文档URL。

Q: API支持批量操作吗？

A: 是的，开放签API支持批量创建签署任务，一次性处理最多100个文档。这大大提高了批量电子签的效率。

Q: 如何实现API的回调通知？

A: 在创建签署任务时设置callback_url参数，开放签会在状态变更时主动通知您的服务器。支持签名验证以确保回调的真实性。

Q: API是否支持Webhook推送？

A: 支持。系统会在签署完成、失败、超时等关键事件发生时自动推送Webhook通知到您指定的URL。Webhook包含完整的事件信息和相关数据。