如何在 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 表單匯出內容裡複製貼上，往往會帶上一個看不見的空格。它在試算表儲存格裡看起來沒問題，但上傳時會在電子郵件驗證環節失敗。
• 重複的列 —— 同一個收件人出現兩次，因為一份班級名單和一份遲到報名名單被直接串接在一起，沒有去除重複。
• 不一致的日期格式 —— 一欄裡的 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 輸出。不需要信用卡。