Open Badges kibocsátása a Badges Ninja REST API-n keresztül: gyorsindító

A legtöbb tanúsítványprogramnak nincs szüksége API-ra. Ha évente néhány száz végzőssel futtatsz egy kurzust, az irányítópult mindent megold: a vizuális tervezőben megtervezed a digitális jelvényt, feltöltesz egy CSV-t, és minden címzett kap egy ellenőrzési oldalt és egy PDF-tanúsítványt. Ha ez a te helyzeted, kezdd azzal, hogyan bocsáss ki Open Badges jelvényeket CSV-ből, és térj vissza később.

Az API akkor ér valamit, ha a tanúsítványokat egy másik rendszernek kell kibocsátania: a tanulási platformod befejezettnek jelöl egy kurzust, a regisztrációs eszközöd lezár egy eseményt, a HR-rendszered rögzít egy teljesített megfelelőségi modult. Ilyenkor senki sem akar minden hét végén táblázatot exportálni. Egyetlen HTTP-hívás a teljesítés pillanatában egyszerűbb, a címzett pedig akkor kapja meg a jelvényét, amikor az eredmény még friss.

Ez a gyorsindító négy hívásban járja végig az egész utat: kulcs beszerzése, kibocsátó létrehozása, jelvény létrehozása, odaítélés. Utána megnézzük, hogyan add át az ellenőrző linket a címzettnek, és hogyan ellenőrizd az eredményt. Az alábbi kérések mindegyike az éles kezelőkből származik, ezért bátran bemásolhatod és futtathatod őket.

Mire lesz szükséged az induláshoz

• Egy ingyenes fiók a badges.ninja-n. A Free csomag elég ehhez az útmutatóhoz: 2 kibocsátót, 5 jelvényt, 2 felhasználói helyet és 1 API-kulcsot tartalmaz.
• Egy API-kulcs, amelyet az irányítópultról hozol létre.
• Egy PNG vagy JPG a jelvény képéhez, vagy egy, a vizuális tervezőben megtervezett jelvény.

Minden kérés alap URL-je https://api.badges.ninja.

1. lépés: API-kulcs létrehozása

Jelentkezz be, nyisd meg az oldalsávban az API Keys menüpontot, és kattints a Create API Key gombra. Adj neki olyan nevet, amely elárulja, hol fog élni, például „LMS integration”, hogy később, a kulcsok cseréjekor meg tudd különböztetni őket.

A kulcs pontosan egyszer látható. Másold azonnal a titokkezelődbe vagy egy környezeti változóba. A kulcsok bws_ előtaggal kezdődnek, utána 32 hexadecimális karakter áll, és minden kérésnél az X-Api-Key fejlécben küldöd őket. A kulcs visszavonása ugyanazon a képernyőn azonnal érvénybe lép.

Néhány szokás, amely később megkíméli a bosszúságtól:

• Soha ne tedd a kulcsot front-end kódba vagy nyilvános tárolóba. Az API-t szerverről, szerver nélküli függvényből vagy automatizálási eszközből hívd.
• Integrációnként egy kulcsot használj. Ha az egyik kiszivárog, egyetlen integrációt vonsz vissza, nem az összeset.
• Az irányítópult elfogadja a bejelentkezett munkamenetedet is (egy Authorization: Bearer fejlécben küldött Cognito JWT), de szkriptekhez és integrációkhoz az API-kulcs a megfelelő eszköz.

Az alábbi példák mind a BADGES_API_KEY nevű környezeti változóból olvassák a kulcsot.

2. lépés: Kibocsátó létrehozása

A kibocsátó az a szervezet, amely a jelvény mögött áll. Minden ellenőrzési oldalon és az Open Badge v2.0 adatokban is megjelenik, ezért azt a nevet használd, amelyet az emberek valóban ismernek.

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

A kötelező mezők: name (legalább 3 karakter), url (érvényes http vagy https cím) és email. Választható mező a logo (base64-kódolt kép) és a linkedinOrganizationId, amely bekapcsolja az Add to LinkedIn Profile gombot a nyilvános tanúsítványoldalaidon.

A válasz tartalmazza a kibocsátó azonosítóját:

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

Tartsd meg ezt az értéket pontosan úgy, ahogy visszajött. Ez a következő lépés bemenete.

A kibocsátó ellenőrzése

Jelvényt csak ellenőrzött kibocsátó alatt lehet létrehozni. Az ellenőrzés így működik:

• Ha a kibocsátó e-mail-címe megegyezik a fiókod e-mail-címével, a kibocsátó automatikusan ellenőrzötté válik. Ez a leggyorsabb út az első teszthez.
• Ha az e-mail-cím eltér, a címre ellenőrző e-mail érkezik egy kóddal. A kódot az irányítópulton (vagy a kibocsátók API-ján keresztül) erősíted meg, mielőtt jelvényeket hozol létre.

Ehhez az útmutatóhoz tehát használd ugyanazt az e-mail-címet, amellyel regisztráltál.

3. lépés: Jelvény létrehozása

A jelvény az újrahasznosítható sablon: név, leírás, feltételek és kép. Minden később kiadott odaítélés erre mutat vissza.

A kérés sima JSON. A képet base64-sztringként kell megadni, így nincs szükség multipart feltöltésre. Az olyan data URL előtag, mint a data:image/png;base64,, elfogadott, és eltávolításra kerül.

JavaScript (Node 18 vagy újabb):

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)

Mind az öt mező (name, description, criteria, image, issuerId) kötelező. Két választható mezőt érdemes ismerni: a shareText az alapértelmezett szöveg, amelyet a címzettek a közösségi hálókon való megosztáskor látnak (támogatja a {{badge_name}}, {{issuer_name}} és {{award_url}} helyőrzőket), a designJson pedig egy vizuálistervező-dokumentumot tárol, így a jelvény később rétegenként szerkeszthető.

Siker esetén a válasz HTTP 200 és { "badgeId": "<id>" }. A kép véglegesen tárolódik, a jelvény pedig innentől egy Open Badge v2.0 BadgeClass, amelyet bárki lekérhet.

Érdemes egyáltalán kódból jelvényt létrehozni?

Általában nem. A jelvénytervezés kreatív feladat, és a vizuális tervező (80+ sablon, formák, ikonok, 11 betűtípus és egyéni feltöltések) sokkal jobb hely erre, mint egy szkript. Gyakori minta, hogy minden jelvényt egyszer megtervezel az irányítópulton, az integrációd pedig csak odaítéléseket bocsát ki hozzá. A jelvényeidet a GET /badges hívással listázhatod, és kimásolhatod a kívánt jelvény id-ját.

Az API-n keresztül akkor hozz létre jelvényeket, ha programozottan generálod őket, például száz meg száz kurzusból álló katalógus minden kurzusához egyet, vagy ha tesztkörnyezetet töltesz fel.

4. lépés: A jelvény odaítélése

Ezt a hívást fogja az integrációd ezerszer meghívni. Add meg a jelvényt, a címzettet és a dátumot.

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"]

A szabályok, amelyeken a legtöbben elakadnak:

• A recipient egy beágyazott objektum name és email mezőkkel. Az olyan lapos mezőket, mint a recipientEmail, elutasítja a rendszer.
• A recipient.name legalább 5 karakter legyen.
• Az issuedOn kötelező. Küldj epoch-ezredmásodpercet vagy ISO dátumsztringet, például 2026-09-28.
• Az expires választható, és ugyanezeket a formátumokat fogadja.

Siker esetén HTTP 200 érkezik, a törzs pedig tartalmazza az awardId értéket. A címzett e-mail-címe SHA-256 hash-ként tárolódik az Open Badge adatokban, így a nyilvános JSON soha nem fedi fel.

5. lépés: Az ellenőrzési oldal és az Open Badge JSON megkeresése

Az odaítélés válasza azonosítót ad, nem kész linket. Az azonosító GUID-dal végződik, és a nyilvános oldalak ebből a GUID-ból épülnek fel:

• Ember által olvasható ellenőrzési oldal: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Ha az awardId teljes URL-ként érkezik, az utolsó útvonalszegmenst használd GUID-ként.

Mindkettő nyilvános. A link birtokában bárki ellenőrizheti a tanúsítványt fiók létrehozása nélkül, és éppen ez a lényeg: egy munkáltatónak vagy felvételi felelősnek tíz másodperc alatt le kell tudnia ellenőrizni egy jelvényt.

Kérd le a JSON-t, hogy lásd, mit lát a világ:

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

Egy Open Badge v2.0 Assertiont kapsz: a hivatkozott jelvényt, a címzett hash-elt azonosítóját, a kibocsátás dátumát és egy ellenőrzési blokkot, amely a tárolt assertionre mutat vissza. Mivel szabványos Open Badges adatról van szó, minden, a formátumot ismerő eszköz képes beolvasni. Ez a hordozhatóság az oka, hogy Open Badges jelvényt érdemes választani egy zárt PDF helyett; az Open Badges vs PDF certificates cikk részletesebben tárgyalja a kompromisszumot.

Hogyan kapják meg a címzettek a tanúsítványt

Az odaítélés létrehozása külön dolog attól, hogy értesítjük a címzettet. A címzettek a badges.ninja/me címzettportálon keresztül nyithatják meg a tanúsítványaikat, amely jelszó nélküli, magic linkes bejelentkezést használ, és nyilvános profilt is közzétehetnek a badges.ninja/u/<handle> címen. Az ellenőrzési oldalról hozzáadhatják a jelvényt a LinkedInhez, letölthetik a PDF-tanúsítványt, vagy megoszthatják a linket.

Az első tesztekhez ítélj oda egyet a saját e-mail-címedre, és járd végig a címzett élményét. Ez a leggyorsabb módja annak, hogy észrevedd például a nehézkesen hangzó jelvényleírást.

Hibakezelés fájdalom nélkül

Az API hétköznapi HTTP-állapotkódokat használ. Ezekkel fogsz találkozni:

Két gyakorlati tanács. Először: a 400-at kezeld adatproblémaként, és naplózd a válasz törzsét, mert megnevezi a hibás mezőt. Másodszor: tedd az integrációdat idempotenssé a saját oldaladon: a saját adatbázisodban tárold az awardId-t a teljesítési rekord mellett, és mielőtt újra hívnád az API-t, ellenőrizd. Így egy újrapróbált webhook vagy újrafuttatott feladat sosem bocsát ki ugyanannak a személynek két tanúsítványt.

Összeállítás valódi integrációvá

Egy tipikus bekötés így néz ki:

1. Megtervezed a jelvényeket az irányítópulton, kurzusonként vagy mérföldkőnként egyet, és feljegyzed az egyes jelvények azonosítóját.
2. A rendszeredben tárolsz egy leképezést a kurzus és a jelvényazonosító között.
3. Amikor egy tanuló befejez egy kurzust, a szervered meghívja a POST /awards végpontot a nevével, e-mail-címével és a teljesítés dátumával.
4. A visszaadott awardId-t elmented a teljesítési rekordhoz.
5. Az ellenőrző linket a saját termékedben jeleníted meg, hogy a tanuló anélkül lássa, hogy elhagyná azt.

Ha inkább nem írnál kódot, ugyanez a hívás működik bármely automatizálási eszközből, amely képes JSON-törzsű, egyéni fejléces HTTP-kérést küldeni. Irányítsd a https://api.badges.ninja/awards címre, és képezd le az űrlap vagy a táblázat mezőit a badgeId, recipient.name, recipient.email és issuedOn mezőkre.

Csomagok és korlátok, amelyeket érdemes ismerni

Az API minden csomagban elérhető; a feloldásáért nem fizetsz felárat. A Free csomag ($0) 2 kibocsátót, 5 jelvényt, 2 felhasználói helyet, 1 API-kulcsot és évi 1,200 tanúsítványt fed le. A Starter $9 havonta, a Pro $29 havonta, magasabb korlátokkal. Mielőtt méreteznéd a bevezetést, nézd meg az aktuális számokat az árazási oldalon. Ha azt hasonlítod össze, mennyit kérnek más platformok az API-hozzáférésért, a Credly alternative egymás mellé teszi a költségeket.

Merre tovább

• A teljes végpont-referencia az API-dokumentációban található, amely 40 nyelven elérhető.
• A hitelesítés és a kulcskezelés részleteiért lásd a hitelesítési útmutatót.
• A hibakódok részletes ismertetéséért lásd a hibák referenciáját.
• Ha kinőtted az egyesével küldött hívásokat, használd az irányítópult tömeges odaítélését: tölts fel egy CSV-t, és szükség esetén szüneteltetheted vagy folytathatod a futást.

Az első sikeres odaítélés a nehezebb rész. Utána már csak azt kell bekötni ugyanezt a hívást oda, ahol az eredmények amúgy is rögzítésre kerülnek.

Készen állsz az első ellenőrizhető tanúsítványod kibocsátására? Kezdd ingyen a badges.ninja-n — vizuális tervező, nyilvános ellenőrzési oldal, PDF-tanúsítvány, Open Badge v2.0 kimenet. Bankkártya nélkül.