Cách cấp Open Badges từ CSV trong chưa đầy 5 phút

Nếu bạn từng cấp credential cho một nhóm theo kiểu mỗi lần một người nhận, bạn đã biết vấn đề: cách này không mở rộng nổi quá khoảng mười người trước khi biến thành cả một buổi chiều sao chép và dán tên cùng email. Một nhóm bootcamp 40 người, một danh sách 500 người tham dự hội nghị, hay một đợt triển khai đào tạo doanh nghiệp cho 5.000 người đều cần cùng một thứ — tải lên một danh sách, chọn một huy hiệu, nhấn Issue, rồi bỏ đi.

Đó chính xác là những gì Bulk Credentials trên https://badges.ninja làm. Hướng dẫn này bao quát toàn bộ quy trình: chuẩn bị CSV của bạn, cấu hình lô, theo dõi nó chạy, và xử lý những trường hợp lộn xộn ngoài đời thực — một dòng người nhận có lỗi đánh máy, một lô bị gián đoạn giữa chừng, hoặc một chương trình muốn cấp theo cùng cách từ hệ thống riêng của mình thay vì từ bảng điều khiển.

Trước khi bắt đầu: Bạn cần gì

Hai thứ, mà có lẽ cả hai bạn đều đã có:

1. Một huy hiệu — thiết kế một lần trong trình thiết kế trực quan, tái sử dụng cho mọi người nhận trong lô. Nếu bạn chưa tạo cái nào, hãy xem hướng dẫn của chúng tôi về thiết kế chứng chỉ có thể xác minh đầu tiên của bạn.
2. Một CSV danh sách người nhận — tên, email, và (tùy chọn) một ngày cấp. Toàn bộ lược đồ chỉ có vậy.

Bạn không cần một tài khoản tổ chức cấp riêng cho từng người nhận, một máy chủ thư, hay bất kỳ đoạn mã nào. Mọi thứ trong phần này diễn ra trong bảng điều khiển.

Bước 1: Chuẩn bị CSV của bạn

Định dạng danh sách người nhận được cố ý giữ ở mức tối giản:

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 — bắt buộc. Điền vào trường người nhận trên assertion và chứng chỉ.
• email — bắt buộc. Nó trở thành danh tính người nhận trên assertion Open Badge v2.0 — được băm với một salt riêng cho từng credential trước khi lưu trữ, không bao giờ được giữ ở dạng văn bản thuần.
• issued_on — tùy chọn. Để trống thì lô sẽ dùng thời điểm mỗi dòng được xử lý; điền rõ ràng nếu bạn đang bổ sung ngược cho một nhóm thực ra đã hoàn thành tháng trước.

Hầu hết chủ chương trình xuất thẳng dữ liệu này từ nơi họ vốn đã theo dõi việc hoàn thành — Airtable, Google Sheets, một bảng tính do giảng viên bàn giao, hoặc một CSV kéo ra từ sổ điểm LMS. Không cần công cụ xuất đặc biệt nào; bất kỳ CSV nào có ba cột đó đều dùng được.

Những cạm bẫy CSV thường gặp (và cách Xem trước bắt được chúng)

Một số ít vấn đề liên tục xuất hiện trong các danh sách người nhận ngoài đời thực, thường vì CSV được ghép lại từ hai hoặc ba bảng nguồn:

• Khoảng trắng thừa ở cuối địa chỉ email — việc sao chép và dán từ một danh sách PDF hoặc bản xuất Google Form thường mang theo một khoảng trắng vô hình. Nó trông ổn trong ô bảng tính nhưng lại thất bại khi xác thực email lúc tải lên.
• Dòng trùng lặp — cùng một người nhận xuất hiện hai lần vì một danh sách nhóm và một danh sách người đăng ký muộn được nối lại mà không loại trùng.
• Định dạng ngày không nhất quán — một cột 2026-07-01 lẫn với 07/01/2026 từ một bản xuất khác. Hãy bám theo ISO 8601 (YYYY-MM-DD) và vấn đề này biến mất hoàn toàn.
• Không khớp chữ hoa/thường ở tiêu đề cột — Email với email với E-mail. Bộ phân tích khá dễ tính với các biến thể phổ biến, nhưng một tên tiêu đề hoàn toàn tùy chỉnh sẽ không tự động ánh xạ.

Không cái nào trong số này là nghiêm trọng — bước xem trước (bên dưới) đưa từng cái ra ánh sáng trước khi bất cứ thứ gì được cấp, nên cách khắc phục là “sửa bảng tính, tải lên lại” thay vì “tìm xem ai trong 3.000 người nhận đã nhận một huy hiệu bị lỗi”.

Bước 2: Cấu hình lô

Từ bảng điều khiển, mở Credentials → Bulk Credentials và chọn huy hiệu bạn đang cấp. Đây là bước bạn thiết lập mọi thứ áp dụng cho toàn bộ lô: bản thân huy hiệu, một ngày cấp chung nếu bạn không đặt ngày theo từng dòng trong CSV, và (nếu hồ sơ tổ chức cấp của bạn có) ID tổ chức LinkedIn cho phép mọi người nhận thêm credential vào hồ sơ của họ chỉ bằng một cú nhấp.

Đây là thời điểm tốt để kiểm tra lại rằng huy hiệu bạn đã chọn là phiên bản cuối cùng — người nhận sẽ thấy hình ảnh và tiêu chí gắn với nó vào thời điểm bạn cấp, chứ không phải thứ bạn cập nhật về sau.

Bước 3: Tải lên và Xem trước

Thả CSV của bạn vào và nền tảng sẽ phân tích nó, hiển thị cho bạn một bảng xem trước, và gắn cờ mọi thứ nó không thể xử lý — một email thiếu, một ngày sai định dạng, một dòng trùng lặp. Không gì được cấp cho đến khi bạn xác nhận bản xem trước.

Bước xem trước này quan trọng hơn vẻ ngoài của nó. Một lỗi đánh máy ở một dòng trong CSV 2.000 dòng rất dễ bị bỏ sót bằng mắt, và bắt được nó trước khi 1.999 dòng đúng đã được cấp thì rẻ hơn nhiều so với việc cố gỡ rối sau đó. Sửa các dòng bị gắn cờ trong bảng tính của bạn, tải lên lại, và bản xem trước cập nhật.

Bước 4: Chạy lô

Nhấn Issue và lô bắt đầu xử lý. Một thanh tiến trình theo dõi số dòng đã hoàn thành so với số dòng còn lại, và lô chạy ở phía máy chủ — bạn không cần giữ tab mở, và đóng laptop giữa chừng cũng không làm mất chỗ của bạn.

Phần cuối đó đáng nói rõ ra vì đó là chi tiết thực sự quan trọng đối với các nhóm lớn: trạng thái của lô nằm trên máy chủ, không phải trong trình duyệt của bạn. Nếu kết nối của bạn rớt, laptop của bạn ngủ, hoặc bạn chỉ đóng tab vì có một cuộc họp bắt đầu, lô vẫn tiếp tục chạy (hoặc tiếp tục đúng chỗ nó đã dừng nếu bạn đã tạm dừng) thay vì khởi động lại từ đầu. Với một nhóm bootcamp 40 người thì đây là điều có cũng tốt. Với một đợt triển khai doanh nghiệp 5.000 dòng, đó là khác biệt giữa “nó cứ thế chạy” và “phải có ai đó trông chừng một tab trình duyệt suốt hai mươi phút”.

Bạn cũng có thể chủ ý tạm dừng một lô đang chạy — chẳng hạn, ai đó báo rằng văn bản tiêu chí của huy hiệu cần chỉnh giữa chừng một lượt chạy 3.000 dòng — sửa vấn đề, rồi tiếp tục mà không cấp lại các dòng đã hoàn thành.

Bước 5: Xử lý thất bại

Danh sách người nhận thực tế luôn có những dòng xấu: một tên miền email bị đánh máy sai, một trường tên thực ra để trống, một mục trùng lặp từ việc gộp hai bảng đã xuất. Khi một dòng thất bại, lô không dừng lại — nó tiếp tục xử lý phần còn lại và gắn cờ thất bại để xem xét sau. Bạn nhận được một bản xuất kết quả cho thấy chính xác dòng nào thành công và dòng nào không, nên bạn có thể chỉ sửa các dòng thất bại và chạy lại một lô tiếp nối nhỏ thay vì phải kiểm tra lại toàn bộ danh sách.

Điều này quan trọng đối với thói quen xuất CSV vốn đã phổ biến trên bảng điều khiển credential — bạn có thể kéo ra một CSV về những gì thực sự đã được cấp vào bất kỳ lúc nào, đối chiếu với danh sách nguồn của bạn, và biết chính xác ai vẫn còn cần một huy hiệu.

Con đường API: Cùng quy trình, không cần Bảng điều khiển

Mọi thứ ở trên giả định có ai đó ngồi ở bảng điều khiển bấm qua trình hướng dẫn. Nếu việc hoàn thành của bạn vốn đã nằm trong một hệ thống — một LMS, một CRM, một tự động hóa bảng tính — bạn có thể điều khiển cùng quy trình cấp credential hàng loạt trực tiếp từ Awards API.

Một lệnh gọi cấp tối thiểu cho mỗi người nhận trông như thế này:

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"
  }'

Hoặc trong Python, lặp qua các dòng đọc từ cùng một CSV mà nếu không bạn sẽ tải lên bằng tay:

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,
            },
        )

Cách này đáng để dùng khi việc cấp credential được kích hoạt bởi một thứ hoàn toàn khác — một webhook hoàn thành khóa học, một thay đổi giai đoạn CRM, một lần gửi biểu mẫu — thay vì một người xuất CSV thủ công. Chúng tôi trình bày xác thực và hình thức đầy đủ của yêu cầu/phản hồi trong phần hướng dẫn nhanh API. Mỗi credential được tạo theo cách này giống hệt với credential được tạo qua trình hướng dẫn của bảng điều khiển: cùng assertion Open Badge v2.0, cùng URL xác minh, cùng chứng chỉ PDF.

Trình hướng dẫn bảng điều khiển so với API: Bạn thực sự muốn cái nào?

Hầu hết đội nhóm bắt đầu với trình hướng dẫn của bảng điều khiển vì nó không đòi hỏi gì ngoài một CSV, và chỉ chuyển sang API khi cùng một lô đã được chạy thủ công ba bốn lần và mô hình rõ ràng đáng để tự động hóa.

Quyền riêng tư: Điều gì thực sự được lưu trữ

Một CSV gồm tên và email là dữ liệu cá nhân, và đáng để biết điều gì xảy ra với nó sau khi tải lên. Địa chỉ email của người nhận không bao giờ được lưu ở dạng văn bản thuần trên chính credential — nó được băm với một salt riêng cho từng credential như một phần của assertion Open Badge v2.0, tuân theo định dạng danh tính người nhận hashed của đặc tả. Chính giá trị băm đó là thứ mà bên xác minh kiểm tra, chứ không phải địa chỉ thô. Trường tên được lưu đúng như đã nhập, vì nó vốn dành để hiển thị trên chứng chỉ và trang xác minh. Nếu một dòng cần chỉnh sau khi cấp — thường gặp nhất là một cái tên bị viết sai — bạn có thể chỉnh sửa hoặc thu hồi credential riêng lẻ đó từ bảng điều khiển credential mà không đụng đến phần còn lại của lô.

Sau lô: Thông báo cho người nhận

Cấp huy hiệu và báo cho người nhận về nó là hai bước khác nhau. Nếu CSV của bạn chưa kích hoạt một email qua hệ thống riêng của bạn, quy trình chia sẻ hàng loạt của bảng điều khiển cho phép bạn chọn nhiều credential bạn vừa tạo và gửi một email chia sẻ được cá nhân hóa cho tất cả chúng trong một lượt — xem gửi email chia sẻ hàng loạt để có hướng dẫn đầy đủ, bao gồm cách cá nhân hóa theo từng người nhận (tên, hình ảnh huy hiệu, liên kết xác minh) được thay thế tự động.

Khi nào Bulk Credentials là công cụ phù hợp

Cấp hàng loạt là lựa chọn đúng bất cứ khi nào khung “lô” khớp với đời thực: một nhóm hoàn thành trong cùng một ngày, một hội nghị vừa kết thúc, một đợt triển khai đào tạo cận kề hạn tuân thủ. Nếu ngược lại bạn cấp credential riêng lẻ khi từng cột mốc cá nhân được đạt tới — một lần thăng chức, một lần hoàn thành dự án — thì biểu mẫu credential đơn nhanh hơn việc lắp ghép một CSV một dòng.

Với bất cứ thứ gì lặp lại — cùng một khóa học chạy mỗi tháng, một quy trình onboarding liên tục — con đường API ở trên đáng để thiết lập một lần. Nó biến “chạy bulk credentials thủ công mỗi nhóm” thành “việc hoàn thành đã tự động cấp credential”, đó là phiên bản của quy trình này mà hầu hết chủ chương trình thực sự muốn sau lô thủ công thứ hai hoặc thứ ba.

Sẵn sàng cấp credential có thể xác minh đầu tiên của bạn? Bắt đầu miễn phí tại badges.ninja — trình thiết kế trực quan, trang xác minh công khai, chứng chỉ PDF, đầu ra Open Badge v2.0. Không cần thẻ tín dụng.