頒發者 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"
    }
  }'

回應

{
  "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"

回應

{
  "items": [
    {
      "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": 1736937000000
    }
  ]
}

timestamp 為 Unix epoch 毫秒。當頒發者數量超過單頁可容納時,回應會另外傳回 lastEvaluatedKey 以供分頁。

---

驗證頒發者

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

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

回應

一個純字串:

"issuer has been verified"

---

刪除頒發者

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

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"

回應

一個純字串:

"issuer has been deleted"

錯誤

• 400 — 頒發者仍有連結的徽章:issuer has {n} badge(s) linked — delete the badges first。刪除僅受 連結的徽章 限制 — 頒發不會阻擋刪除。
• 404 — 找不到頒發者

---

更新頒發者

更新頒發者的欄位。僅未驗證的頒發者可編輯 — 一旦頒發者已驗證,此端點會回傳 400 verified issuers cannot be edited,以保持憑證穩定。編輯頒發者會重新產生其驗證碼:若 email 與你的帳號電子郵件相符,頒發者會自動重新驗證,否則會寄送新的驗證電子郵件至該地址。

PUT /issuers/{issuerId}

參數

參數	型別	必填	說明
issuerId	string	是	頒發者 ID(路徑參數)
name	string	否	新名稱
url	string	否	新 URL
email	string	否	新電子郵件(除非與你的帳號電子郵件相符,否則會寄送新的驗證信)
logo	string	否	新的 Base64 編碼 logo
linkedinOrganizationId	string	否	新的 LinkedIn 組織 ID(或空字串以清除)

回應

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

錯誤

• 400 — verified issuers cannot be edited(頒發者已驗證)
• 400 — not authorized(頒發者屬於其他帳號)
• 404 — 找不到頒發者