真迹 API 文档

版本 1.0.1 · 基础地址：https://Rt.pandan.ltd

概述

真迹提供 RESTful API，支持第三方平台集成打章、封章、证书验证等功能。所有 API 均通过 HTTPS 传输，使用 JSON 格式。

认证方式

蓝章级别无需 API Key。银章和金章级别需要使用 API Key 进行身份验证（即将上线）。

端點列表

打章

POST/stamp

提交一个打章签名凭证

参数	类型	必填	说明
sessionId	string	必填	会话 UUID，一个创作过程对应一个 session
timestamp	string	必填	ISO 8601 时间戳
nonce	string	必填	随机数（十六进制），用于防重放攻击
signature	string	必填	Ed25519 签名（十六进制）
publicKey	string	首次	Ed25519 公钥（十六进制），首次打章必填

{
  // 请求示例
  "sessionId": "a1b2c3d4-e5f6-...",
  "timestamp": "2026-06-06T12:00:00Z",
  "nonce": "a1b2c3d4e5f6...",
  "signature": "f0e1d2c3b4a5...",
  "publicKey": "deadbeef..."
}

{
  // 响应示例
  "ok": true,
  "index": 0
}

封章

POST/seal

对一组打章记录进行封章，生成证书

参数	类型	必填	说明
sessionId	string	必填	会话 UUID
publicKey	string	必填	Ed25519 公钥
stamps	array	必填	打章记录数组
autoSeal	boolean	否	是否自动封章

{
  // 响应示例
  "certificateId": "ZJ-2026-06-06-a3f8",
  "status": "sealed",
  "chainRootHash": "abc123..."
}

查询证书

GET/certificate/{id}

获取证书的 JSON 详情

{
  "certificateId": "ZJ-2026-06-06-a3f8",
  "sessionId": "a1b2c3...",
  "stampCount": 8,
  "firstStamp": "2026-06-06T12:00:00Z",
  "lastStamp": "2026-06-06T12:47:00Z",
  "chainRootHash": "abc123...",
  "tsaTimestamp": null,
  "createdAt": "2026-06-06T12:47:30Z"
}

验证页面

GET/verify/{certificateId}

证书验证详情页（HTML），扫码后直接打开

Badge 接口

GET/badge/{certificateId}

返回证书验证徽章数据（JSON），平台方可嵌入展示

健康检查

GET/health

服务健康状况

{
  "status": "ok",
  "service": "Rt-api",
  "version": "1.0.1"
}

错误码

HTTP 400: { "error": "Missing required fields" }
HTTP 404: { "error": "Session not found" }
HTTP 409: { "error": "Duplicate stamp" }
HTTP 429: { "error": "Rate limit exceeded" }
HTTP 500: { "error": "Internal server error" }

集成示例

Node.js

const stamp = {
  sessionId: crypto.randomUUID(),
  timestamp: new Date().toISOString(),
  nonce: "f0e1d2c3b4a5...",
  signature: "deadbeef...",
  publicKey: "cafe...",
};
const res = await fetch("https://Rt.pandan.ltd/stamp", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(stamp),
});

Python

import requests, uuid, json
stamp = {
  "sessionId": str(uuid.uuid4()),
  "timestamp": "2026-06-06T12:00:00Z",
  "nonce": "a1b2c3d4...",
  "signature": "f0e1d2c3...",
  "publicKey": "deadbeef...",
}
r = requests.post("https://Rt.pandan.ltd/stamp", json=stamp)
print(r.json())