自定义文字证书生成 API 文档

📌 注意：本 API 仅限授权用户使用。如需接入，请联系管理员申请 API Key。

---

📩 联系方式

• 邮箱：holytreasure@163.com
• 说明：请邮件注明您的机构名称、使用场景及联系人信息，我们将为您开通专属 X-API-Key。

---

🔑 认证方式

所有请求必须在 HTTP Header 中包含有效的 API Key：

X-API-Key: your_api_key_here

⚠️ 未提供或无效的 API Key 将返回 401 Unauthorized。

---

📥 接口地址

POST https://api.holytreasure.cn/api/certificates/custom

---

📤 请求参数（JSON）

字段	类型	必填	说明	限制
activity	string	是	活动名称	最多 6 个字符（中文、英文、数字均计为 1 字）。超长部分将自动截断，并在末尾显示为 …
name	string	是	获奖人姓名	≤30 个字符
organization	string	是	颁发单位（落款）	≤30 个字符

示例请求体：

{
  "activity": "2025科技创新赛",
  "name": "张三",
  "organization": "全国青少年科技组委会"
}

✅ 有效输入示例："AI挑战赛"（5 字）、"编程马拉松"（5 字）
⚠️ 超长输入示例："2025年春季校园编程大赛" → 实际显示为：2025年春…

---

💻 前端调用方式（浏览器 JavaScript）

由于该 API 不支持 CORS（跨域资源共享），不能直接从浏览器前端（如 Vue、React、HTML 页面）调用，否则会因浏览器安全策略被拦截。

✅ 正确做法：通过你的后端代理请求

架构建议：

用户浏览器 → 你的后端服务器（如 Node.js / PHP / Python） → 本证书 API

示例（Node.js + Express 代理）：

// 你的后端路由（例如 /api/generate-certificate）
app.post('/api/generate-certificate', async (req, res) => {
  const { activity, name, organization } = req.body;

  try {
    const response = await fetch('https://api.holytreasure.cn/api/certificates/custom', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY, // 从环境变量读取，绝不暴露在前端！
        'Content-Type': 'application/json; charset=utf-8'
      },
      body: JSON.stringify({ activity, name, organization })
    });

    const data = await response.json();
    res.json(data);
  } catch (error) {
    console.error('Certificate generation failed:', error);
    res.status(500).json({ success: false, message: '证书生成失败' });
  }
});

然后前端调用自己的后端：

// 前端 JavaScript（Vue/React/原生均可）
fetch('/api/generate-certificate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    activity: "2025年春季编程赛",
    name: "李四",
    organization: "XX市教育局"
  })
})
.then(res => res.json())
.then(data => {
  if (data.success) {
    // 显示证书图片
    document.getElementById('certificate').src = data.image_url;
  } else {
    alert('生成失败：' + data.message);
  }
});

🔒 重要安全提示：

• 永远不要将 X-API-Key 写在前端代码中（包括 HTML、JS、Vue 组件等），否则会被任何人盗用。
• API Key 必须保存在你的后端服务器环境变量中，并通过后端发起请求。

---

🖥 后端 / 脚本调用示例

PowerShell（推荐用于测试）：

$body = @{
    activity      = "2025年春季编程赛"
    name          = "王五"
    organization  = "XX大学计算机学院"
} | ConvertTo-Json

$response = Invoke-RestMethod -Uri "https://api.holytreasure.cn/api/certificates/custom" `
  -Method Post `
  -Headers @{ "X-API-Key" = "your_api_key_here" } `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

Write-Output $response.image_url

cURL（Linux / Git Bash）：

curl -X POST "https://api.holytreasure.cn/api/certificates/custom" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "activity": "2025年春季编程赛",
    "name": "赵六",
    "organization": "开源社区联盟"
  }'

---

📤 响应格式

成功（HTTP 200）：

{
  "success": true,
  "activity": "2025年春…",
  "name": "赵六",
  "organization": "开源社区联盟",
  "image_url": "https://api.holytreasure.cn/certificates/custom_1712345678.png"
}

注意：activity 字段在响应中为实际渲染内容（可能含 …）

失败（HTTP 4xx / 5xx）：

{
  "success": false,
  "message": "缺少必要字段 activity"
}

---

❗ 错误码说明

状态码	原因	解决方案
401	缺失或无效 X-API-Key	联系管理员获取有效 Key
400	JSON 格式错误 / 字段缺失	检查请求体结构
500	服务器内部错误（如模板/字体缺失）	联系管理员排查

💡 当前版本不会因 activity 超长返回错误，而是自动处理，因此通常不会出现“字段超长”类 400 错误。

---

🖼 证书样式说明

• 使用官方证书模板
• 正文自动分两行显示：

  在“{activity}”活动中 {name} 同志，
  表现突出，兹授予此证书以示鼓励。

• 落款包含颁发单位与当前日期（右对齐）
• 输出格式：PNG，公开可访问 URL
• 活动名称超过 6 字时自动显示为 …，确保排版美观

---

📜 使用条款

1. 生成的证书仅可用于非商业表彰、教育或公益用途；
2. 禁止用于虚假宣传、伪造资质等违法用途；
3. 我们保留对滥用行为终止 API 权限的权利。

---

✉️ 如有疑问或需技术支持，请邮件至：holytreasure@163.com

---

• 分类： 未分类
• 标签： 无标签