如何在 5 分钟内从 CSV 批量颁发 Open Badges

如果你曾经一次一个收件人地给一批人颁发凭证，你早就知道问题所在了：超过大约十个人之后就完全撑不住，会变成一整个下午复制粘贴姓名和邮箱的苦差事。一个 40 人的训练营班级、一份 500 人的会议参会名单，或是一次面向 5,000 人的企业培训推广，都需要同一件事——上传一份名单，选一个徽章，点击颁发，然后走人。

这正是 https://badges.ninja 上的 Bulk Credentials 所做的事。本篇教程涵盖整个流程：准备你的 CSV、配置批次、看着它运行，以及处理现实世界中那些棘手的情况——某一行收件人有拼写错误、批次进行到一半被中断，或者某个项目希望从自己的系统而非仪表盘以同样的方式颁发。

开始之前：你需要准备什么

两样东西，两样你很可能都已经有了：

1. 一个徽章 —— 在可视化设计器里设计一次，然后为批次里的每个收件人重复使用。如果你还没做过，请看我们关于设计你的第一张可验证证书的指南。
2. 一份收件人 CSV —— 姓名、邮箱，以及（可选的）颁发日期。这就是全部的字段结构。

你不需要为每个收件人准备一个颁发者账号，不需要邮件服务器，也不需要任何代码。本节的所有操作都在仪表盘里完成。

第 1 步：准备你的 CSV

收件人名单的格式刻意做得很精简：

name,email,issued_on
Maria Gonzalez,maria@example.com,2026-07-01
David Kim,david@example.com,2026-07-01
Priya Patel,priya@example.com,

• name —— 必填。填充断言和证书上的收件人字段。
• email —— 必填。它会成为 Open Badge v2.0 断言上的收件人身份 —— 在存储前用每个凭证独立的 salt 进行哈希处理，绝不以明文保存。
• issued_on —— 可选。留空时，批次会使用每一行被处理的那一刻；如果你是在为一个实际上上个月就结束的班级补录，就明确填上它。

大多数项目负责人都是直接从他们已经用来记录结业情况的地方导出这份文件——Airtable、Google Sheets、讲师递交的一份电子表格，或者从 LMS 成绩册里拉出来的一份 CSV。不需要任何专门的导出工具；任何带有这三列的 CSV 都可以用。

常见的 CSV 陷阱（以及预览如何帮你抓出它们）

现实中的收件人名单里总会反复出现几类问题，通常是因为这份 CSV 是把两三张来源表合并拼出来的：

• 邮箱地址末尾的空白字符 —— 从 PDF 名册或 Google Form 导出内容里复制粘贴，往往会带上一个看不见的空格。它在表格单元格里看起来没问题，但上传时会在邮箱校验环节失败。
• 重复的行 —— 同一个收件人出现两次，因为一份班级名单和一份迟到报名名单被直接拼接在一起，没有去重。
• 不一致的日期格式 —— 一列里的 2026-07-01 和来自另一次导出的 07/01/2026 混在一起。坚持使用 ISO 8601（YYYY-MM-DD），这个问题就会彻底消失。
• 表头大小写不匹配 —— Email 对 email 对 E-mail。解析器对常见的变体比较宽容，但一个完全自定义的表头名不会被自动映射。

这些问题没有一个是致命的 —— 预览步骤（见下文）会在任何东西被颁发之前把每一个都暴露出来，所以修复方式是“改一下表格，重新上传”，而不是“搞清楚 3,000 个收件人里到底是哪一个拿到了坏掉的徽章”。

第 2 步：配置批次

在仪表盘里，打开 Credentials → Bulk Credentials，选择你要颁发的徽章。这一步用来设置适用于整个批次的一切：徽章本身、一个共享的颁发日期（如果你不打算在 CSV 里逐行填日期的话），以及（如果你的颁发者档案里有的话）LinkedIn 组织 ID，它能让每个收件人一键把凭证添加到自己的个人主页。

这是一个再次确认你所选徽章就是最终版本的好时机 —— 收件人看到的将是你颁发那一刻附在徽章上的图片和标准，而不是你之后更新成的样子。

第 3 步：上传并预览

把你的 CSV 拖进来，平台会解析它，向你展示一张预览表格，并标记出任何它无法处理的内容 —— 缺失的邮箱、格式错误的日期、重复的行。在你确认预览之前，什么都不会被颁发。

这个预览步骤比它看上去更重要。在一份 2,000 行的 CSV 中，某一行的拼写错误用肉眼很容易漏掉，而在 1,999 行正确的数据已经颁发之前抓到它，要比事后再去收拾便宜得多。在你的表格里修正被标记的行，重新上传，预览就会更新。

第 4 步：运行批次

点击颁发，批次就开始处理。一个进度条会跟踪已完成与剩余的行数，并且批次在服务器端运行 —— 你不需要一直开着标签页，批次进行到一半时合上笔记本也不会丢失进度。

最后这一点值得说清楚，因为它才是对大批量真正重要的细节：批次状态存在服务器上，而不是你的浏览器里。如果你的网络断了、笔记本睡眠了，或者你只是因为要开会而关掉了标签页，批次会继续运行（如果你之前暂停了，它会正好从停下的地方恢复），而不是从零重新开始。对一个 40 人的训练营班级来说，这只是锦上添花。而对一次 5,000 行的企业推广来说，它就是“它就是能用”和“得有人盯着一个浏览器标签页看二十分钟”之间的区别。

你也可以有意暂停一个正在运行的批次 —— 比如说，有人在一次 3,000 行的运行进行到一半时指出徽章的标准文案需要改一下 —— 修好问题，然后在不重新颁发已完成行的情况下恢复。

第 5 步：处理失败项

真实的收件人名单里总有坏行：拼错的邮箱域名、其实是空的姓名字段、两张导出表合并时带来的重复条目。当某一行失败时，批次不会停下 —— 它会继续处理其余的行，并把这个失败标记出来供你事后审查。你会得到一份结果导出文件，清楚地显示哪些行成功、哪些行失败，这样你就可以只修复失败的那些行，重新运行一个小小的后续批次，而不用把整份名单再核对一遍。

这一点对于凭证仪表盘上已经很常见的 CSV 导出习惯很有意义 —— 你可以在任何时刻拉出一份记录着实际颁发情况的 CSV，把它和你的源名单交叉比对，从而精确知道谁还没拿到徽章。

API 路径：同样的流程，无需仪表盘

上面的一切都假设有人坐在仪表盘前一路点击向导。如果你的结业数据已经存在于某个系统里 —— 一个 LMS、一个 CRM、一套电子表格自动化 —— 你可以改为直接通过 Awards API 来驱动同样的批量凭证流程。

一次最小化的、针对单个收件人的颁发调用看起来是这样：

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{
    "badgeId": "badge_9f8e7d6c5b4a",
    "recipient": {
      "name": "Maria Gonzalez",
      "email": "maria@example.com"
    },
    "issuedOn": "2026-07-01T00:00:00Z"
  }'

或者用 Python，遍历那份你本来会手动上传的同一份 CSV 里读出的每一行：

import csv
import requests

API_KEY = "bws_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
BADGE_ID = "badge_9f8e7d6c5b4a"

with open("recipients.csv") as f:
    for row in csv.DictReader(f):
        requests.post(
            "https://api.badges.ninja/awards",
            headers={"X-Api-Key": API_KEY},
            json={
                "badgeId": BADGE_ID,
                "recipient": {"name": row["name"], "email": row["email"]},
                "issuedOn": row.get("issued_on") or None,
            },
        )

当凭证颁发是由完全另外一件事触发时 —— 一个课程结业的 webhook、一次 CRM 阶段变更、一次表单提交 —— 而不是由某个人手动导出 CSV 时，就值得考虑走这条路。我们在 API 快速入门里介绍了认证以及完整的请求/响应结构。用这种方式创建的每一个凭证，都和通过仪表盘向导创建的完全一致：同样的 Open Badge v2.0 断言、同样的验证 URL、同样的 PDF 证书。

仪表盘向导 vs. API：你到底想要哪一个？

大多数团队都从仪表盘向导开始，因为它除了一份 CSV 之外别无所求；只有在同一个批次已经手动运行了三四次、这个模式明显值得自动化之后，他们才会转向 API。

隐私：到底存了什么

一份包含姓名和邮箱的 CSV 属于个人数据，很值得了解它在上传之后会经历什么。收件人的邮箱地址绝不会以明文形式存储在凭证本身上 —— 它作为 Open Badge v2.0 断言的一部分，用每个凭证独立的 salt 进行哈希处理，遵循规范中的 hashed 收件人身份格式。验证方核对的是这个哈希值，而不是原始地址。姓名字段则按输入原样存储，因为它本就是要显示在证书和验证页面上的。如果某一行在颁发后需要更正 —— 最常见的是名字拼错了 —— 你可以从凭证仪表盘编辑或吊销这一个凭证，而不影响批次的其余部分。

批次之后：通知收件人

颁发徽章和告知收件人是两个不同的步骤。如果你的 CSV 还没有通过你自己的系统触发一封邮件，仪表盘的批量分享流程可以让你多选刚刚创建的那些凭证，一次性给它们全部发送一封个性化的分享邮件 —— 完整的操作步骤请看批量发送分享邮件，其中包括针对每个收件人的个性化内容（姓名、徽章图片、验证链接）是如何被自动替换进去的。

什么时候 Bulk Credentials 是合适的工具

只要“批次”这个框架契合现实情况，批量颁发就是正确的选择：同一天结业的一个班级、一场刚刚落幕的会议、一次赶在合规截止日期前完成的培训推广。相反，如果你是在个别里程碑达成时颁发一次性的凭证 —— 一次单独的晋升、一个单独项目的完成 —— 那么单个凭证表单会比拼一份只有一行的 CSV 更快。

对于任何反复发生的事情 —— 每月都开的同一门课、一条滚动进行的入职流程 —— 上面那条 API 路径值得一次性配置好。它把“每个班级都手动运行一遍批量凭证”变成“结业本身就自动颁发凭证”，而这正是大多数项目负责人在做过第二次或第三次手动批次之后真正想要的那个版本的工作流。

准备好颁发你的第一张可验证凭证了吗？ 在 badges.ninja 免费开始 —— 可视化设计器、公开验证页面、PDF 证书、Open Badge v2.0 输出。无需信用卡。