API 文档

快速集成TrueSignature笔迹比对API到您的应用中

快速开始
几分钟内完成集成，开始使用笔迹比对服务
1. 获取API密钥

在用户中心创建API密钥

2. 创建比对任务

调用API创建笔迹比对会话

3. 获取比对结果

查询会话状态获取结果

认证方式

所有API请求都需要在HTTP头部携带API密钥进行认证：

Authorization: Bearer sk-your-api-key-here
📝 您可以在 用户中心 创建和管理API密钥
API 端点
API基础地址：https://api.agreely.online
POST
https://api.agreely.online/api/handwriting/session/create

创建新的笔迹比对任务

请求参数

{
  "textContent": "张三",
  "similarityThreshold": 0.9,
  "returnUrl": "https://your-app.com/callback"
}

响应示例

{
  "code": 200,
  "message": "会话创建成功",
  "data": {
    "sessionId": "session_abc123",
    "handwritingUrl": "https://www.agreely.online/handwriting/session_abc123",
    "textContent": "张三",
    "similarityThreshold": 0.9,
    "status": "pending"
  }
}
GET
https://api.agreely.online/api/handwriting/session/{id}

查询会话状态和结果，如果会话已完成，返回所有字符的手写图片

响应示例（会话进行中）

{
  "code": 200,
  "message": "Session retrieved successfully",
  "data": {
    "sessionId": "session_abc123",
    "textContent": "张三",
    "status": "in_progress"
  }
}

响应示例（会话已完成）

{
  "code": 200,
  "message": "Session retrieved successfully",
  "data": {
    "sessionId": "session_abc123",
    "textContent": "张三",
    "status": "completed",
    "characters": [
      {
        "charText": "张",
        "handwrittenImageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
      },
      {
        "charText": "三",
        "handwrittenImageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
      }
    ]
  }
}
错误码说明
401API密钥无效或缺失
402积分余额不足
404会话不存在或已过期
429请求频率超限
500服务器内部错误
代码示例
不同编程语言的集成示例

JavaScript / Node.js

// 创建比对任务
const response = await fetch('https://api.agreely.online/api/handwriting/session/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk-your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    textContent: '张三',
    similarityThreshold: 0.9,
    returnUrl: 'https://your-app.com/callback'
  })
});

const result = await response.json();
console.log('Session ID:', result.sessionId);
console.log('Handwriting URL:', result.handwritingUrl);

Python

import requests

# 创建比对任务
response = requests.post(
    'https://api.agreely.online/api/handwriting/session/create',
    headers={
        'Authorization': 'Bearer sk-your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'textContent': '张三',
        'similarityThreshold': 0.9,
        'returnUrl': 'https://your-app.com/callback'
    }
)

result = response.json()
print(f"Session ID: {result['sessionId']}")
print(f"Handwriting URL: {result['handwritingUrl']}")

cURL

curl -X POST https://api.agreely.online/api/handwriting/session/create \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "textContent": "张三",
    "similarityThreshold": 0.9,
    "returnUrl": "https://your-app.com/callback"
  }'
最佳实践

安全建议

  • • 不要在前端代码中暴露API密钥
  • • 定期轮换API密钥
  • • 使用HTTPS进行所有API调用
  • • 实施适当的访问控制

性能优化

  • • 实施请求重试机制
  • • 设置合理的超时时间
  • • 避免频繁创建会话
  • • 定期查询会话状态获取结果