Jak odvolat Open Badge (a co se stane s kopií příjemce)

Odvolání v Open Badges: jak funguje, co se mění pro příjemce a jak správně rozlišit „vydáno omylem“, „platnost skončila“ a „porušení pravidel“.

Nacho Coll Autor Aktualizováno 9 min čtení
Odvolání v Open Badges: jak funguje, co se mění pro příjemce a jak správně rozlišit „vydáno omylem“, „platnost skončila“ a „porušení pravidel“.

Dříve nebo později musí každý program vydávající digitální osvědčení nějaké vzít zpět. Certifikát šel nesprávné osobě. Zjistilo se, že účastník podváděl u závěrečného hodnocení. Smlouva s partnerem skončila a odznaky s nápisem „Certified Partner“ už nemají platit. Vydávání je ta příjemná cesta; odvolání rozhoduje o tom, zda lze vašim osvědčením skutečně důvěřovat.

Tento průvodce vysvětluje, jak odvolání v Open Badges funguje, co příjemce poté vidí a co ne, a jak odvolat jedno osvědčení nebo několik set na https://badges.ninja — z řídicího panelu nebo přes API.

Co znamená „odvolat“ v Open Badges

Ve specifikaci Open Badges v2.0 je každý vydaný odznak assertion: malý dokument JSON-LD hostovaný na veřejné URL, který říká: „tento vydavatel udělil tento odznak tomuto příjemci tohoto dne.“ Odvolání je jednoduše změna tohoto hostovaného dokumentu. Assertion získá "revoked": true a volitelně řetězec "revocationReason" s vysvětlením důvodu.

Tento návrh má důležitý důsledek, který mnoho vlastníků programů překvapí:

  • Hostovaný assertion je zdrojem pravdy. Každý, kdo osvědčení ověřuje načtením URL assertion nebo otevřením ověřovací stránky, okamžitě vidí stav „odvoláno“.
  • Kopie se nevolají zpět. Pokud příjemce stáhl obrázek odznaku nebo JSON či si ho připnul do portfolia, tento soubor se nemění. Stále obsahuje odkaz na váš hostovaný assertion, takže ověřovatel, který odkaz otevře, uvidí odvolání, ale člověk, který se jen podívá na uložené PNG, ne.

Odvolání je tedy prohlášení učiněné na ověřovacím koncovém bodě, nikoli smazání. Představte si to jako razítko „NEPLATNÉ“ na hlavním záznamu, místo abyste honili každou fotokopii.

Pokud se chcete podívat na samotný dokument zblízka, náš rozbor Open Badge JSON-LD prochází každé pole.

Odvolat, vydat znovu, nebo smazat: vyberte správnou akci

Než na cokoli kliknete, rozhodněte, která ze tří akcí se pro situaci hodí. Nejsou zaměnitelné.

SituaceNejlepší akceProč
Osvědčení bylo vydáno nesprávné osobě nebo s překlepemSmazat (pokud nebylo odesláno) nebo odvolat a poté vydat znovuSmazání odstraní záznam úplně; odvolání zachová auditní stopu
Účastník porušil pravidla nebo bylo osvědčení získáno nepatřičněOdvolat s uvedením důvoduZáznam zůstane ověřitelný jako odvolaný, což ve sporu chcete
Osvědčení jednoduše dosáhlo koncového dataNedělat nic; při vydání nastavte platnostVypršení platnosti je běžná událost životního cyklu, nikoli odvolání
Program zrušen, kohorta anulovánaHromadné odvoláníJedna úloha, jeden důvod, použitý na všechny
Údaje byly chybné, ale osvědčení je jinak platnéUpravit před odesláním, nebo odvolat a po odeslání vydat znovuZachová příjemci příjemnou zkušenost

Dvě praktická pravidla:

  1. U všeho skutečného dávejte přednost odvolání před smazáním. Veřejná stránka smazaného osvědčení vrací chybu „nenalezeno“. Odvolané se stále zobrazí a jasně říká, že je odvolané, což je mnohem lepší důkaz, pokud se později někdo zeptá, co se stalo.
  2. Nikdy nepoužívejte odvolání jako náhradu za vypršení platnosti. Pokud je osvědčení platné jen dva roky, nastavte datum vypršení při vydání. Odznak, který tiše pozbyl platnosti, se liší od staženého a vaše ověřovací stránka by měla říkat, o který případ jde.

Odvolání z řídicího panelu

U několika osvědčení je panel nejrychlejší cestou a nevyžaduje žádný kód.

  1. Přihlaste se a otevřete Awards v postranním panelu.
  2. Najděte osvědčení. Seznam ukazuje příjemce, název odznaku, datum vydání a vypršení a můžete vyhledávat podle příjemce.
  3. Klikněte na řádek (nebo View) a otevřete detail osvědčení.
  4. Klikněte na Revoke.
  5. V potvrzovacím dialogu volitelně zadejte důvod a volitelně zaškrtněte Email the recipient that their credential was revoked.
  6. Potvrďte.

Award detail modal

Osvědčení zůstane ve vašem seznamu s červeným štítkem Revoked vedle příjemce, takže vy i váš tým vždy vidíte, co bylo staženo. Odvolání nevrací osvědčení do kvóty vašeho plánu. Vydali jste ho, takže se započítalo.

Poznámka k poli s důvodem

Důvod je volitelný, ale vyplňte ho. Ukládá se spolu s osvědčením, objeví se jako revocationReason ve veřejném assertion Open Badges a je součástí payloadu webhooku, který dostávají vaše systémy. Protože je v assertion veřejný, pište ho tak, jako byste psali pro cizího čtenáře. „Issued in error“ nebo „Program cancelled“ je v pořádku. „Jana podváděla u otázky 14“ není. Osobní údaje si nechte ve vlastních záznamech a veřejný důvod držte neutrální.

Mám příjemci poslat e-mail?

Obvykle ano. Účastník, který se o zneplatnění svého osvědčení dozví, až když zaměstnavatel klikne na ověřovací odkaz, má plné právo být na vás naštvaný. Upozornění je volitelné právě proto, že některá odvolání (například hromadný úklid testovacích udělení) nepotřebují nikoho obtěžovat. Naše doporučení:

  • E-mail posílejte, když se odvolání týká skutečné osoby, která může osvědčení stále zobrazovat.
  • E-mail vynechte, když uklízíte interní testovací data nebo anulujete osvědčení, která nikdy nebyla odeslána.

Odvolání mnoha osvědčení najednou

Programy zřídka potřebují odvolat jedno osvědčení izolovaně; častěji jde o celou kohortu. V seznamu Awards:

  1. Zaškrtněte políčka u osvědčení, která chcete stáhnout.
  2. Klikněte na Revoke selected v liště hromadných akcí.
  3. Přidejte důvod, rozhodněte, zda upozornit příjemce, a potvrďte.

Hromadné odvolání běží jako odolná úloha na pozadí, takže několik set osvědčení nevyčerpá časový limit karty prohlížeče. Osvědčení, která jsou již odvolána, se přeskočí místo toho, aby selhala celá dávka, a úlohu přerušenou v půlce lze obnovit. Stejný mechanismus pohání hromadné vydávání z tabulky, o kterém píšeme v jak vydávat Open Badges z CSV.

Odvolání přes API

Pokud váš vzdělávací systém nebo HR platforma rozhoduje, kdo už není certifikován, můžete odvolávat programově. Koncový bod je POST /awards/{awardId}/revoke, ověřovaný API klíčem (X-Api-Key: bws_<32-hex>) nebo tokenem Bearer z Cognito. ID udělení jde do cesty; reason a notify jdou do těla JSON a oba jsou volitelné.

Pomocí 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>"}

V JavaScriptu:

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

A v Pythonu:

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

Několik praktických detailů, které stojí za to znát:

  • Je idempotentní. Odvolání již odvolaného osvědčení vrací stejnou úspěšnou odpověď a neposílá druhé upozornění. Díky tomu je bezpečné volat ho z úlohy s opakováním.
  • Důvody se zkracují na 500 znaků.
  • notify je ve výchozím stavu false. Nic se neposílá e-mailem, dokud o to nepožádáte.
  • Hromadné odvolání je dostupné přes hromadný koncový bod s action: "revoke" a seznamem ID udělení; vrací ID úlohy, kterou můžete sledovat. Úplné parametry jsou v referenci API awards.

API potřebujete jen tehdy, když odvolání řídí jiný systém. Pro jednorázový případ je panel rychlejší a má potvrzovací krok, který chrání před překlepem v ID.

Co vidí příjemce a ověřovatel

Po odvolání se mění následující, a to takto rychle.

Na veřejné ověřovací stránce. Stránka na https://badges.ninja/awards/<award-id> zobrazuje osvědčení jako odvolané a titulek stránky pro sdílení na sociálních sítích dostane předponu „[Revoked]“, aby sdílený odkaz v náhledové kartě nevypadal jako platné osvědčení.

V assertion Open Badges v2.0. Hostovaný JSON na https://api.badges.ninja/certify-badge/award/<award-id> nyní nese "revoked": true a také "revocationReason", pokud jste jej uvedli. Odvolané assertiony se cachují jen asi 30 sekund, zatímco platné pět minut, takže se změna dostane k ověřovatelům rychle.

V osvědčení Open Badges 3.0. Odvolání také přepne bit osvědčení v seznamu W3C Bitstring Status List, podle kterého ho detekují peněženky a ověřovatelé verifiable credentials. Tento seznam se cachuje krátce, takže počítejte s propagací do přibližně minuty. Pokud porovnáváte obě verze, viz Open Badges v2 vs v3.

Ve vlastní kopii příjemce. Ve staženém souboru se nic nemění. Obrázek odznaku na jeho notebooku vypadá stejně. Mění se výsledek ověření: každý, kdo klikne na odkaz nebo osvědčení zkontroluje programově, dostane odpověď „odvoláno“. Pokud jste ho upozornili, má také e-mail s vysvětlením důvodu.

Na LinkedIn. Osvědčení přidané do profilu na LinkedIn je odkaz plus metadata ukazující na vaši ověřovací stránku. LinkedIn za vás odvolání nekontroluje, takže záznam může na profilu zůstat, ale každý, kdo odkaz otevře, skončí na stránce s odvoláním. To je další důvod poslat upozornění a požádat příjemce o odstranění záznamu.

Informujte vlastní systémy: webhooky

Odvolání málokdy končí uvnitř vaší organizace. Účastník může přijít o přístup do komunity, může být nutné aktualizovat záznam zaměstnavatele nebo odstranit štítek v CRM. Badges Ninja vysílá událost webhooku credential.revoked, když je osvědčení odvoláno, s URL udělení a důvodem:

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

Přihlaste se k jejímu odběru a vaše navazující systémy zůstanou synchronizované, aniž by si někdo musel pamatovat ruční aktualizace. Podrobnosti nastavení jsou v dokumentaci webhooků a širší model událostí rozebíráme v nastavení webhooků pro události odznaků.

Jednoduchá politika odvolávání, kterou můžete přijmout hned dnes

Nástroje jsou ta snazší polovina. Těžší je předem rozhodnout, kdy budete odvolávat a kdo k tomu má oprávnění. Krátká písemná politika předchází pozdějším sporům. Použitelná šablona:

  1. Důvody odvolání. Vyjmenujte je: vydáno omylem, získáno pochybením, požadavek již není splněn (například zanikl členský vztah) nebo program stažen.
  2. Kdo rozhoduje. Uveďte roli, ne osobu. Oprávnění odvolávat omezte na tuto roli.
  3. Upozornění. Uveďte, že příjemci jsou informováni e-mailem s důvodem, pokud osvědčení nebylo nikdy doručeno.
  4. Odvolání se proti rozhodnutí. Dejte příjemcům možnost rozhodnutí zpochybnit a řekněte, jak dlouho bude odpověď trvat. Pokud bude námitka úspěšná, vydejte nové osvědčení, místo abyste se pokoušeli odvolání vzít zpět — historie zůstane čistá.
  5. Záznam. Veďte interní poznámku o tom, kdo co odvolal a proč, odděleně od neutrálního veřejného důvodu.

Politiku zveřejněte na stejné stránce, kde osvědčení popisujete, aby držitelé znali pravidla ještě před přihlášením.

Běžné chyby, kterým se vyhnout

  • Smazání místo odvolání. Smazání je trvalé a nelze ho vrátit a veřejná stránka zmizí. Používejte je pro skutečné chyby u osvědčení, která nikdo neviděl.
  • Soukromé údaje v důvodu. V assertion je veřejný.
  • Očekávání, že se uložené kopie změní. Odvolání žije na ověřovacím koncovém bodě. Řekněte příjemcům, ať osvědčení odstraní z profilů a portfolií.
  • Odvolání místo vypršení platnosti. Pro časově omezená osvědčení použijte datum vypršení.
  • Předpoklad vrácení. Odvolaná osvědčení se stále započítávají do kvóty vašeho plánu.
  • Zapomenuté navazující systémy. Zapojte webhook, aby přístupy a záznamy následovaly stav osvědčení.

Často kladené otázky

Mohu odvolání vrátit zpět? Ne přes rozhraní. Pokud jste odvolali omylem, vydejte příjemci nové osvědčení. Odvolané zůstává součástí auditní stopy.

Musí příjemce něco udělat? Ne. Pokud jste zvolili upozornění, dostane e-mail. Jinak se změna děje tiše na ověřovací stránce.

Funguje odvolání u osvědčení, která nebyla nikdy odeslána? Ano, i když u neodeslaného osvědčení s jednoduchou chybou můžete dát přednost úpravě před odesláním, nebo smazání, pokud ho nikdo neviděl.

Existuje limit, kolik mohu odvolat? Hromadné odvolání běží jako obnovitelná úloha na pozadí, takže velké dávky se zvládnou jednou operací místo po jednom.

Uvidí zaměstnavatelé, že bylo osvědčení odvoláno? Každý, kdo ho ověřuje přes veřejnou URL nebo assertion, vidí stav odvolání a důvod, pokud jste jej uvedli.

Závěr

Odvolání Open Badge je malá akce se skutečnými důsledky pro důvěru. Z řídicího panelu to dělejte u jednoho osvědčení, pro kohortu použijte hromadné odvolání a po API či webhookách sáhněte, když rozhodnutí vlastní jiný systém. Pište neutrální důvody, upozorňujte ty, kdo to potřebují vědět, a pamatujte: odvolání mění to, co vidí ověřovatelé, nikoli soubory, které už příjemci mají.

Připraveni vydat své první ověřitelné osvědčení? Začněte zdarma na badges.ninja — vizuální designér, veřejná ověřovací stránka, PDF certifikát, výstup Open Badge v2.0. Kreditní karta není potřeba.

Nacho Coll

O autorovi

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.

Zpět na Blog

Související články