Cách thu hồi Open Badge (và điều gì xảy ra với bản sao của người nhận)

Thu hồi (revocation) trong Open Badges: cách hoạt động, người nhận thấy gì thay đổi, và cách xử lý đúng các trường hợp «cấp nhầm», «chứng chỉ hết hạn» và «vi phạm chính sách».

Nacho Coll Bởi Cập nhật 13 phút đọc
Thu hồi (revocation) trong Open Badges: cách hoạt động, người nhận thấy gì thay đổi, và cách xử lý đúng các trường hợp «cấp nhầm», «chứng chỉ hết hạn» và «vi phạm chính sách».

Sớm hay muộn, chương trình nào cấp chứng chỉ số cũng phải thu hồi một chứng chỉ. Một chứng nhận gửi nhầm người. Một học viên bị phát hiện gian lận trong bài đánh giá cuối khóa. Hợp đồng với đối tác kết thúc và những huy hiệu ghi “Certified Partner” không còn hiệu lực. Cấp chứng chỉ là phần dễ chịu; thu hồi mới là phần quyết định chứng chỉ của bạn có thực sự đáng tin hay không.

Hướng dẫn này giải thích cách thu hồi hoạt động trong Open Badges, người nhận thấy và không thấy gì sau đó, và cách thu hồi một chứng chỉ hoặc vài trăm chứng chỉ tại https://badges.ninja, từ bảng điều khiển hoặc qua API.

”Revoke” nghĩa là gì trong Open Badges

Trong đặc tả Open Badges v2.0, mỗi huy hiệu đã cấp là một assertion: một tài liệu JSON-LD nhỏ được lưu tại một URL công khai, nói rằng “tổ chức cấp này đã trao huy hiệu này cho người nhận này vào ngày này.” Thu hồi chỉ đơn giản là thay đổi tài liệu được lưu đó. Assertion được thêm "revoked": true, và tùy chọn có chuỗi "revocationReason" giải thích lý do.

Thiết kế này dẫn đến một hệ quả quan trọng khiến nhiều chủ chương trình bất ngờ:

  • Assertion được lưu là nguồn sự thật. Bất kỳ ai xác minh chứng chỉ bằng cách mở URL assertion hoặc trang xác minh đều thấy ngay trạng thái đã thu hồi.
  • Các bản sao không bị thu lại. Nếu người nhận đã tải ảnh huy hiệu hoặc JSON về, hay ghim vào hồ sơ năng lực, tệp đó không thay đổi. Tệp vẫn chứa liên kết trỏ về assertion của bạn, nên người xác minh theo liên kết sẽ thấy nó đã bị thu hồi, nhưng người chỉ nhìn lướt ảnh PNG đã lưu thì không.

Vì vậy thu hồi là một tuyên bố tại điểm cuối xác minh, không phải là xóa. Hãy hình dung như đóng dấu “VOID” lên bản ghi gốc thay vì đuổi theo từng bản photocopy.

Nếu muốn xem kỹ hơn về tài liệu này, hướng dẫn JSON-LD của Open Badge của chúng tôi đi qua từng trường.

Thu hồi, cấp lại hay xóa: chọn đúng hành động

Trước khi bấm bất cứ thứ gì, hãy quyết định hành động nào trong ba hành động sau phù hợp với tình huống. Chúng không thể thay thế cho nhau.

Tình huốngHành động tốt nhấtLý do
Chứng chỉ cấp nhầm người hoặc có lỗi chính tảXóa (nếu chưa gửi) hoặc Revoke, rồi cấp lạiXóa loại bỏ hoàn toàn bản ghi; revoke giữ lại dấu vết kiểm toán
Học viên vi phạm chính sách hoặc chứng chỉ có được không chính đángRevoke, kèm lý doBản ghi vẫn xác minh được là đã thu hồi, đúng điều bạn cần khi có tranh chấp
Chứng chỉ chỉ đơn giản là đến ngày hết hạnKhông cần làm gì; đặt ngày hết hạn khi cấpHết hạn là một phần bình thường của vòng đời, không phải thu hồi
Chương trình bị hủy, khóa học bị vô hiệuBulk revokeMột job, một lý do, áp dụng cho tất cả
Thông tin sai nhưng chứng chỉ về cơ bản vẫn hợp lệChỉnh sửa trước khi gửi, hoặc revoke rồi cấp lại nếu đã gửiGiữ trải nghiệm của người nhận gọn gàng

Hai nguyên tắc cần nhớ:

  1. Với bất cứ thứ gì có thật, hãy ưu tiên revoke hơn xóa. Trang công khai của chứng chỉ đã xóa trả về lỗi not-found. Chứng chỉ đã thu hồi vẫn mở được và ghi rõ là đã bị thu hồi, bằng chứng tốt hơn nhiều nếu sau này ai đó hỏi chuyện gì đã xảy ra.
  2. Đừng bao giờ dùng thu hồi thay cho hết hạn. Nếu chứng chỉ chỉ có giá trị hai năm, hãy đặt ngày hết hạn khi cấp. Một huy hiệu lặng lẽ hết hạn khác với một huy hiệu bị rút lại, và trang xác minh của bạn nên nói rõ là trường hợp nào.

Thu hồi từ bảng điều khiển

Với một vài chứng chỉ, bảng điều khiển là cách nhanh nhất và không cần viết mã.

  1. Đăng nhập và mở Awards ở thanh bên.
  2. Tìm chứng chỉ. Danh sách hiển thị người nhận, tên huy hiệu, ngày cấp và ngày hết hạn, và bạn có thể tìm theo người nhận.
  3. Bấm vào dòng đó (hoặc View) để mở hộp thoại chi tiết chứng chỉ.
  4. Bấm Revoke.
  5. Trong hộp thoại xác nhận, có thể nhập lý do, và có thể tích Email the recipient that their credential was revoked.
  6. Xác nhận.

Award detail modal

Chứng chỉ vẫn nằm trong danh sách của bạn với nhãn đỏ Revoked bên cạnh người nhận, để bạn và nhóm luôn thấy được những gì đã bị rút lại. Thu hồi không hoàn lại chứng chỉ vào hạn mức gói của bạn. Bạn đã cấp nó, nó đã được tính.

Lưu ý về trường lý do

Lý do là tùy chọn, nhưng hãy điền. Nó được lưu cùng chứng chỉ, xuất hiện dưới dạng revocationReason trong assertion Open Badges công khai, và có trong payload webhook mà hệ thống của bạn nhận được. Vì nó công khai trên assertion, hãy viết như viết cho người đọc bên ngoài. “Issued in error” hoặc “Program cancelled” thì được. “Jane gian lận ở câu 14” thì không. Hãy giữ chi tiết cá nhân trong hồ sơ nội bộ và giữ lý do công khai ở mức trung lập.

Có nên gửi email cho người nhận không?

Thường là có. Một học viên chỉ biết chứng chỉ của mình đã vô hiệu khi nhà tuyển dụng bấm vào liên kết xác minh hoàn toàn có quyền bực bội với bạn. Thông báo là tùy chọn chính vì một số lần thu hồi (ví dụ dọn dẹp hàng loạt các award thử nghiệm) không cần làm phiền ai. Gợi ý của chúng tôi:

  • Gửi email khi việc thu hồi ảnh hưởng đến một người thật có thể vẫn đang trưng bày chứng chỉ đó.
  • Bỏ qua email khi bạn đang dọn dữ liệu thử nghiệm nội bộ hoặc vô hiệu hóa những chứng chỉ chưa từng được gửi.

Thu hồi nhiều chứng chỉ cùng lúc

Chương trình hiếm khi cần thu hồi một chứng chỉ riêng lẻ; thường là cả một khóa. Trong danh sách Awards:

  1. Tích chọn các chứng chỉ bạn muốn rút lại.
  2. Bấm Revoke selected trên thanh thao tác hàng loạt.
  3. Thêm lý do và quyết định có thông báo cho người nhận hay không, rồi xác nhận.

Thu hồi hàng loạt chạy dưới dạng một job nền bền vững, nên vài trăm chứng chỉ sẽ không làm tab trình duyệt của bạn bị timeout. Các chứng chỉ đã thu hồi sẽ được bỏ qua thay vì làm hỏng cả lô, và job bị gián đoạn giữa chừng có thể tiếp tục. Cơ chế này cũng vận hành việc cấp hàng loạt từ bảng tính, mà chúng tôi đã đề cập trong cách cấp Open Badges từ CSV.

Thu hồi qua API

Nếu hệ thống học tập hoặc nền tảng nhân sự của bạn quyết định ai không còn được chứng nhận, bạn có thể thu hồi bằng lập trình. Endpoint là POST /awards/{awardId}/revoke, xác thực bằng API key (X-Api-Key: bws_<32-hex>) hoặc Bearer token của Cognito. ID award nằm trong đường dẫn; reason và notify nằm trong body JSON và cả hai đều tùy chọn.

Dùng curl:

curl -X POST https://api.badges.ninja/awards/<award-id>/revoke \
  -H "X-Api-Key: bws_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Issued to the wrong recipient","notify":true}'
# 200 -> {"revoked":true,"awardId":"<award-id>"}

Trong JavaScript:

const res = await fetch(`https://api.badges.ninja/awards/${awardId}/revoke`, {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "Program cancelled", notify: false }),
});
const { revoked } = await res.json(); // true

Và trong Python:

import requests
res = requests.post(
    f"https://api.badges.ninja/awards/{award_id}/revoke",
    headers={"X-Api-Key": API_KEY},
    json={"reason": "Program cancelled", "notify": False},
)
print(res.json()["revoked"])  # True

Một vài chi tiết thực tế đáng biết:

  • Nó có tính idempotent. Thu hồi một chứng chỉ đã thu hồi sẽ trả về cùng phản hồi thành công và không gửi thông báo lần hai. Nhờ vậy gọi từ một job có retry là an toàn.
  • Lý do bị cắt còn tối đa 500 ký tự.
  • notify mặc định là false. Sẽ không có email nào được gửi trừ khi bạn yêu cầu.
  • Bulk revoke có sẵn qua endpoint hàng loạt với action: "revoke" và danh sách ID award; nó trả về một job ID để bạn theo dõi. Đầy đủ tham số có trong tài liệu API awards.

Bạn chỉ cần API khi việc thu hồi do một hệ thống khác điều khiển. Với một lần đơn lẻ, bảng điều khiển nhanh hơn và có bước xác nhận giúp bạn tránh nhập sai ID.

Người nhận và người xác minh thấy gì

Sau khi bạn thu hồi, đây là những gì thay đổi và nhanh đến mức nào.

Trên trang xác minh công khai. Trang tại https://badges.ninja/awards/<award-id> hiển thị chứng chỉ là đã thu hồi, và tiêu đề trang khi chia sẻ lên mạng xã hội được thêm tiền tố “[Revoked]” để liên kết được chia sẻ không trông như một chứng chỉ còn hiệu lực trong thẻ xem trước.

Trong assertion Open Badges v2.0. JSON được lưu tại https://api.badges.ninja/certify-badge/award/<award-id> giờ có "revoked": true, kèm "revocationReason" nếu bạn đã nhập. Assertion đã thu hồi chỉ được cache khoảng 30 giây, trong khi assertion còn hiệu lực được cache năm phút, nên thay đổi đến tay người xác minh rất nhanh.

Trong chứng chỉ Open Badges 3.0. Việc thu hồi cũng lật bit của chứng chỉ trong W3C Bitstring Status List, cách mà ví verifiable credential và người xác minh dùng để phát hiện. Danh sách này được cache ngắn, nên hãy kỳ vọng lan truyền trong khoảng một phút. Nếu bạn đang cân nhắc giữa hai phiên bản, xem Open Badges v2 vs v3.

Trên bản sao của chính người nhận. Không có gì thay đổi với tệp họ đã tải. Ảnh huy hiệu trên laptop của họ trông y hệt. Cái thay đổi là kết quả xác minh: bất kỳ ai bấm vào liên kết hoặc kiểm tra chứng chỉ bằng lập trình đều nhận được câu trả lời đã thu hồi. Nếu bạn đã thông báo, họ cũng có một email giải thích lý do.

Trên LinkedIn. Chứng chỉ được thêm vào hồ sơ LinkedIn là một liên kết kèm siêu dữ liệu trỏ về trang xác minh của bạn. LinkedIn không tự kiểm tra việc thu hồi thay bạn, nên mục đó có thể vẫn nằm trên hồ sơ, nhưng ai theo liên kết sẽ đến trang báo đã thu hồi. Đây là một lý do nữa để gửi thông báo và đề nghị người nhận gỡ mục đó.

Thông báo cho hệ thống của bạn: webhook

Thu hồi hiếm khi là hồi kết bên trong tổ chức của bạn. Học viên có thể cần mất quyền truy cập vào một cộng đồng, hồ sơ nhà tuyển dụng cần cập nhật, hoặc thẻ CRM cần gỡ. Badges Ninja phát sự kiện webhook credential.revoked khi một chứng chỉ bị thu hồi, kèm URL award và lý do:

{
  "awardId": "https://api.badges.ninja/certify-badge/award/<award-id>",
  "reason": "Issued in error"
}

Hãy đăng ký nhận sự kiện này và các hệ thống phía sau của bạn luôn đồng bộ mà không ai phải nhớ cập nhật. Chi tiết thiết lập có trong tài liệu webhook, và mô hình sự kiện rộng hơn được chúng tôi trình bày ở thiết lập webhook cho sự kiện huy hiệu.

Một chính sách thu hồi đơn giản bạn có thể áp dụng ngay hôm nay

Công cụ là nửa dễ. Nửa khó hơn là quyết định trước khi nào sẽ thu hồi và ai được phép. Một chính sách viết ngắn gọn sẽ tránh tranh cãi về sau. Một mẫu khả dụng:

  1. Căn cứ thu hồi. Liệt kê: cấp nhầm, đạt được do vi phạm, không còn đáp ứng yêu cầu (ví dụ tư cách thành viên hết hạn), hoặc chương trình bị rút.
  2. Ai quyết định. Nêu một vai trò, không phải một cá nhân. Giới hạn quyền revoke cho vai trò đó.
  3. Thông báo. Nêu rõ người nhận được báo qua email kèm lý do, trừ khi chứng chỉ chưa từng được gửi.
  4. Khiếu nại. Cho người nhận cách phản đối quyết định và nói rõ bạn sẽ phản hồi trong bao lâu. Nếu khiếu nại thành công, hãy cấp một chứng chỉ mới thay vì cố hoàn tác việc thu hồi, để lịch sử luôn sạch sẽ.
  5. Ghi chép. Lưu ghi chú nội bộ về ai đã thu hồi gì và vì sao, tách biệt với lý do công khai trung lập.

Hãy công bố chính sách ngay trên trang mô tả chứng chỉ, để người nhận biết quy tắc trước khi đăng ký.

Những lỗi thường gặp cần tránh

  • Xóa trong khi định thu hồi. Xóa là vĩnh viễn và không thể hoàn tác, và khiến trang công khai biến mất. Chỉ dùng cho những sai sót thực sự trên chứng chỉ chưa ai nhìn thấy.
  • Đưa chi tiết riêng tư vào lý do. Nó công khai trên assertion.
  • Mong các bản sao đã lưu thay đổi. Thu hồi nằm ở điểm cuối xác minh. Hãy bảo người nhận gỡ chứng chỉ khỏi hồ sơ và portfolio của họ.
  • Thu hồi thay vì cho hết hạn. Hãy dùng ngày hết hạn cho các chứng chỉ có thời hạn.
  • Cho rằng sẽ được hoàn lại. Chứng chỉ đã thu hồi vẫn tính vào hạn mức gói của bạn.
  • Quên các hệ thống phía sau. Hãy nối webhook để quyền truy cập và hồ sơ đi theo trạng thái của chứng chỉ.

Câu hỏi thường gặp

Tôi có thể hoàn tác việc thu hồi không? Không qua giao diện. Nếu bạn thu hồi nhầm, hãy cấp chứng chỉ mới cho người nhận. Chứng chỉ đã thu hồi vẫn còn như một phần của dấu vết kiểm toán.

Người nhận có cần làm gì không? Không. Nếu bạn chọn thông báo, họ nhận một email. Nếu không, thay đổi diễn ra lặng lẽ trên trang xác minh.

Thu hồi có áp dụng cho chứng chỉ chưa từng được gửi không? Có, tuy với chứng chỉ chưa gửi chỉ có lỗi đơn giản, bạn có thể muốn chỉnh sửa trước khi gửi, hoặc xóa nếu chưa ai thấy.

Có giới hạn số lượng tôi có thể thu hồi không? Thu hồi hàng loạt chạy dưới dạng job nền có thể tiếp tục, nên các lô lớn được xử lý trong một thao tác thay vì từng cái một.

Nhà tuyển dụng có thấy chứng chỉ đã bị thu hồi không? Bất kỳ ai xác minh qua URL công khai hoặc assertion đều thấy trạng thái đã thu hồi và lý do, nếu bạn có nhập.

Kết luận

Thu hồi một Open Badge là một hành động nhỏ nhưng ảnh hưởng thực sự đến niềm tin. Hãy làm từ bảng điều khiển khi chỉ có một chứng chỉ, dùng bulk revoke cho cả một khóa, và dùng API hoặc webhook khi một hệ thống khác nắm quyền quyết định. Giữ lý do trung lập, thông báo cho những người cần biết, và nhớ rằng thu hồi thay đổi những gì người xác minh thấy, chứ không phải các tệp đã nằm trong tay người nhận.

Sẵn sàng cấp chứng chỉ 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 nhận PDF, đầu ra Open Badge v2.0. Không cần thẻ tín dụng.

Nacho Coll

Về tác giả

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Quay lại Blog

Bài viết liên quan