CSV から Open Badges を 5 分以内に発行する方法

コホートに対して受信者を一人ずつ発行したことがあるなら、その問題はもうご存じでしょう。だいたい 10 人を超えると立ち行かなくなり、名前とメールアドレスをコピー＆ペーストするだけで午後がまるごと潰れてしまいます。40 人のブートキャンプのコホート、500 人のカンファレンス参加者リスト、5,000 人規模の企業研修のロールアウト、これらはすべて同じことを必要としています。つまり、リストをアップロードし、バッジを選び、発行をクリックして、立ち去るということです。

それこそが https://badges.ninja の Bulk Credentials が行うことです。このウォークスルーでは、CSV の準備、バッチの設定、実行を見守ること、そして現実世界の厄介なケースへの対処という一連の流れ全体を扱います。厄介なケースとは、タイプミスのある受信者の行、途中で中断されるバッチ、あるいはダッシュボードではなく自社のシステムから同じように発行したいプログラムなどです。

始める前に：必要なもの

2 つ、どちらもおそらくすでにお持ちのものです。

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 などです。特別なエクスポートツールは不要で、その 3 つの列を持つ CSV ならどれでも動作します。

よくある CSV の落とし穴（そしてプレビューがどう捕まえるか）

現実世界の受信者リストには、いくつかの問題が絶えず現れます。たいていは CSV が 2 つか 3 つの元シートを結合して組み立てられたためです。

• メールアドレス末尾の余分な空白 —— PDF の名簿や Google フォームのエクスポートからのコピー＆ペーストには、しばしば目に見えない空白が紛れ込みます。スプレッドシートのセルでは問題なく見えますが、アップロード時にメール検証で失敗します。
• 重複した行 —— コホートのリストと遅れて登録した人のリストが重複排除なしに連結されたために、同じ受信者が 2 回現れます。
• 一貫しない日付フォーマット —— ある列の 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 行のタイプミスは目視では見逃しやすく、1,999 行の正しい行がすでに発行された後にそれを巻き戻そうとするより、その前に捕まえるほうがはるかに安上がりです。スプレッドシートでフラグの立った行を直し、再アップロードすれば、プレビューが更新されます。

ステップ 4：バッチを実行する

発行をクリックすると、バッチの処理が始まります。プログレスバーが完了した行と残りの行を追跡し、バッチはサーバー側で実行されます。タブを開いたままにしておく必要はなく、バッチの途中でノートパソコンを閉じても進行状況は失われません。

その最後の点は、大規模なコホートで実際に重要となる細部なので、はっきりさせておく価値があります。バッチの状態はブラウザではなくサーバー上にあります。接続が切れても、ノートパソコンがスリープしても、会議が始まって単にタブを閉じても、バッチはゼロから再スタートするのではなく、実行を続けます（一時停止していた場合は、中断したまさにその場所から再開します）。40 人のブートキャンプのコホートにとって、これはあれば嬉しい機能です。5,000 行の企業ロールアウトにとっては、「ただ動く」ことと「誰かが 20 分間ブラウザのタブを見張らなければならない」ことの違いになります。

実行中のバッチを意図的に一時停止することもできます。たとえば、3,000 行の実行の途中で誰かがバッジの基準テキストに手直しが必要だと指摘した場合、問題を修正し、すでに完了した行を再発行することなく再開できます。

ステップ 5：失敗に対処する

現実の受信者リストには不良行があります。タイプミスのあるメールドメイン、実は空の名前フィールド、2 つのエクスポートシートが結合されたことによる重複エントリなどです。ある行が失敗しても、バッチは止まりません。残りの処理を続け、後で確認できるようにその失敗にフラグを立てます。どの行が成功しどの行が失敗したかを正確に示す結果のエクスポートが得られるので、リスト全体を再チェックする代わりに、失敗した行だけを直して小さなフォローアップのバッチを再実行できます。

これは、証明書ダッシュボードですでに一般的になっている 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,
            },
        )

これに手を伸ばす価値があるのは、証明書の発行が、人が手作業で CSV をエクスポートすることではなく、まったく別の何か —— コース修了の webhook、CRM のステージ変更、フォームの送信 —— によってトリガーされる場合です。認証とリクエスト／レスポンスの完全な形については、API クイックスタートで扱っています。この方法で作成されたすべての証明書は、ダッシュボードのウィザードで作成されたものと同一です。同じ Open Badge v2.0 アサーション、同じ検証 URL、同じ PDF 証明書です。

ダッシュボードのウィザード vs. API：実際にどちらが欲しいのか？

ほとんどのチームはダッシュボードのウィザードから始めます。CSV 以外に何も必要としないからです。そして、同じバッチを手作業で 3、4 回実行し、そのパターンが自動化する価値が明らかになって初めて API に移行します。

プライバシー：実際に保存されるもの

名前とメールの CSV は個人データであり、アップロード後にそれがどうなるかを知っておく価値があります。受信者のメールアドレスが証明書そのものに平文で保存されることは決してありません。仕様の hashed 受信者識別フォーマットに従い、Open Badge v2.0 アサーションの一部として証明書ごとの salt でハッシュ化されます。検証者が照合するのは生のアドレスではなく、このハッシュです。名前フィールドは、証明書と検証ページに表示されることを意図しているため、入力されたとおりに保存されます。発行後にある行を訂正する必要がある場合 —— 最もよくあるのは名前のスペルミスです —— バッチの残りに触れることなく、証明書ダッシュボードから個々の証明書を編集または取り消せます。

バッチの後：受信者に通知する

バッジを発行することと、受信者にそれを知らせることは、2 つの別々のステップです。自社のシステムを通じて CSV がすでにメールをトリガーしていない場合、ダッシュボードの一括共有フローを使えば、作成したばかりの証明書を複数選択し、それらすべてにパーソナライズされた共有メールを一度に送れます。受信者ごとのパーソナライズ（名前、バッジ画像、検証リンク）が自動的に差し込まれる仕組みを含む完全なウォークスルーは、共有メールの一括送信をご覧ください。

Bulk Credentials が適切なツールであるとき

「バッチ」という枠組みが現実に合致するなら、いつでも一括発行が正しい選択です。同じ日に修了したコホート、ちょうど終わったばかりのカンファレンス、コンプライアンスの締め切りに迫る研修のロールアウトなどです。逆に、個々のマイルストーンが達成されるたびに単発の証明書を発行しているなら —— 単一の昇進、単一のプロジェクトの完了 —— 1 行の CSV を組み立てるより単一証明書フォームのほうが速いです。

繰り返し起きるもの —— 毎月開催される同じコース、途切れなく続くオンボーディングのパイプライン —— については、上記の API という道を一度だけ設定しておく価値があります。それは「コホートごとに手作業で一括証明書を実行する」を「修了そのものがすでに自動的に証明書を発行する」に変えます。これこそ、ほとんどのプログラム担当者が 2、3 回目の手作業バッチの後に本当に望む、このワークフローの姿です。

最初の検証可能な証明書を発行する準備はできましたか？ badges.ninja で無料で始める —— ビジュアルデザイナー、公開検証ページ、PDF 証明書、Open Badge v2.0 出力。クレジットカードは不要です。