Open Badges išdavimas per Badges Ninja REST API: greitas pradžios vadovas

Dauguma kvalifikacijų programų API visai nereikia. Jei vedate kursą, kurį per metus baigia keli šimtai dalyvių, valdymo skydelio pakanka viskam: skaitmeninį ženklelį sukuriate vizualiame dizaineryje, įkeliate CSV, o kiekvienas gavėjas gauna patikrinimo puslapį ir PDF sertifikatą. Jei tai jūsų atvejis, pradėkite nuo kaip išduoti Open Badges iš CSV failo ir grįžkite vėliau.

API pravartus tada, kai kvalifikacijas turi išduoti kita sistema: jūsų mokymosi platforma pažymi kursą kaip baigtą, registracijos įrankis uždaro renginį, personalo sistema užfiksuoja baigtą atitikties modulį. Tokiais atvejais niekas nenori kiekvienos savaitės pabaigoje eksportuoti skaičiuoklės. Vienas HTTP kvietimas pasiekimo akimirką yra paprastesnis, o gavėjas ženklelį gauna, kol pasiekimas dar šviežias.

Šiame vadove visą kelią įveiksime keturiais kvietimais: gausime raktą, sukursime išdavėją, sukursime ženklelį ir jį įteiksime. Tada pažiūrėsime, kaip gavėjui perduoti patikrinimo nuorodą ir patikrinti rezultatą. Kiekviena žemiau pateikta užklausos forma paimta iš veikiančių tvarkyklių, tad galite ją tiesiog nukopijuoti ir paleisti.

Ko jums reikės prieš pradedant

• Nemokamos paskyros badges.ninja. Šiam vadovui pakanka Free plano: jame yra 2 išdavėjai, 5 ženkleliai, 2 vietos ir 1 API raktas.
• Vieno API rakto, sukurto valdymo skydelyje.
• PNG arba JPG paveikslėlio ženklelio vaizdui arba ženklelio, kurį sukūrėte vizualiame dizaineryje.

Visų užklausų bazinis URL yra https://api.badges.ninja.

1 žingsnis: sukurkite API raktą

Prisijunkite, šoninėje juostoje atidarykite API Keys ir spustelėkite Create API Key. Pavadinkite jį taip, kad aiškiai matytųsi, kur jis bus naudojamas, pavyzdžiui, „LMS integracija“, kad vėliau, keisdami raktus, galėtumėte juos atskirti.

Raktas rodomas tik vieną kartą. Nedelsdami nukopijuokite jį į savo paslapčių tvarkyklę arba aplinkos kintamąjį. Raktai atrodo kaip bws_, po kurio eina 32 šešioliktainiai simboliai, ir kiekvienoje užklausoje siunčiami X-Api-Key antraštėje. Raktą atšaukus tame pačiame ekrane, atšaukimas įsigalioja iš karto.

Kelios įpročiai, kurie vėliau sutaupo vargo:

• Niekada nedėkite rakto į priekinės dalies kodą ar viešą saugyklą. API kvieskite iš serverio, bevaldžio (serverless) funkcijos ar automatizavimo įrankio.
• Kiekvienai integracijai naudokite atskirą raktą. Jei vienas nutekės, atšauksite vieną integraciją, o ne visas.
• Valdymo skydelis taip pat priima jūsų prisijungimo sesiją (Cognito JWT, siunčiamą kaip Authorization: Bearer), tačiau skriptams ir integracijoms tinkamas įrankis yra API raktas.

Visuose žemiau pateiktuose pavyzdžiuose raktas skaitomas iš aplinkos kintamojo BADGES_API_KEY.

2 žingsnis: sukurkite išdavėją

Išdavėjas yra organizacija, kuri laiduoja už ženklelį. Jis rodomas kiekviename patikrinimo puslapyje ir Open Badge v2.0 duomenyse, todėl naudokite pavadinimą, kurį žmonės iš tikrųjų pažįsta.

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

Privalomi laukai yra name (bent 3 simboliai), url (galiojantis http arba https adresas) ir email. Neprivalomi laukai: logo (base64 koduotas paveikslėlis) ir linkedinOrganizationId, kuris jūsų viešuose kvalifikacijų puslapiuose įjungia mygtuką „Add to LinkedIn Profile“.

Atsakyme pateikiamas išdavėjo identifikatorius:

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

Išsaugokite šią reikšmę tiksliai tokią, kokią gavote. Ji reikalinga kitam žingsniui.

Išdavėjo patikrinimas

Ženklelius galima kurti tik pagal patikrintą išdavėją. Patikrinimas vyksta taip:

• Jei išdavėjo el. paštas sutampa su jūsų paskyros el. paštu, išdavėjas patikrinamas automatiškai. Tai greičiausias kelias pirmam bandymui.
• Jei el. paštas kitoks, į tą adresą išsiunčiamas patikrinimo laiškas su kodu. Kodą patvirtinate valdymo skydelyje (arba per išdavėjų API) prieš kurdami ženklelius.

Todėl šiame vadove naudokite tą patį el. paštą, su kuriuo registravotės.

3 žingsnis: sukurkite ženklelį

Ženklelis yra daugkartinio naudojimo šablonas: pavadinimas, aprašymas, kriterijai ir vaizdas. Kiekvienas vėliau išduotas įteikimas nurodo į jį.

Užklausa yra paprastas JSON. Vaizdas siunčiamas kaip base64 eilutė, tad nereikia painiotis su multipart įkėlimu. Duomenų URL priešdėlis, pavyzdžiui, data:image/png;base64,, priimamas ir pašalinamas.

JavaScript (Node 18 ar naujesnė):

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)

Visi penki laukai (name, description, criteria, image, issuerId) yra privalomi. Verta žinoti dar du neprivalomus: shareText – numatytąjį tekstą, kurį gavėjai mato dalindamiesi socialiniuose tinkluose (palaiko vietoženklius {{badge_name}}, {{issuer_name}} ir {{award_url}}), ir designJson, kuriame saugomas vizualaus dizainerio dokumentas, kad ženklelį vėliau būtų galima redaguoti sluoksnis po sluoksnio.

Sėkmės atveju grąžinamas HTTP 200 su { "badgeId": "<id>" }. Vaizdas saugomas visam laikui, o ženklelis dabar yra Open Badge v2.0 BadgeClass, kurį gali gauti bet kas.

Ar apskritai verta kurti ženklelius kode?

Dažniausiai ne. Ženklelio dizainas yra kūrybinė užduotis, o vizualus dizaineris (80+ šablonų, formų, piktogramų, 11 šriftų ir savi įkėlimai) tam tinka kur kas geriau nei skriptas. Įprastas modelis: kiekvieną ženklelį vieną kartą sukurti valdymo skydelyje, o integracija tik išduoda įteikimus pagal jį. Savo ženklelių sąrašą galite gauti per GET /badges ir nukopijuoti norimo id.

Ženklelius per API kurkite tada, kai juos generuojate programiškai, pavyzdžiui, po vieną kiekvienam šimtų kursų kataloge, arba kai užpildote testavimo aplinką.

4 žingsnis: įteikite ženklelį

Tai kvietimas, kurį jūsų integracija darys tūkstančius kartų. Nusiųskite ženklelį, gavėją ir datą.

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

Taisyklės, ant kurių žmonės dažniausiai suklumpa:

• recipient yra įdėtasis objektas su name ir email. Plokšti laukai, tokie kaip recipientEmail, atmetami.
• recipient.name turi būti bent 5 simbolių.
• issuedOn yra privalomas. Siųskite epochos milisekundes arba ISO datos eilutę, pavyzdžiui, 2026-09-28.
• expires neprivalomas ir priima tuos pačius formatus.

Sėkmės atveju grąžinamas HTTP 200 su turiniu, kuriame yra awardId. Gavėjo el. paštas Open Badge duomenyse saugomas kaip SHA-256 maiša, todėl viešasis JSON jo niekada neatskleidžia.

5 žingsnis: raskite patikrinimo puslapį ir Open Badge JSON

Įteikimo atsakyme gaunate identifikatorių, o ne paruoštą nuorodą. Identifikatorius baigiasi GUID, o viešieji puslapiai sudaromi iš to GUID:

• Žmogui skirtas patikrinimo puslapis: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Jei jūsų awardId grįžta kaip pilnas URL, kaip GUID naudokite paskutinį kelio segmentą.

Abu yra vieši. Bet kas, turintis nuorodą, gali patikrinti kvalifikaciją nesikurdamas paskyros, ir tai yra esmė: darbdavys ar priėmimo komisijos narys turi galėti patikrinti ženklelį per dešimt sekundžių.

Gaukite JSON ir pamatysite, ką mato pasaulis:

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

Gausite Open Badge v2.0 Assertion: ženklelį, į kurį jis nurodo, užmaišytą gavėjo tapatybę, išdavimo datą ir patikrinimo bloką, nurodantį atgal į talpinamą tvirtinimą. Kadangi tai standartiniai Open Badges duomenys, juos gali perskaityti bet kuris formatą suprantantis įrankis. Dėl šio perkeliamumo Open Badges verta rinktis vietoj nuosavybinio PDF; Open Badges ir PDF sertifikatai šį kompromisą nagrinėja išsamiau.

Kaip gavėjai gauna kvalifikaciją

Įteikimo sukūrimas yra atskiras dalykas nuo gavėjo informavimo apie jį. Gavėjai savo kvalifikacijas gali atidaryti gavėjų portale badges.ninja/me, kuriame prisijungiama magiška nuoroda be slaptažodžio, ir gali paskelbti viešą profilį adresu badges.ninja/u/<handle>. Iš patikrinimo puslapio jie gali pridėti ženklelį prie LinkedIn, atsisiųsti PDF sertifikatą arba pasidalyti nuoroda.

Per pirmuosius kelis bandymus nusiųskite įteikimą sau, naudodami savo el. pašto adresą, ir išbandykite gavėjo patirtį. Tai greičiausias būdas pastebėti tokius dalykus kaip nepatogiai skambantis ženklelio aprašymas.

Klaidų apdorojimas, kuris nekenkia

API naudoja įprastus HTTP būsenos kodus. Su šiais susidursite:

Du praktiniai patarimai. Pirma, 400 traktuokite kaip duomenų problemą ir registruokite atsakymo turinį, nes jame įvardijamas klaidingas laukas. Antra, užtikrinkite idempotentiškumą savo pusėje: išsaugokite awardId šalia užbaigimo įrašo savo duomenų bazėje ir patikrinkite jį prieš vėl kviesdami API. Taip pakartotas webhook ar iš naujo paleista užduotis niekada neišduos to paties žmogaus dviejų kvalifikacijų.

Viskas kartu tikroje integracijoje

Tipinė schema atrodo taip:

1. Sukurkite ženklelius valdymo skydelyje, po vieną kiekvienam kursui ar etapui, ir užsirašykite kiekvieno ženklelio ID.
2. Savo sistemoje išsaugokite kurso ir ženklelio ID atitikmenį.
3. Kai besimokantysis baigia kursą, jūsų serveris iškviečia POST /awards su jo vardu, el. paštu ir baigimo data.
4. Grąžintą awardId išsaugokite prie užbaigimo įrašo.
5. Rodykite patikrinimo nuorodą savo produkte, kad besimokantysis ją matytų iš jo neišėjęs.

Jei nenorite rašyti kodo, tą patį kvietimą gali atlikti bet kuris automatizavimo įrankis, galintis siųsti HTTP užklausą su JSON turiniu ir pasirinktine antraštė. Nukreipkite jį į https://api.badges.ninja/awards ir susiekite savo formos ar skaičiuoklės laukus su badgeId, recipient.name, recipient.email ir issuedOn.

Planai ir apribojimai, kuriuos verta žinoti

API prieinamas visuose planuose; už jo atrakinimą papildomai nemokate. Free planas ($0) apima 2 išdavėjus, 5 ženklelius, 2 vietas, 1 API raktą ir 1,200 kvalifikacijų per metus. Starter kainuoja $9 per mėnesį, o Pro – $29 per mėnesį, su didesniais limitais. Prieš planuodami diegimo mastą, patikrinkite kainų puslapį dėl aktualių skaičių. Jei lyginate, kiek kitos platformos ima už API prieigą, Credly alternatyva kainas išdėsto greta.

Kur eiti toliau

• Visas galinių taškų aprašas yra API dokumentacijoje, kuri prieinama 40 kalbų.
• Autentifikavimo detalių ir raktų tvarkymo ieškokite autentifikavimo vadove.
• Išsamų klaidų kodų aprašą rasite klaidų žinyne.
• Kai vieno kvietimo vienu metu nebepakaks, naudokite masinį įteikimą valdymo skydelyje: įkelkite CSV ir, jei reikia, pristabdykite ar tęskite vykdymą.

Sunkiausia yra pirmasis sėkmingas įteikimas. Toliau belieka tą patį kvietimą įtaisyti ten, kur pasiekimai ir taip užfiksuojami.

Pasiruošę išduoti savo pirmąją patikrinamą kvalifikaciją? Pradėkite nemokamai badges.ninja — vizualus dizaineris, viešas patikrinimo puslapis, PDF sertifikatas, Open Badge v2.0 išvestis. Kreditinė kortelė nereikalinga.