Open Badges'i väljastamine Badges Ninja REST API kaudu: kiirjuhend

Enamik tunnistusprogramme ei vaja API-t kunagi. Kui juhid kursust, millel on aastas paarsada lõpetajat, teeb armatuurlaud kõik ära: kujundad märgi visuaalses kujundajas, laed üles CSV-faili ja iga saaja saab kinnituslehe ning PDF-sertifikaadi. Kui see on sinu olukord, alusta artiklist kuidas väljastada Open Badges’i CSV-failist ja tule hiljem tagasi.

API tasub end ära siis, kui tunnistusi peab väljastama mõni teine süsteem: sinu õpiplatvorm märgib kursuse lõpetatuks, sinu registreerimisvahend sulgeb ürituse, sinu personalisüsteem fikseerib lõpetatud vastavusmooduli. Neil juhtudel ei taha keegi iga nädala lõpus tabelit eksportida. Üks HTTP-kutse lõpetamise hetkel on lihtsam ja saaja saab oma märgi kätte, kuni saavutus on veel värske.

See kiirjuhend viib sind läbi kogu tee nelja kutsega: hangi võti, loo väljaandja, loo märk, anna see välja. Seejärel vaatame, kuidas anda saajale kinnituslink ja tulemust kontrollida. Iga allolev päringu kuju pärineb tegelikult kasutusele võetud töötlejatest, nii et võid selle kopeerida ja käivitada.

Mida sul enne alustamist vaja on

• Tasuta konto aadressil badges.ninja. Selle õpetuse jaoks piisab Free-paketist: see sisaldab 2 väljaandjat, 5 märki, 2 kohta ja 1 API-võtit.
• Üks API-võti, mis on loodud armatuurlaual.
• Märgi pilt PNG- või JPG-vormingus või märk, mille kujundasid visuaalses kujundajas.

Kõige baas-URL on https://api.badges.ninja.

1. samm: loo API-võti

Logi sisse, ava külgribal API Keys ja klõpsa Create API Key. Anna sellele nimi, mis ütleb, kus see elama hakkab, näiteks „LMS integration“, et saaksid võtmeid hiljem vahetades neid eristada.

Võtit näidatakse täpselt üks kord. Kopeeri see kohe oma saladuste haldurisse või keskkonnamuutujasse. Võtmed näevad välja nagu bws_, millele järgneb 32 kuueteistkümnendmärki, ja neid saadetakse igas päringus päises X-Api-Key. Võtme tühistamine samal ekraanil jõustub kohe.

Mõned harjumused, mis hiljem vaeva säästavad:

• Ära pane võtit kunagi esiotsa koodi ega avalikku hoidlasse. Kutsu API-t serverist, serverita funktsioonist või automatiseerimisvahendist.
• Kasuta iga integratsiooni jaoks ühte võtit. Kui üks lekib, tühistad ühe integratsiooni, mitte kõiki.
• Armatuurlaud aktsepteerib ka sinu sisselogitud seanssi (Cognito JWT, saadetud kui Authorization: Bearer), kuid skriptide ja integratsioonide jaoks on õige tööriist API-võti.

Kõik allolevad näited loevad võtme keskkonnamuutujast BADGES_API_KEY.

2. samm: loo väljaandja

Väljaandja on organisatsioon, kes märgi taga seisab. See kuvatakse igal kinnituslehel ja Open Badge v2.0 andmetes, seega kasuta nime, mida inimesed tegelikult tunnevad.

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

Kohustuslikud väljad on name (vähemalt 3 märki), url (kehtiv http- või https-aadress) ja email. Valikulised väljad on logo (base64-kodeeringus pilt) ja linkedinOrganizationId, mis lülitab sinu avalikel tunnistuslehtedel sisse nupu Add to LinkedIn Profile.

Vastus sisaldab väljaandja identifikaatorit:

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

Hoia see väärtus täpselt sellisena, nagu see tagastati. See on järgmise sammu sisend.

Väljaandja kinnitamine

Märke saab luua ainult kinnitatud väljaandja alla. Kinnitamine käib nii:

• Kui väljaandja e-post ühtib sinu konto e-postiga, kinnitatakse väljaandja automaatselt. See on esimese katse jaoks kiireim tee.
• Kui e-post on erinev, saadetakse sellele aadressile koodiga kinnituskiri. Kinnitad koodi armatuurlaual (või väljaandjate API kaudu) enne märkide loomist.

Seega kasuta selle õpetuse jaoks sama e-posti, millega registreerusid.

3. samm: loo märk

Märk on korduvkasutatav mall: nimi, kirjeldus, kriteeriumid ja pilt. Iga hiljem väljastatav andmine viitab sellele tagasi.

Päring on tavaline JSON. Pilt läheb sisse base64-stringina, seega ei pea sa multipart-üleslaadimisega vaeva nägema. Andme-URL-i eesliide, nagu data:image/png;base64,, aktsepteeritakse ja eemaldatakse.

JavaScript (Node 18 või uuem):

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)

Kõik viis välja (name, description, criteria, image, issuerId) on kohustuslikud. Kaks valikulist on väärt teadmist: shareText, vaiketekst, mida saajad näevad sotsiaalvõrgustikes jagades (toetab kohatäiteid {{badge_name}}, {{issuer_name}} ja {{award_url}}), ning designJson, mis salvestab visuaalse kujundaja dokumendi, et märki saaks hiljem kiht kihi haaval muuta.

Edu korral tagastatakse HTTP 200 ja { "badgeId": "<id>" }. Pilt salvestatakse püsivalt ja märk on nüüd Open Badge v2.0 BadgeClass, mille igaüks saab alla laadida.

Kas märke üldse koodis luua?

Tavaliselt mitte. Märgi kujundamine on loominguline ülesanne ja visuaalne kujundaja (üle 80 malli, kujundid, ikoonid, 11 fonti ja oma üleslaadimised) on selleks palju parem koht kui skript. Levinud muster on kujundada iga märk armatuurlaual üks kord ja lasta oma integratsioonil seejärel anda välja ainult selle põhjal tehtud andmisi. Märgid saad välja lugeda käsuga GET /badges ja kopeerida soovitud märgi id.

Loo märke API kaudu siis, kui genereerid neid programmiliselt, näiteks üks igale kursusele sadade kursustega kataloogis, või kui täidad testkeskkonda.

4. samm: anna märk välja

See on kutse, mida sinu integratsioon teeb tuhandeid kordi. Saada märk, saaja ja kuupäev.

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

Reeglid, mis inimesi komistama panevad:

• recipient on pesastatud objekt väljadega name ja email. Lamedad väljad nagu recipientEmail lükatakse tagasi.
• recipient.name peab olema vähemalt 5 märki pikk.
• issuedOn on kohustuslik. Saada epohhi millisekundid või ISO-kuupäev, näiteks 2026-09-28.
• expires on valikuline ja võtab samu vorminguid.

Edu korral tagastatakse HTTP 200 ja vastuse sisu, milles on awardId. Saaja e-post salvestatakse Open Badge’i andmetes SHA-256 räsina, seega avalik JSON ei paljasta seda kunagi.

5. samm: leia kinnitusleht ja Open Badge’i JSON

Andmise vastus annab sulle identifikaatori, mitte valmis linki. Identifikaator lõpeb GUID-iga ja avalikud lehed ehitatakse sellest GUID-ist:

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

Kui sinu awardId tuleb täis-URL-ina, kasuta GUID-ina viimast tee segmenti.

Mõlemad on avalikud. Igaüks, kellel on link, saab tunnistuse kinnitada ilma kontot loomata ja see ongi mõte: tööandja või vastuvõtuametnik peab suutma märgi kümne sekundiga üle kontrollida.

Too JSON, et näha, mida maailm näeb:

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

Saad Open Badge v2.0 väite: märgi, millele see viitab, räsitud saaja identiteedi, väljaandmise kuupäeva ja kinnitusploki, mis viitab tagasi majutatud väitele. Kuna tegu on standardsete Open Badges’i andmetega, oskab neid lugeda iga vormingut mõistev tööriist. Just see teisaldatavus on põhjus, miks valida Open Badges, mitte omanduslik PDF; Open Badges vs PDF-sertifikaadid käsitleb kompromissi põhjalikumalt.

Kuidas saajad tunnistuse kätte saavad

Andmise loomine on eraldi asi saaja teavitamisest. Saajad saavad oma tunnistused avada saajaportaali kaudu aadressil badges.ninja/me, mis kasutab maagilise lingiga sisselogimist ilma paroolita, ja nad saavad avaldada avaliku profiili aadressil badges.ninja/u/<handle>. Kinnituslehelt saavad nad märgi lisada LinkedIni, alla laadida PDF-sertifikaadi või linki jagada.

Esimeste testide jaoks saada andmine iseendale oma e-posti aadressile ja käi saaja kogemus läbi. See on kiireim viis märgata asju, näiteks kohmakalt kõlavat märgi kirjeldust.

Veakäsitlus, mis ei tee haiget

API kasutab tavalisi HTTP olekukoode. Need, millega kokku puutud:

Kaks praktilist nõuannet. Esiteks, käsitle 400 andmeprobleemina ja logi vastuse sisu, sest see nimetab ebaõnnestunud välja. Teiseks, tee oma integratsioon idempotentseks enda poolel: salvesta awardId oma andmebaasis lõpetamise kirje kõrvale ja kontrolli seda enne API uuesti kutsumist. Nii ei väljasta korratud webhook ega uuesti käivitatud töö kunagi samale inimesele kahte tunnistust.

Kõik kokku päris integratsioonis

Tüüpiline ühendus näeb välja nii:

1. Kujunda märgid armatuurlaual, üks kursuse või verstaposti kohta, ja pane iga märgi ID kirja.
2. Salvesta oma süsteemis vastavus kursuselt märgi ID-le.
3. Kui õppija kursuse lõpetab, kutsub sinu server POST /awards tema nime, e-posti ja lõpetamise kuupäevaga.
4. Salvesta tagastatud awardId lõpetamise kirje juurde.
5. Näita kinnituslinki oma tootes, et õppija näeks seda sealt lahkumata.

Kui sa pigem koodi ei kirjuta, töötab sama kutse igast automatiseerimisvahendist, mis oskab saata HTTP-päringu JSON-sisu ja kohandatud päisega. Suuna see aadressile https://api.badges.ninja/awards ja vasta oma vormi- või tabeliväljad väljadele badgeId, recipient.name, recipient.email ja issuedOn.

Paketid ja piirangud, mida tasub teada

API on saadaval igas paketis; selle avamise eest ei maksa sa lisatasu. Free-pakett ($0) katab 2 väljaandjat, 5 märki, 2 kohta, 1 API-võtu ja 1,200 tunnistust aastas. Starter maksab $9 kuus ja Pro $29 kuus, kõrgemate piirangutega. Enne kui kasutuselevõttu mõõtkavasid, vaata hinnalehelt kehtivaid numbreid. Kui võrdled, mida teised platvormid API-juurdepääsu eest küsivad, näitab Credly alternatiiv kulusid kõrvuti.

Kuhu edasi

• Täielik lõpp-punktide viide asub API dokumentatsioonis, mis on saadaval 40 keeles.
• Autentimise ja võtmete käsitlemise üksikasjad leiad autentimisjuhendist.
• Veakoodide põhjalikuma kirjelduse leiad vigade viitest.
• Kui ühe kutse korraga on sulle väikseks jäänud, kasuta armatuurlaual hulgiandmist: laadi üles CSV ja vajaduse korral peata või jätka käivitust.

Esimene õnnestunud andmine on kõige raskem. Pärast seda tuleb sama kutse vaid ühendada kohtadega, kus saavutusi juba salvestatakse.

Valmis väljastama oma esimest kontrollitavat tunnistust? Alusta tasuta aadressil badges.ninja – visuaalne kujundaja, avalik kinnitusleht, PDF-sertifikaat, Open Badge v2.0 väljund. Krediitkaarti pole vaja.