徽章 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 — 找不到徽章