凭证 API

创建并管理凭证（assertion）——即颁发给特定接收者的徽章。

所有端点都需要通过 X-Api-Key 头进行认证。参阅 认证。

创建凭证

向接收者颁发一枚徽章。

需要一次性向成百上千名接收者颁发，而不是每人调用一次 API？请使用支持上传 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：该凭证对应的位会在 VC 的 credentialStatus 所引用的 W3C Bitstring Status List 中翻转，因此 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 }
  }
}