徽章 API

管理徽章範本 — 即你頒發給接收者的憑證。

所有端點皆需透過 X-Api-Key 標頭驗證。請見 驗證。

建立徽章

於已驗證的頒發者下建立新徽章。

POST /badges

參數

參數	型別	必填	說明
name	string	是	徽章標題
description	string	是	徽章所代表的內容
criteria	string	是	接收者取得徽章所達成的條件
image	string	是	Base64 編碼的圖片(PNG 或 JPG)
issuerId	string	是	已驗證頒發者的 ID

範例

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"
    }
  }'

回應

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

備註

• 頒發者必須先驗證才能建立徽章。
• 圖片會上傳至 IPFS 進行永久儲存。

---

列出徽章

取得你建立的所有徽章。

GET /badges

範例

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

回應

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

更新徽章

更新既有徽章。僅你提供的欄位會被變更。

PUT /badges/{badgeId}

參數

參數	型別	必填	說明
badgeId	string	是	徽章 ID(路徑參數)
name	string	否	新徽章標題
description	string	否	新描述
criteria	string	否	新標準
image	string	否	新的 Base64 編碼圖片

範例

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"
    }
  }'

回應

{
  "statusCode": 200,
  "info": {
    "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:"
    }
  }'

回應

{
  "statusCode": 200,
  "info": {
    "updated": true
  }
}

---

刪除徽章

刪除徽章。徽章必須沒有任何頒發。

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"

回應

{
  "statusCode": 200,
  "info": {
    "deleted": true
  }
}

錯誤

• 400 — 徽章有頒發,無法刪除
• 404 — 找不到徽章