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

回應

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

備註

• 每次頒發會扣抵你每月的配額(Free: 100/mo、Starter: 1,000/mo、Pro: 10,000/mo)。配額會於每個計費週期重置。
• blockchain 參數僅於 Pro 方案可用。

---

列出頒發

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

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"

回應

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

回應

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

---

分享頒發

將頒發以電子郵件分享給多位接收者。

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

回應

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

---

下載 PDF 證書

為頒發產生一份可列印的 A4 PDF 證書。

GET /awards/{awardGuid}/pdf

無需驗證 — 此端點為公開,讓接收者可自行下載證書。

範例

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

回應為二進位 PDF,標頭為 Content-Type: application/pdf。

---

追蹤頒發事件

記錄互動事件(檢視、分享、下載、LinkedIn 新增)。由公開頒發頁使用,用以累計互動統計。無需驗證。

POST /awards/{awardGuid}/event

參數

參數	型別	必填	說明
kind	string	是	view、share、download、linkedin_add 之一。
network	string	否	當 kind=share 時的社群網路:linkedin、twitter、facebook、whatsapp、telegram、email、copy。

依 IP 重複抑制:同一 IP 相同類型事件於 24 小時內僅計算一次。

範例

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

---

取得頒發統計

取得頒發的累計互動計數。

GET /awards/{awardGuid}/stats

無需驗證。

回應

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}