頒發者 API

管理徽章頒發者 — 頒發徽章的組織或個人。

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

建立頒發者

建立新的徽章頒發者。

POST /issuers

參數

參數	型別	必填	說明
name	string	是	組織名稱(至少 3 個字元)
url	string	是	組織網站(必須是有效的 HTTP/HTTPS URL)
email	string	是	頒發者的聯絡電子郵件
logo	string	否	Base64 編碼的圖片(PNG 或 JPG)
linkedinOrganizationId	string	否	LinkedIn 公司頁的數字 ID。設定後,此頒發者名下每個公開頒發頁皆會顯示 新增至 LinkedIn 個人檔案 按鈕。

範例

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

回應

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

備註

• 會計入方案的頒發者上限(Free: 1、Starter: 5、Pro: 無上限)。不扣配額。
• 若頒發者電子郵件與帳號電子郵件相同,頒發者會自動通過驗證。
• 若電子郵件不同,系統會寄送驗證電子郵件至頒發者電子郵件。

---

列出頒發者

取得你建立的所有頒發者。

GET /issuers

範例

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

回應

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "name": "Acme Academy",
        "url": "https://acme.example.com",
        "email": "badges@acme.example.com",
        "verified": true,
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

驗證頒發者

使用寄至頒發者電子郵件的驗證碼驗證頒發者。

POST /issuers/{issuerId}/verify

參數

參數	型別	必填	說明
issuerId	string	是	頒發者 ID(路徑參數)
code	string	是	電子郵件中的驗證碼

範例

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

回應

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

---

刪除頒發者

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

DELETE /issuers/{issuerId}

範例

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

回應

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

錯誤

• 400 — 頒發者有徽章或頒發,無法刪除(請先刪除那些)
• 404 — 找不到頒發者

---

更新頒發者

更新未驗證頒發者的欄位。一旦頒發者已驗證,僅 logo 與 linkedinOrganizationId 可繼續編輯,以保持憑證穩定。

PUT /issuers/{issuerId}

參數

參數	型別	必填	說明
issuerId	string	是	頒發者 ID(路徑參數)
name	string	否	新名稱(僅限未驗證時)
url	string	否	新 URL(僅限未驗證時)
email	string	否	新電子郵件(僅限未驗證時 — 會寄送新的驗證信)
logo	string	否	新的 Base64 編碼 logo
linkedinOrganizationId	string	否	新的 LinkedIn 組織 ID(或空字串以清除)

---

重新產生驗證碼

讓先前的驗證連結失效,並寄送新的一組。僅於頒發者尚未驗證時有效。

POST /issuers/{issuerId}/rotate-code

回應

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