徽章 API 参考：创建、验证与获取徽章

管理徽章模板——即你颁发给接收者的凭证。

如需通过上传 CSV 而不是 API 来一次性向多名接收者颁发此徽章，请参阅 批量凭证。

所有端点都需要通过 X-Api-Key 请求头进行身份验证。参见 身份验证。

创建徽章

在已验证的颁发者下创建新徽章。

POST /badges

参数

参数	类型	必填	说明
name	string	是	徽章标题
description	string	是	徽章所代表的含义
criteria	string	是	接收者为获得此徽章所做的事情
image	string	是	Base64 编码的图片（PNG 或 JPG）
issuerId	string	是	已验证颁发者的 ID
shareText	string	否	此徽章默认的社交分享文本。支持 、 和 占位符。省略时使用内置默认文本。
designJson	string	否	序列化的徽章设计器文档，保存后可在以后逐层重新编辑徽章。

示例

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

响应

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

说明

• 创建徽章之前，颁发者必须已通过验证。
• 图片存储在 Amazon S3 上，并通过我们的全球 CDN 以不可变的、基于内容寻址的 URL 提供。
• 徽章类创建完成后，请使用 凭证 API 将其颁发给接收者。

---

列出徽章

获取你创建的所有徽章。

GET /badges

示例

curl -X GET https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here"

响应

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

获取徽章

获取单个徽章，包括其分享文本和序列化的徽章设计器文档（designJson）。编辑徽章弹窗正是通过此端点还原各个图层；列表端点会省略 designJson，以保持响应精简。

GET /badges/{badgeId}

参数

参数	类型	必填	说明
badgeId	string	是	徽章 ID（路径参数）

示例

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

响应

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

分享文本始终会包含在内。较轻量的列表变体 GET /badges?badgeId={id} 返回相同的文档但不含 designJson，并且仅在使用 includeShareText=true 调用时才包含分享文本。

---

更新徽章

更新现有徽章。只有你提供的字段会被修改。

PUT /badges/{badgeId}

参数

参数	类型	必填	说明
badgeId	string	是	徽章 ID（路径参数）
name	string	否	新的徽章标题
description	string	否	新的描述
criteria	string	否	新的标准
image	string	否	新的 Base64 编码图片
designJson	string	否	新的序列化徽章设计器文档。

示例

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

响应

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

更新分享文本

设置接收者在社交媒体上分享此徽章时显示的自定义文本。

PUT /badges/{badgeId}/share-text

参数

参数	类型	必填	说明
badgeId	string	是	徽章 ID（路径参数）
text	string	是	分享文本（不允许 HTML）

示例

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

响应

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

删除徽章

删除徽章。该徽章下不能有任何凭证。

DELETE /badges/{badgeId}

示例

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

响应

返回一个纯确认字符串：

"badge has been deleted"

错误

• 400 — 该徽章仍有已颁发的凭证："This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — 未找到徽章