Cum revoci o insignă Open Badge (și ce se întâmplă cu copia destinatarului)

Revocarea în Open Badges: cum funcționează, ce se schimbă pentru destinatar și cum tratezi corect cazurile „emisă din greșeală”, „credențial expirat” și „încălcarea regulilor”.

Nacho Coll De Actualizat 10 min de citit
Revocarea în Open Badges: cum funcționează, ce se schimbă pentru destinatar și cum tratezi corect cazurile „emisă din greșeală”, „credențial expirat” și „încălcarea regulilor”.

Mai devreme sau mai târziu, orice program care emite credențiale digitale trebuie să retragă una. Un certificat a ajuns la persoana greșită. S-a descoperit că un cursant a fraudat evaluarea finală. Un contract de parteneriat s-a încheiat, iar insignele care spuneau „Partener certificat” nu mai trebuie să fie valide. Emiterea e partea ușoară; revocarea decide dacă credențialele tale chiar merită încredere.

Ghidul acesta explică cum funcționează revocarea în Open Badges, ce vede și ce nu vede destinatarul după aceea și cum revoci o singură credențială sau câteva sute pe https://badges.ninja, din dashboard sau prin API.

Ce înseamnă „revocare” în Open Badges

În specificația Open Badges v2.0, fiecare insignă emisă este o aserțiune (assertion): un mic document JSON-LD găzduit la o adresă publică, care spune „acest emitent a acordat această insignă acestui destinatar la această dată”. Revocarea este pur și simplu o modificare a acelui document găzduit. Aserțiunea primește "revoked": true și, opțional, un șir "revocationReason" care explică motivul.

Designul acesta are o consecință importantă, care îi surprinde pe mulți responsabili de program:

  • Aserțiunea găzduită este sursa adevărului. Oricine verifică credențiala accesând URL-ul aserțiunii sau pagina de verificare vede imediat starea de revocare.
  • Copiile nu sunt retrase. Dacă destinatarul a descărcat imaginea insignei sau JSON-ul, ori a fixat-o într-un portofoliu, fișierul acela nu se schimbă. Conține în continuare un link către aserțiunea ta găzduită, deci un verificator care urmează linkul va vedea că e revocată, dar cineva care se uită în treacăt la un PNG salvat nu va vedea nimic.

Revocarea este, așadar, o declarație făcută la punctul de verificare, nu o ștergere. Gândește-te la ea ca la ștampila „ANULAT” pe înregistrarea principală, nu ca la alergatul după fiecare xerocopie.

Dacă vrei să vezi mai îndeaproape documentul în sine, ghidul nostru despre Open Badge JSON-LD parcurge fiecare câmp.

Revocare, reemitere sau ștergere: alege acțiunea potrivită

Înainte să dai click pe orice, decide care dintre cele trei acțiuni se potrivește situației. Nu sunt interschimbabile.

SituațieCea mai bună acțiuneDe ce
Credențiala a fost emisă persoanei greșite sau cu o greșeală de scriereȘterge (dacă nu a fost trimisă) sau Revocă, apoi reemiteȘtergerea elimină complet înregistrarea; revocarea păstrează o urmă de audit
Cursantul a încălcat o regulă sau credențiala a fost obținută incorectRevocă, cu un motivÎnregistrarea rămâne verificabilă ca revocată, exact ce îți trebuie într-o dispută
Credențiala și-a atins pur și simplu data de expirareNu face nimic; setează o expirare la emitereExpirarea este un eveniment normal din ciclul de viață, nu o revocare
Program anulat, cohortă invalidatăRevocare în masăO singură operațiune, un singur motiv, aplicat tuturor
Detaliile erau greșite, dar credențiala este altfel validăEditează înainte de trimitere, sau revocă și reemite după trimiterePăstrează experiența destinatarului curată

Două reguli simple:

  1. Preferă revocarea ștergerii pentru tot ce e real. Pagina publică a unei credențiale șterse returnează o eroare de tip „negăsit”. Una revocată se deschide în continuare și spune clar că este revocată, ceea ce e o dovadă mult mai bună dacă cineva întreabă mai târziu ce s-a întâmplat.
  2. Nu folosi niciodată revocarea în locul expirării. Dacă o credențială e valabilă doar doi ani, setează o dată de expirare când o emiți. O insignă care expiră discret e altceva decât una retrasă, iar pagina ta de verificare ar trebui să spună care e cazul.

Revocarea din dashboard

Pentru câteva credențiale, dashboardul este cea mai rapidă cale și nu necesită cod.

  1. Autentifică-te și deschide Awards din bara laterală.
  2. Găsește credențiala. Lista afișează destinatarul, numele insignei, data emiterii și expirarea, și poți căuta după destinatar.
  3. Dă click pe rând (sau pe View) ca să deschizi fereastra cu detaliile credențialei.
  4. Apasă Revoke.
  5. În dialogul de confirmare, introdu opțional un motiv și bifează opțional Email the recipient that their credential was revoked.
  6. Confirmă.

Award detail modal

Credențiala rămâne în listă, cu o etichetă roșie Revoked lângă destinatar, astfel încât tu și echipa ta să vedeți mereu ce a fost retras. Revocarea nu returnează credențiala în cota planului tău. Ai emis-o, a contat.

O notă despre câmpul „motiv”

Motivul este opțional, dar completează-l. Se stochează împreună cu credențiala, apare ca revocationReason în aserțiunea publică Open Badges și este inclus în payload-ul webhook-ului primit de sistemele tale. Fiindcă este public pe aserțiune, scrie-l ca pentru un cititor din exterior. „Emisă din greșeală” sau „Program anulat” e în regulă. „Ioana a copiat la întrebarea 14” nu e. Păstrează detaliile personale în evidențele tale și lasă motivul public neutru.

Să-i trimiți email destinatarului?

De obicei, da. Un cursant care află că i s-a anulat credențiala abia când un angajator dă click pe linkul de verificare are tot dreptul să fie nemulțumit de tine. Notificarea este opțională tocmai pentru că unele revocări (de exemplu o curățare în masă a premiilor de test) nu trebuie să deranjeze pe nimeni. Recomandarea noastră:

  • Trimite email când revocarea afectează o persoană reală care ar putea încă să afișeze credențiala.
  • Sari peste email când ordonezi date interne de test sau anulezi credențiale care nu au fost niciodată trimise.

Revocarea mai multor credențiale simultan

Rareori un program trebuie să revoce o credențială izolată; mai des este vorba de o cohortă întreagă. În lista Awards:

  1. Bifează casetele credențialelor pe care vrei să le retragi.
  2. Apasă Revoke selected în bara de acțiuni în masă.
  3. Adaugă un motiv și decide dacă notifici destinatarii, apoi confirmă.

Revocarea în masă rulează ca job de fundal durabil, deci câteva sute de credențiale nu vor bloca fila din browser. Credențialele deja revocate sunt sărite, în loc să eșueze tot lotul, iar un job întrerupt pe parcurs poate fi reluat. Același mecanism stă la baza emiterii în masă dintr-o foaie de calcul, pe care o tratăm în cum emiți Open Badges dintr-un CSV.

Revocarea prin API

Dacă sistemul tău de învățare sau platforma HR decide cine nu mai este certificat, poți revoca programatic. Endpoint-ul este POST /awards/{awardId}/revoke, autentificat cu o cheie API (X-Api-Key: bws_<32-hex>) sau cu un token Bearer Cognito. ID-ul premiului merge în cale; reason și notify merg în corpul JSON și ambele sunt opționale.

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

În 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

Și în 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

Câteva detalii practice utile:

  • Este idempotent. Revocarea unei credențiale deja revocate returnează același răspuns de succes și nu trimite o a doua notificare. Astfel e sigur de apelat dintr-un job cu reîncercări.
  • Motivele sunt trunchiate la 500 de caractere.
  • notify este implicit false. Nu se trimite niciun email decât dacă ceri.
  • Revocarea în masă este disponibilă prin endpoint-ul bulk, cu action: "revoke" și o listă de ID-uri de premii; returnează un ID de job pe care îl poți urmări. Parametrii compleți sunt în referința API pentru awards.

Ai nevoie de API doar când revocarea e condusă de un alt sistem. Pentru o acțiune izolată, dashboardul e mai rapid și are un pas de confirmare care te ferește de un ID scris greșit.

Ce văd destinatarul și verificatorul

După ce revoci, iată ce se schimbă și cât de repede.

Pe pagina publică de verificare. Pagina de la https://badges.ninja/awards/<award-id> afișează credențiala ca revocată, iar titlul paginii pentru partajare socială are prefixul „[Revoked]”, ca un link distribuit să nu arate ca o credențială activă într-un card de previzualizare.

În aserțiunea Open Badges v2.0. JSON-ul găzduit la https://api.badges.ninja/certify-badge/award/<award-id> conține acum "revoked": true, plus "revocationReason" dacă ai dat unul. Aserțiunile revocate sunt păstrate în cache doar aproximativ 30 de secunde, față de cinci minute pentru cele active, deci schimbarea ajunge rapid la verificatori.

În credențiala Open Badges 3.0. Revocarea comută și bitul credențialei într-un W3C Bitstring Status List, prin care wallet-urile de credențiale verificabile și verificatorii o detectează. Lista este păstrată scurt în cache, deci așteaptă-te la propagare în cam un minut. Dacă compari cele două versiuni, vezi Open Badges v2 vs v3.

În copia proprie a destinatarului. Nimic nu se schimbă în fișierul descărcat. Imaginea insignei de pe laptopul lui arată identic. Se schimbă rezultatul verificării: oricine dă click sau verifică credențiala programatic primește răspunsul „revocată”. Dacă l-ai notificat, are și un email care explică motivul.

Pe LinkedIn. O credențială adăugată pe un profil LinkedIn este un link plus metadate care trimit înapoi la pagina ta de verificare. LinkedIn nu interoghează periodic starea de revocare în numele tău, deci intrarea poate rămâne pe profil, dar oricine urmează linkul ajunge pe pagina de revocare. Încă un motiv să trimiți notificarea și să-i ceri destinatarului să elimine intrarea.

Anunță-ți propriile sisteme: webhook-uri

Revocarea rareori se oprește aici în organizația ta. Cursantul poate trebui să piardă accesul la o comunitate, o înregistrare de angajator poate cere actualizare sau un tag din CRM trebuie eliminat. Badges Ninja emite un eveniment webhook credential.revoked când o credențială este revocată, cu URL-ul premiului și motivul:

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

Abonează-te la el și sistemele tale din aval rămân sincronizate fără ca cineva să-și amintească să le actualizeze. Detaliile de configurare sunt în documentația webhook-urilor, iar modelul mai larg de evenimente îl tratăm în configurarea webhook-urilor pentru evenimentele insignelor.

O politică simplă de revocare pe care o poți adopta azi

Uneltele sunt jumătatea ușoară. Jumătatea grea este să decizi dinainte când vei revoca și cine are voie. O politică scurtă, scrisă, previne discuții ulterioare. Un șablon funcțional:

  1. Motive de revocare. Enumeră-le: emisă din greșeală, obținută prin fraudă, cerință care nu mai e îndeplinită (de exemplu, o calitate de membru expirată) sau program retras.
  2. Cine decide. Numește un rol, nu o persoană. Limitează permisiunea de revocare la acel rol.
  3. Notificare. Precizează că destinatarii sunt anunțați prin email, cu motivul, dacă credențiala nu a fost livrată niciodată.
  4. Contestație. Oferă destinatarilor o cale de a contesta decizia și spune în cât timp răspunzi. Dacă o contestație reușește, reemite o credențială nouă în loc să încerci să anulezi revocarea, ca istoricul să rămână curat.
  5. Evidență. Păstrează o notă internă despre cine a revocat ce și de ce, separat de motivul public neutru.

Publică politica pe aceeași pagină unde descrii credențiala, ca cei care o obțin să știe regulile înainte să se înscrie.

Greșeli frecvente de evitat

  • Ștergere în loc de revocare. Ștergerea este permanentă, nu poate fi anulată și face să dispară pagina publică. Folosește-o pentru greșeli reale la credențiale pe care nu le-a văzut nimeni.
  • Detalii private în motiv. Este public pe aserțiune.
  • Așteptarea ca exemplarele salvate să se schimbe. Revocarea trăiește la punctul de verificare. Spune-le destinatarilor să elimine credențiala din profiluri și portofolii.
  • Revocare în loc de expirare. Folosește o dată de expirare pentru credențialele limitate în timp.
  • Presupunerea unei rambursări. Credențialele revocate se numără în continuare în cota planului.
  • Uitarea sistemelor din aval. Conectează webhook-ul ca accesul și evidențele să urmeze starea credențialei.

Întrebări frecvente

Pot anula o revocare? Nu din interfață. Dacă ai revocat din greșeală, emite o credențială nouă destinatarului. Cea revocată rămâne parte din urma de audit.

Trebuie să facă ceva destinatarul? Nu. Dacă ai ales să-l notifici, primește un email. Altfel, schimbarea se petrece discret pe pagina de verificare.

Funcționează revocarea pentru credențiale netrimise? Da, deși pentru o credențială netrimisă cu o greșeală simplă poți prefera să o editezi înainte de trimitere sau să o ștergi dacă n-a văzut-o nimeni.

Există o limită la câte pot revoca? Revocarea în masă rulează ca job de fundal reluabil, deci loturile mari se tratează într-o singură operațiune, nu una câte una.

Vor vedea angajatorii că o credențială a fost revocată? Oricine o verifică prin URL-ul public sau aserțiune vede starea revocată și motivul, dacă ai dat unul.

Concluzie

Revocarea unei insigne Open Badge este o acțiune mică, cu consecințe reale pentru încredere. Fă-o din dashboard pentru o singură credențială, folosește revocarea în masă pentru o cohortă și apelează la API sau la webhook-uri când decizia aparține altui sistem. Păstrează motivele neutre, notifică-i pe cei care trebuie să știe și nu uita că revocarea schimbă ce văd verificatorii, nu fișierele deja aflate la destinatari.

Ești gata să emiți prima ta credențială verificabilă? Începe gratuit pe badges.ninja — designer vizual, pagină publică de verificare, certificat PDF, ieșire Open Badge v2.0. Fără card de credit.

Nacho Coll

Despre autor

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.

Înapoi la Blog

Articole similare