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

说明

• 从你的月度配额中扣 1 次(Free:100/月,Starter:1,000/月,Pro:10,000/月)。配额按当前日历月自 UTC 时间 1 号 00:00 起创建的颁发数量计算 — 在 UTC 日历月边界重置,而非你的计费周年日。
• blockchain 参数仅 Pro 套餐可用,且仅接受 matchain。
• 链上锚定尚未上线。 传入 blockchain: "matchain" 会被接受并记录为一次请求,但目前尚未写入任何链上凭证 — 此时颁发不携带可验证的链上记录。

---

列出颁发

可选地按筛选与分页获取颁发。

GET /awards

Query 参数

参数	类型	必填	说明
filter	JSON string	否	过滤对象(见下)
lastEvaluatedKey	string	否	上一次响应中的分页 token

过滤对象

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,说明还有更多结果。将其作为下一次请求的 query 参数即可获取下一页。

---

发送颁发邮件

向接收者发送关于其颁发的邮件通知。

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

响应是带有 Content-Type: application/pdf 头的二进制 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 去重:相同 event 自同一 IP 每 24 小时仅计 1 次。

示例

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