Izdajanje Open Badges prek REST API-ja Badges Ninja: hitri začetek

Večina programov poverilnic API-ja sploh ne potrebuje. Če vodite tečaj z nekaj sto diplomanti na leto, nadzorna plošča opravi vse: značko oblikujete v vizualnem oblikovalniku, naložite datoteko CSV, vsak prejemnik pa dobi stran za preverjanje in potrdilo v PDF-ju. Če ste v tem položaju, začnite z izdajanjem Open Badges iz datoteke CSV in se vrnite pozneje.

API se obrestuje, kadar naj poverilnice izdaja drug sistem: vaša učna platforma označi tečaj kot zaključen, vaše orodje za registracijo zaključi dogodek, vaš kadrovski sistem zabeleži opravljen modul o skladnosti. V takih primerih nihče ne želi vsak teden izvažati preglednice. En sam klic HTTP ob zaključku je preprostejši, prejemnik pa svojo značko dobi, dokler je dosežek še svež.

Ta hitri začetek vas popelje skozi celotno pot v štirih klicih: pridobite ključ, ustvarite izdajatelja, ustvarite značko, jo podelite. Nato si ogledamo, kako prejemniku predati povezavo za preverjanje in kako preveriti rezultat. Vsaka oblika zahtevka spodaj izvira iz razmeščenih obdelovalcev, zato jo lahko prilepite in zaženete.

Kaj potrebujete, preden začnete

• Brezplačen račun na badges.ninja. Za ta vodič zadošča načrt Free: vključuje 2 izdajatelja, 5 značk, 2 sedeža in 1 ključ API.
• En ključ API, ustvarjen na nadzorni plošči.
• Slika PNG ali JPG za značko ali značka, ki ste jo oblikovali v vizualnem oblikovalniku.

Osnovni naslov URL za vse je https://api.badges.ninja.

1. korak: ustvarite ključ API

Prijavite se, v stranski vrstici odprite API Keys in kliknite Create API Key. Dajte mu ime, ki pove, kje bo živel, na primer »LMS integration«, da boste ključe pri poznejši rotaciji lahko ločili.

Ključ je prikazan natanko enkrat. Takoj ga kopirajte v upravljalnik skrivnosti ali spremenljivko okolja. Ključi izgledajo kot bws_, ki mu sledi 32 šestnajstiških znakov, pošiljate pa jih v glavi X-Api-Key pri vsakem zahtevku. Preklic ključa na istem zaslonu začne veljati takoj.

Nekaj navad, ki vam pozneje prihranijo težave:

• Ključa nikoli ne dajajte v kodo sprednjega dela ali v javno skladišče. API kličite iz strežnika, brezstrežniške funkcije ali orodja za avtomatizacijo.
• Za vsako integracijo uporabite en ključ. Če eden pušča, prekličete eno integracijo namesto vseh.
• Nadzorna plošča sprejme tudi vašo prijavljeno sejo (Cognito JWT, poslan kot Authorization: Bearer), vendar je za skripte in integracije pravo orodje ključ API.

Vsi spodnji primeri berejo ključ iz spremenljivke okolja BADGES_API_KEY.

2. korak: ustvarite izdajatelja

Izdajatelj je organizacija, ki stoji za značko. Prikazan je na vsaki strani za preverjanje in v podatkih Open Badge v2.0, zato uporabite ime, ki ga ljudje res poznajo.

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Academy","url":"https://acme.example.com","email":"badges@acme.example.com"}'

Obvezna polja so name (vsaj 3 znaki), url (veljaven naslov http ali https) in email. Neobvezni polji sta logo (slika, kodirana v base64) in linkedinOrganizationId, ki na vaših javnih straneh poverilnic vklopi gumb Add to LinkedIn Profile.

Odgovor vsebuje identifikator izdajatelja:

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Vrednost obdržite natanko tako, kot je vrnjena. Je vhod za naslednji korak.

Preverjanje izdajatelja

Značke je mogoče ustvarjati samo pod preverjenim izdajateljem. Preverjanje poteka takole:

• Če se e-pošta izdajatelja ujema z e-pošto vašega računa, je izdajatelj preverjen samodejno. To je najhitrejša pot za prvi preizkus.
• Če je e-pošta drugačna, na ta naslov prispe e-pošta za preverjanje s kodo. Kodo potrdite na nadzorni plošči (ali prek API-ja izdajateljev), preden ustvarite značke.

Za ta vodič torej uporabite isto e-pošto, s katero ste se registrirali.

3. korak: ustvarite značko

Značka je ponovno uporabna predloga: ime, opis, merila in slika. Vsaka podelitev, ki jo izdate pozneje, kaže nazaj nanjo.

Zahtevek je navaden JSON. Slika gre vanj kot niz base64, zato se vam ni treba ukvarjati z nalaganjem multipart. Predpona data URL, kot je data:image/png;base64,, je sprejeta in odstranjena.

JavaScript (Node 18 ali novejši):

import { readFileSync } from "node:fs";
const API_KEY = process.env.BADGES_API_KEY;
const image = readFileSync("./badge.png").toString("base64");
const res = await fetch("https://api.badges.ninja/badges", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "JavaScript Fundamentals",
    description: "Demonstrates proficiency in core JavaScript concepts",
    criteria: "Completed the JavaScript Fundamentals course with a score of 80% or higher",
    image,
    issuerId: "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  }),
});
const { badgeId } = await res.json();
console.log(badgeId);

Python:

import base64, os, requests
API_KEY = os.environ["BADGES_API_KEY"]
with open("badge.png", "rb") as f:
    image = base64.b64encode(f.read()).decode()
res = requests.post(
    "https://api.badges.ninja/badges",
    headers={"X-Api-Key": API_KEY},
    json={
        "name": "JavaScript Fundamentals",
        "description": "Demonstrates proficiency in core JavaScript concepts",
        "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
        "image": image,
        "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    },
)
badge_id = res.json()["badgeId"]
print(badge_id)

Vseh pet polj (name, description, criteria, image, issuerId) je obveznih. Vredni omembe sta še dve neobvezni: shareText, privzeto besedilo, ki ga prejemniki vidijo ob deljenju na družbenih omrežjih (podpira označbi mest {{badge_name}}, {{issuer_name}} in {{award_url}}), ter designJson, ki shrani dokument vizualnega oblikovalnika, da lahko značko pozneje urejate plast za plastjo.

Uspeh vrne HTTP 200 z { "badgeId": "<id>" }. Slika je shranjena trajno, značka pa je zdaj Open Badge v2.0 BadgeClass, ki ga lahko prenese vsakdo.

Ali sploh ustvarjati značke v kodi?

Običajno ne. Oblikovanje značk je ustvarjalno opravilo, vizualni oblikovalnik (več kot 80 predlog, oblike, ikone, 11 pisav in lastna nalaganja) pa je za to veliko boljše mesto kot skripta. Pogost vzorec je, da vsako značko enkrat oblikujete na nadzorni plošči, vaša integracija pa nato le izdaja podelitve zanjo. Svoje značke lahko izpišete z GET /badges in kopirate id želene.

Značke prek API-ja ustvarjajte, kadar jih generirate programsko, na primer eno na tečaj v katalogu več sto tečajev, ali kadar polnite testno okolje.

4. korak: podelite značko

To je klic, ki ga bo vaša integracija izvedla tisočkrat. Pošljite značko, prejemnika in datum.

curl:

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: $BADGES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"badgeId":"<badge-id>","recipient":{"name":"Jane Smith","email":"jane@example.com"},"issuedOn":"2026-09-28"}'

JavaScript:

const res = await fetch("https://api.badges.ninja/awards", {
  method: "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    badgeId,
    recipient: { name: "Jane Smith", email: "jane@example.com" },
    issuedOn: Date.now(),
  }),
});
const { awardId } = await res.json();

Python:

import time, requests
res = requests.post(
    "https://api.badges.ninja/awards",
    headers={"X-Api-Key": API_KEY},
    json={
        "badgeId": badge_id,
        "recipient": {"name": "Jane Smith", "email": "jane@example.com"},
        "issuedOn": int(time.time() * 1000),
    },
)
award_id = res.json()["awardId"]

Pravila, na katerih se ljudje najpogosteje spotaknejo:

• recipient je gnezdeni objekt s poljema name in email. Ravna polja, kot je recipientEmail, so zavrnjena.
• recipient.name mora imeti vsaj 5 znakov.
• issuedOn je obvezen. Pošljite milisekunde epohe ali datum ISO, na primer 2026-09-28.
• expires je neobvezen in sprejema iste oblike.

Uspeh je HTTP 200 s telesom, ki vsebuje awardId. E-pošta prejemnika je v podatkih Open Badge shranjena kot zgoščena vrednost SHA-256, zato je javni JSON nikoli ne razkrije.

5. korak: poiščite stran za preverjanje in JSON Open Badge

Odgovor o podelitvi vam da identifikator, ne pa že pripravljene povezave. Identifikator se konča z GUID-om, javne strani pa so zgrajene iz tega GUID-a:

• Strani za preverjanje, berljiva za ljudi: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Če vaš awardId pride kot poln naslov URL, kot GUID uporabite zadnji segment poti.

Obe sta javni. Vsakdo s povezavo lahko poverilnico preveri brez ustvarjanja računa, v tem je smisel: delodajalec ali sprejemni uradnik mora biti sposoben značko preveriti v desetih sekundah.

Prenesite JSON in si oglejte, kaj vidi svet:

curl https://api.badges.ninja/certify-badge/award/<awardId>

Dobite trditev Open Badge v2.0: značko, na katero se sklicuje, zgoščeno identiteto prejemnika, datum izdaje in blok preverjanja, ki kaže nazaj na gostovano trditev. Ker gre za standardne podatke Open Badges, jih lahko prebere vsako orodje, ki format razume. Zaradi te prenosljivosti je Open Badges boljša izbira od lastniškega PDF-ja; Open Badges proti potrdilom v PDF-ju kompromis obravnava podrobneje.

Kako prejemniki prejmejo poverilnico

Ustvarjanje podelitve je ločeno od obveščanja prejemnika. Prejemniki lahko svoje poverilnice odprejo prek portala za prejemnike na badges.ninja/me, ki uporablja prijavo z magično povezavo brez gesla, in lahko objavijo javni profil na badges.ninja/u/<handle>. S strani za preverjanje lahko značko dodajo na LinkedIn, prenesejo potrdilo v PDF-ju ali delijo povezavo.

Za prvih nekaj preizkusov pošljite podelitev sebi na svoj e-poštni naslov in preglejte izkušnjo prejemnika. Tako najhitreje opazite stvari, na primer opis značke, ki zveni neroden.

Obravnava napak, ki ne boli

API uporablja običajne statusne kode HTTP. Tiste, ki jih boste srečali:

Dva praktična nasveta. Prvič, 400 obravnavajte kot težavo s podatki in zabeležite telo odgovora, saj imenuje polje, ki je spodletelo. Drugič, svojo integracijo naredite idempotentno na svoji strani: awardId shranite ob zapis o zaključku v svoji zbirki podatkov in ga preverite, preden znova pokličete API. Tako ponovljen webhook ali ponovno zagnano opravilo nikoli ne izda iste osebe dveh poverilnic.

Vse skupaj v pravi integraciji

Tipična povezava izgleda takole:

1. Značke oblikujte na nadzorni plošči, eno na tečaj ali mejnik, in si zapišite ID vsake značke.
2. V svojem sistemu shranite preslikavo iz tečaja v ID značke.
3. Ko učenec zaključi tečaj, vaš strežnik pokliče POST /awards z njegovim imenom, e-pošto in datumom zaključka.
4. Vrnjeni awardId shranite ob zapis o zaključku.
5. Povezavo za preverjanje prikažite znotraj svojega izdelka, da jo učenec vidi, ne da bi ga zapustil.

Če raje ne pišete kode, isti klic deluje iz vsakega orodja za avtomatizacijo, ki zna poslati zahtevek HTTP s telesom JSON in glavo po meri. Usmerite ga na https://api.badges.ninja/awards in polja obrazca ali preglednice preslikajte na badgeId, recipient.name, recipient.email in issuedOn.

Načrti in omejitve, ki jih velja poznati

API je na voljo v vseh načrtih; za odklep ne plačate nič dodatno. Načrt Free ($0) pokriva 2 izdajatelja, 5 značk, 2 sedeža, 1 ključ API in 1,200 poverilnic na leto. Starter stane $9 na mesec, Pro pa $29 na mesec, z višjimi omejitvami. Preden načrtujete uvedbo, na strani s cenami preverite aktualne številke. Če primerjate, koliko drugi ponudniki zaračunajo za dostop do API-ja, alternativa Credlyju stroške prikaže drugega ob drugem.

Kam naprej

• Celoten pregled končnih točk najdete v dokumentaciji API-ja, ki je na voljo v 40 jezikih.
• Za podrobnosti o overjanju in ravnanju s ključi glejte vodnik za overjanje.
• Za podrobnosti o kodah napak glejte referenco napak.
• Ko vam en klic naenkrat ne bo več zadostoval, na nadzorni plošči uporabite množične podelitve: naložite CSV in po potrebi zaustavite ali nadaljujte izvajanje.

Prva uspešna podelitev je najtežja. Potem je ostalo le še vezanje istega klica na mesta, kjer se dosežki že beležijo.

Ste pripravljeni izdati svojo prvo preverljivo poverilnico? Začnite brezplačno na badges.ninja – vizualni oblikovalnik, javna stran za preverjanje, potrdilo v PDF-ju, izhod Open Badge v2.0. Kreditna kartica ni potrebna.