頒發 API

建立並管理徽章頒發(assertion)— 發給特定接收者的徽章。

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

建立頒發

將徽章頒發給接收者。

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 格式的到期日
blockchain	string	否	用於鏈上驗證的區塊鏈。僅支援 matchain。僅 Pro 方案可用。

範例

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: 100/mo、Starter: 1,000/mo、Pro: 10,000/mo)。配額是以當前日曆月 1 號 00:00 UTC 起所建立的頒發數量計算 — 會在 UTC 日曆月邊界重置,而非你的計費週年日。
• blockchain 參數僅於 Pro 方案可用,且僅接受 matchain。
• 區塊鏈錨定尚未上線。 傳入 blockchain: "matchain" 會被接受並記錄為一項請求,但目前尚未寫入任何鏈上證明 — 目前的頒發不帶有可驗證的鏈上紀錄。

---

列出頒發

取得頒發紀錄,可選擇性加上篩選與分頁。

GET /awards

查詢參數

參數	型別	必填	說明
filter	JSON 字串	否	篩選物件(見下)
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://ipfs.ninja/ipfs/Qm..."
      },
      "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(並可附上原因),讓任何驗證者都能看到該徽章已不再有效。頒發紀錄會為稽核目的保留,且不退還額度。

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

撤銷一個已被撤銷的頒發是冪等的 — 它會回傳相同的回應,且不會重新寄送通知。

---

刪除頒發

硬刪除你所發出的頒發。與撤銷不同,此操作會完全移除紀錄,且公開頒發頁會回傳 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 }
  }
}