憑證 API

建立並管理憑證（assertion）— 發給特定接收者的徽章。

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

建立憑證

將徽章簽發給接收者。

如果需要一次簽發給數百或數千位接收者，而不是每人呼叫一次 API，請使用批次憑證 UI 功能，它支援上傳 CSV。

POST /awards

參數

參數	類型	必填	說明
badgeId	string	是	要簽發的徽章 ID
recipient	object	是	接收者詳細資料（見下方）
recipient.name	string	是	接收者全名（至少 5 個字元）
recipient.email	string	是	接收者電子郵件地址
issuedOn	string	是	ISO 8601 格式的簽發日期（例如 2025-01-15）
expires	string	否	ISO 8601 格式的到期日期

範例

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

回應

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

注意事項

• 每次簽發會計為年度憑證額度中的一張憑證（Free：每年 1,200 張、Starter：每年 12,000 張、Pro：每年 120,000 張）。此額度是彈性的年度配額 — 您可以在一年中隨時使用，包括集中大量使用 — 並於您帳號的註冊週年日重設。帳單仍按月計算；只有憑證配額是按年計算。詳情請見方案與帳單。

---

列出憑證

擷取憑證，可選擇性地進行篩選與分頁。

GET /awards

查詢參數

參數	類型	必填	說明
filter	JSON string	否	篩選物件（見下方）
lastEvaluatedKey	string	否	來自前一次回應的分頁權杖

篩選物件

filter 參數接受包含下列欄位的 JSON 字串：

欄位	類型	說明
badgeId	string	依徽章 ID 篩選。
search	string	在接收者姓名或電子郵件中查詢的子字串（見 searchField）。
searchField	string	name（預設）或 email — 指定要搜尋的欄位。

無論有沒有篩選條件，都可以透過 lastEvaluatedKey 分頁。每頁筆數為 50。

範例 — 列出所有憑證

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

範例 — 依徽章篩選

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

回應

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

如果回應中包含 lastEvaluatedKey，表示還有更多結果。請在下一次請求中將它作為查詢參數傳入，以取得下一頁。

---

傳送憑證電子郵件

向接收者傳送有關其憑證的電子郵件通知。

POST /awards/{awardId}/send

參數

參數	類型	必填	說明
awardId	string	是	憑證 ID（路徑參數與本文）
email	string	是	接收者電子郵件地址

範例

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

回應

回傳純文字確認字串：

"email sent"

---

分享憑證

透過電子郵件將憑證分享給多位收件者。

POST /awards/{awardId}/share

參數

參數	類型	必填	說明
awardId	string	是	憑證 ID（路徑參數與本文）
recipients	string	是	以逗號分隔的電子郵件地址清單
subject	string	是	電子郵件主旨
message	string	是	電子郵件內文

範例

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

回應

回傳純文字確認字串：

"email sent"

---

撤銷憑證

撤銷您所簽發的憑證。託管的 Open Badges v2.0 assertion 會被標記為 revoked: true（可附上原因），讓任何驗證者都能看出該徽章已不再有效。憑證記錄會保留以供稽核，且不會退還點數。

撤銷也會傳播到該憑證的 Open Badges 3.0 Verifiable Credential：該憑證在 W3C Bitstring Status List（由 VC 的 credentialStatus 所引用）中對應的位元會被翻轉，因此 VC 錢包同樣能偵測到。請見撤銷（Bitstring Status List）。

POST /awards/{awardId}/revoke

參數

參數	類型	必填	說明
awardId	string	是	憑證 ID（路徑參數）
reason	string	否	撤銷原因。超過 500 個字元會被截斷。
notify	boolean	否	為 true 時，會以電子郵件通知接收者其憑證已被撤銷。預設為 false。

範例

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

回應

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

撤銷已被撤銷的憑證是冪等的 — 會回傳相同的回應，且不會重複發送通知。

批次撤銷

若要一次撤銷多張憑證，請使用具備持久性的批次端點並指定 action: "revoke"，而不是對每張憑證各呼叫一次此端點：

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

它會回傳 { "jobId", "total" }；該工作會在伺服器端撤銷每個 ID（略過已撤銷者），並且可以恢復執行。已撤銷與不存在的 ID 會被回報為已略過。

---

刪除憑證

永久刪除您所簽發的憑證。與撤銷不同，這會完全移除記錄，公開憑證頁面將回傳 404。請將此用於真正的錯誤（例如簽發給錯誤的人）；對於實際有效的憑證，建議使用撤銷，讓 assertion 仍可被驗證為已撤銷。不會退還點數。

DELETE /awards/{awardId}

參數

參數	類型	必填	說明
awardId	string	是	憑證 ID（路徑參數）

範例

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

回應

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

下載 PDF 證書

為憑證產生可直接列印的 A4 PDF 證書。

GET /certify-badge/award/{awardGuid}/pdf

無需驗證 — 此端點為公開，讓接收者可以下載自己的證書。

範例

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

回應為二進位 PDF，並附有 Content-Type: application/pdf 標頭。

---

追蹤憑證事件

記錄互動事件。公開憑證頁面使用此端點來累積互動統計。無需驗證。

POST /certify-badge/award/{awardGuid}/event

參數

此端點直接讀取其本文（沒有 parameters 包裝層）。

參數	類型	必填	說明
event	string	是	view、share、download、click_linkedin_addtoprofile、click_pdf、click_verify 其中之一。
network	string	否	當 event=share 時的社群網路：linkedin、twitter、facebook、whatsapp、telegram、email、copy。

依 IP 去除重複：來自同一 IP 的相同事件，每 24 小時只計算一次。

範例

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

回應

{
  "ok": true
}

---

取得憑證統計

擷取憑證的累計互動計數。

GET /certify-badge/award/{awardGuid}/stats

無需驗證。

回應

計數器以原始事件類型為鍵回傳。totals 記錄每種事件的總數；networks 則針對帶有 network 的事件（目前為 share）列出各網路的分項統計。沒有任何活動紀錄的事件則不會出現。

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}