颁发者 API

管理徽章颁发者 — 颁发徽章的组织或个人。

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

创建颁发者

创建一个新的徽章颁发者。

POST /issuers

参数

参数	类型	必填	说明
name	string	是	组织名称(至少 3 个字符)
url	string	是	组织网站(必须是有效的 HTTP/HTTPS URL)
email	string	是	颁发者联系邮箱
logo	string	否	Base64 编码的图片(PNG 或 JPG)
linkedinOrganizationId	string	否	LinkedIn 公司主页的数字 ID。设置后,该颁发者的每个公开颁发页都会显示 添加到 LinkedIn 个人资料 按钮。

示例

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

响应

{
  "statusCode": 200,
  "info": {
    "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

说明

• 计入你套餐的颁发者上限(Free:1、Starter:5、Pro:无限)。不扣除配额。
• 若颁发者邮箱与账户邮箱一致,颁发者会被自动验证。
• 若邮箱不同,会向颁发者邮箱发送一封验证邮件。

---

列出颁发者

获取你创建的所有颁发者。

GET /issuers

示例

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

响应

{
  "statusCode": 200,
  "info": {
    "issuers": [
      {
        "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "name": "Acme Academy",
        "url": "https://acme.example.com",
        "email": "badges@acme.example.com",
        "verified": true,
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

验证颁发者

使用发送到其邮箱的验证码来验证颁发者。

POST /issuers/{issuerId}/verify

参数

参数	类型	必填	说明
issuerId	string	是	颁发者 ID(路径参数)
code	string	是	邮件中的验证码

示例

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

响应

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

---

删除颁发者

删除颁发者。该颁发者必须没有徽章。

DELETE /issuers/{issuerId}

示例

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

响应

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

错误

• 400 — 颁发者存在徽章或颁发记录,无法删除(请先删除它们)
• 404 — 颁发者未找到

---

更新颁发者

更新未验证颁发者的字段。颁发者一旦验证,仅剩 logo 与 linkedinOrganizationId 可编辑,以保证凭证稳定性。

PUT /issuers/{issuerId}

参数

参数	类型	必填	说明
issuerId	string	是	颁发者 ID(路径参数)
name	string	否	新名称(仅在未验证时)
url	string	否	新 URL(仅在未验证时)
email	string	否	新邮箱(仅在未验证时 — 会发送新的验证邮件)
logo	string	否	新的 Base64 编码 Logo
linkedinOrganizationId	string	否	新的 LinkedIn 组织 ID(或空字符串以清除)

---

轮换验证码

使上一个验证链接失效,并通过邮件发送新的。仅在颁发者仍未验证时有效。

POST /issuers/{issuerId}/rotate-code

响应

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