Open Badges -merkkien myöntäminen Badges Ninjan REST API:n kautta: pikaopas

Useimmat todistusohjelmat eivät tarvitse rajapintaa lainkaan. Jos vedät kurssia, jolta valmistuu muutama sata ihmistä vuodessa, hallintapaneeli hoitaa kaiken: suunnittelet merkin visuaalisella suunnittelutyökalulla, lataat CSV-tiedoston, ja jokainen saaja saa varmennussivun ja PDF-todistuksen. Jos tämä on sinun tilanteesi, aloita oppaasta Open Badges -merkkien myöntäminen CSV-tiedostosta ja palaa tähän myöhemmin.

Rajapinta ansaitsee paikkansa, kun todistukset pitää myöntää toisesta järjestelmästä: oppimisalustasi merkitsee kurssin suoritetuksi, ilmoittautumistyökalusi sulkee tapahtuman tai HR-järjestelmäsi kirjaa suoritetun compliance-moduulin. Silloin kukaan ei halua viedä taulukkoa ulos joka viikon päätteeksi. Yksi HTTP-kutsu suorituksen hetkellä on yksinkertaisempi, ja saaja saa merkkinsä, kun saavutus on vielä tuore.

Tämä pikaopas käy koko polun läpi neljällä kutsulla: hanki avain, luo myöntäjä, luo merkki ja myönnä se. Sen jälkeen katsomme, miten varmennuslinkki annetaan saajalle ja miten tuloksen voi tarkistaa. Jokainen alla oleva pyyntömuoto on peräisin käyttöön otetuista käsittelijöistä, joten voit liittää ne sellaisenaan ja ajaa.

Mitä tarvitset ennen aloitusta

• Ilmainen tili osoitteessa badges.ninja. Free-paketti riittää tähän oppaaseen: siihen kuuluu 2 myöntäjää, 5 merkkiä, 2 käyttäjäpaikkaa ja 1 API-avain.
• Yksi API-avain, luotuna hallintapaneelista.
• PNG- tai JPG-kuva merkin kuvaksi tai visuaalisella suunnittelutyökalulla suunnittelemasi merkki.

Kaiken perus-URL on https://api.badges.ninja.

Vaihe 1: Luo API-avain

Kirjaudu sisään, avaa sivupalkista API Keys ja napsauta Create API Key. Anna avaimelle nimi, joka kertoo, missä sitä käytetään, esimerkiksi “LMS integration”, jotta erotat avaimet toisistaan, kun kierrätät niitä myöhemmin.

Avain näytetään täsmälleen kerran. Kopioi se heti salaisuuksien hallintaan tai ympäristömuuttujaan. Avaimet näyttävät tältä: bws_ ja sen perässä 32 heksamerkkiä, ja ne lähetetään X-Api-Key-otsakkeessa jokaisen pyynnön mukana. Avaimen mitätöinti samasta näkymästä tulee voimaan välittömästi.

Muutama tapa, jotka säästävät vaivaa myöhemmin:

• Älä koskaan laita avainta frontend-koodiin tai julkiseen repositorioon. Kutsu rajapintaa palvelimelta, serverless-funktiosta tai automaatiotyökalusta.
• Käytä yhtä avainta yhtä integraatiota kohti. Jos yksi vuotaa, mitätöit yhden integraation etkä kaikkia.
• Hallintapaneeli hyväksyy myös kirjautuneen istuntosi (Cognito JWT, joka lähetetään muodossa Authorization: Bearer), mutta skripteihin ja integraatioihin oikea työkalu on API-avain.

Kaikki alla olevat esimerkit lukevat avaimen ympäristömuuttujasta nimeltä BADGES_API_KEY.

Vaihe 2: Luo myöntäjä

Myöntäjä on organisaatio, joka seisoo merkin takana. Se näkyy jokaisella varmennussivulla ja Open Badge v2.0 -datassa, joten käytä nimeä, jonka ihmiset oikeasti tuntevat.

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

Pakolliset kentät ovat name (vähintään 3 merkkiä), url (kelvollinen http- tai https-osoite) ja email. Valinnaisia kenttiä ovat logo (base64-koodattu kuva) ja linkedinOrganizationId, joka ottaa käyttöön Add to LinkedIn Profile -painikkeen julkisilla todistussivuillasi.

Vastaus sisältää myöntäjän tunnisteen:

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

Säilytä arvo täsmälleen sellaisena kuin se palautettiin. Se on seuraavan vaiheen syöte.

Myöntäjän varmennus

Merkkejä voi luoda vain varmennetun myöntäjän alle. Varmennus toimii näin:

• Jos myöntäjän sähköposti vastaa tilisi sähköpostia, myöntäjä varmennetaan automaattisesti. Tämä on nopein tapa ensimmäiseen testiin.
• Jos sähköposti on eri, osoitteeseen lähetetään varmennusviesti ja koodi. Vahvistat koodin hallintapaneelissa (tai myöntäjärajapinnan kautta) ennen merkkien luomista.

Käytä siis tässä oppaassa samaa sähköpostia, jolla rekisteröidyit.

Vaihe 3: Luo merkki

Merkki on uudelleenkäytettävä pohja: nimi, kuvaus, kriteerit ja kuva. Jokainen myöhemmin myöntämäsi myöntö viittaa siihen.

Pyyntö on pelkkää JSONia. Kuva annetaan base64-merkkijonona, joten multipart-latauksen kanssa ei tarvitse painia. Data URL -etuliite, kuten data:image/png;base64,, hyväksytään ja poistetaan.

JavaScript (Node 18 tai uudempi):

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)

Kaikki viisi kenttää (name, description, criteria, image, issuerId) ovat pakollisia. Kaksi valinnaista kannattaa tuntea: shareText, oletusteksti, jonka saajat näkevät jakaessaan sosiaalisessa mediassa (tukee paikkamerkkejä {{badge_name}}, {{issuer_name}} ja {{award_url}}), sekä designJson, joka tallentaa visuaalisen suunnittelutyökalun dokumentin, jotta merkkiä voi myöhemmin muokata kerros kerrokselta.

Onnistunut kutsu palauttaa HTTP 200 ja { "badgeId": "<id>" }. Kuva tallennetaan pysyvästi, ja merkki on nyt Open Badge v2.0 -BadgeClass, jonka kuka tahansa voi hakea.

Pitäisikö merkkejä luoda koodilla lainkaan?

Yleensä ei. Merkin suunnittelu on luova tehtävä, ja visuaalinen suunnittelutyökalu (yli 80 pohjaa, muodot, kuvakkeet, 11 fonttia ja omat lataukset) on siihen paljon parempi paikka kuin skripti. Yleinen malli on suunnitella jokainen merkki kerran hallintapaneelissa ja antaa integraation vain myöntää niitä. Voit listata merkkisi komennolla GET /badges ja kopioida haluamasi merkin id:n.

Luo merkkejä rajapinnan kautta, kun tuotat niitä ohjelmallisesti, esimerkiksi yhden jokaista kurssia kohti sadoista kursseista koostuvassa katalogissa, tai kun täytät testiympäristöä.

Vaihe 4: Myönnä merkki

Tämän kutsun integraatiosi tekee tuhansia kertoja. Lähetä merkki, saaja ja päivämäärä.

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

Säännöt, joihin ihmiset yleensä kompastuvat:

• recipient on sisäkkäinen objekti, jossa on name ja email. Litteät kentät, kuten recipientEmail, hylätään.
• recipient.name on oltava vähintään 5 merkkiä.
• issuedOn on pakollinen. Lähetä epoch-millisekunteja tai ISO-päivämäärä, kuten 2026-09-28.
• expires on valinnainen ja hyväksyy samat muodot.

Onnistunut kutsu palauttaa HTTP 200 ja vastauksen, joka sisältää awardId:n. Saajan sähköposti tallennetaan SHA-256-tiivisteenä Open Badge -dataan, joten julkinen JSON ei koskaan paljasta sitä.

Vaihe 5: Etsi varmennussivu ja Open Badge -JSON

Myöntövastaus antaa tunnisteen, ei valmista linkkiä. Tunniste päättyy GUID-arvoon, ja julkiset sivut rakennetaan tuosta GUID:stä:

• Ihmisen luettava varmennussivu: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Jos awardId palautuu täytenä URL-osoitteena, käytä GUID:nä polun viimeistä osaa.

Molemmat ovat julkisia. Kuka tahansa, jolla on linkki, voi varmentaa todistuksen luomatta tiliä, ja juuri se on tarkoitus: työnantajan tai opiskelijavalinnasta vastaavan pitää pystyä tarkistamaan merkki kymmenessä sekunnissa.

Hae JSON nähdäksesi, mitä maailma näkee:

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

Saat Open Badge v2.0 -Assertionin: merkin, johon se viittaa, tiivistetyn saajan identiteetin, myöntöpäivän ja varmennuslohkon, joka osoittaa takaisin isännöityyn assertioniin. Koska kyse on tavallisesta Open Badges -datasta, kaikki formaattia ymmärtävät työkalut osaavat lukea sen. Tämä siirrettävyys on syy valita Open Badges suljetun PDF:n sijaan; Open Badges vs PDF certificates käy vaihtokauppaa läpi tarkemmin.

Miten saajat saavat todistuksen

Myönnön luominen on eri asia kuin saajalle kertominen siitä. Saajat voivat avata todistuksensa saajaportaalissa osoitteessa badges.ninja/me, joka käyttää salasanatonta magic link -kirjautumista, ja he voivat julkaista julkisen profiilin osoitteessa badges.ninja/u/<handle>. Varmennussivulta he voivat lisätä merkin LinkedIniin, ladata PDF-todistuksen tai jakaa linkin.

Lähetä ensimmäisissä testeissä myöntö itsellesi omalla sähköpostiosoitteellasi ja käy läpi saajan kokemus. Se on nopein tapa huomata esimerkiksi kömpelösti kuulostava merkin kuvaus.

Virheenkäsittely, joka ei sattuisi

Rajapinta käyttää tavallisia HTTP-tilakoodeja. Näitä kohtaat:

Kaksi käytännön vinkkiä. Ensiksi: käsittele 400 dataongelmana ja kirjaa vastauksen runko lokiin, sillä se nimeää virheellisen kentän. Toiseksi: tee integraatiostasi idempotentti omalla puolellasi. Tallenna awardId suorituskirjauksen viereen omaan tietokantaasi ja tarkista se ennen kuin kutsut rajapintaa uudelleen. Näin uudelleen lähetetty webhook tai uudelleen ajettu työ ei koskaan myönnä samalle henkilölle kahta todistusta.

Kokonaisuuden kokoaminen oikeaksi integraatioksi

Tyypillinen kytkentä näyttää tältä:

1. Suunnittele merkit hallintapaneelissa, yksi kutakin kurssia tai virstanpylvästä kohti, ja kirjaa jokaisen merkin ID ylös.
2. Tallenna järjestelmääsi kuvaus kurssista merkin ID:hen.
3. Kun oppija suorittaa kurssin, palvelimesi kutsuu POST /awards oppijan nimellä, sähköpostilla ja suorituspäivällä.
4. Tallenna palautettu awardId suorituskirjauksen yhteyteen.
5. Näytä varmennuslinkki omassa tuotteessasi, jotta oppija näkee sen poistumatta sieltä.

Jos haluat välttää koodin kirjoittamisen, sama kutsu toimii mistä tahansa automaatiotyökalusta, joka osaa lähettää HTTP-pyynnön JSON-rungolla ja mukautetulla otsakkeella. Osoita se osoitteeseen https://api.badges.ninja/awards ja yhdistä lomakkeesi tai taulukkosi kentät kenttiin badgeId, recipient.name, recipient.email ja issuedOn.

Paketit ja rajat, jotka kannattaa tuntea

Rajapinta on käytettävissä kaikissa paketeissa; sen käyttöönotosta ei makseta erikseen. Free-paketti ($0) kattaa 2 myöntäjää, 5 merkkiä, 2 käyttäjäpaikkaa, 1 API-avaimen ja 1 200 todistusta vuodessa. Starter maksaa $9 kuukaudessa ja Pro $29 kuukaudessa, ja niissä rajat ovat korkeammat. Tarkista ajantasaiset luvut hinnoittelusivulta ennen kuin mitoitat käyttöönoton. Jos vertailet, mitä muut alustat veloittavat API-käytöstä, Credly alternative asettaa kustannukset rinnakkain.

Mihin siirtyä seuraavaksi

• Täydellinen päätepisteiden viite löytyy API-dokumentaatiosta, joka on saatavilla 40 kielellä.
• Tunnistautumisesta ja avainten käsittelystä kerrotaan tunnistautumisoppaassa.
• Virhekoodeista tarkemmin virheviitteessä.
• Kun yksi kutsu kerrallaan ei enää riitä, käytä hallintapaneelin massamyöntöä: lataa CSV ja keskeytä tai jatka ajoa tarvittaessa.

Ensimmäinen onnistunut myöntö on vaikein. Sen jälkeen jäljellä on vain saman kutsun kytkeminen niihin paikkoihin, joissa saavutukset jo kirjataan.

Valmiina myöntämään ensimmäisen varmennettavan todistuksesi? Aloita ilmaiseksi badges.ninjassa — visuaalinen suunnittelutyökalu, julkinen varmennussivu, PDF-todistus, Open Badge v2.0 -tuloste. Luottokorttia ei tarvita.