Izdavanje Open Badgeva putem Badges Ninja REST API-ja: brzi vodič

Većini programa vjerodajnica API nikada ne treba. Ako vodite tečaj s nekoliko stotina polaznika godišnje, nadzorna ploča radi sve: u vizualnom dizajneru dizajnirate značku, učitate CSV i svaki primatelj dobije stranicu za provjeru i PDF certifikat. Ako je to vaš slučaj, počnite s vodičem kako izdati Open Badgeve iz CSV-a i vratite se kasnije.

API se isplati kada vjerodajnice treba izdavati drugi sustav: vaša platforma za učenje označi tečaj kao završen, vaš alat za registraciju zatvori događaj, vaš HR sustav zabilježi završen modul o usklađenosti. U takvim slučajevima nitko ne želi na kraju svakog tjedna izvoziti tablicu. Jedan HTTP poziv u trenutku završetka jednostavniji je, a primatelj dobiva značku dok je postignuće još svježe.

Ovaj brzi vodič prolazi cijeli put u četiri poziva: nabavite ključ, kreirajte izdavatelja, kreirajte značku, dodijelite je. Zatim pogledamo kako primatelju predati poveznicu za provjeru i kako provjeriti rezultat. Svaki oblik zahtjeva u nastavku dolazi iz postavljenih handlera, pa ga možete zalijepiti i pokrenuti.

Što vam treba prije početka

• Besplatan račun na badges.ninja. Plan Free dovoljan je za ovaj vodič: uključuje 2 izdavatelja, 5 znački, 2 mjesta i 1 API ključ.
• Jedan API ključ, kreiran na nadzornoj ploči.
• PNG ili JPG za sliku značke ili značka koju ste dizajnirali u vizualnom dizajneru.

Osnovni URL za sve je https://api.badges.ninja.

Korak 1: Kreirajte API ključ

Prijavite se, otvorite API Keys u bočnoj traci i kliknite Create API Key. Dajte mu ime koje govori gdje će živjeti, primjerice „LMS integracija”, kako biste kasnije pri rotaciji mogli razlikovati ključeve.

Ključ se prikazuje samo jednom. Odmah ga kopirajte u svoj upravitelj tajni ili u varijablu okruženja. Ključevi izgledaju kao bws_ iza kojeg slijedi 32 heksadecimalna znaka, a šaljete ih u zaglavlju X-Api-Key uz svaki zahtjev. Opoziv ključa na istom zaslonu stupa na snagu odmah.

Nekoliko navika koje kasnije štede muke:

• Nikada ne stavljajte ključ u front-end kod ni u javni repozitorij. API pozivajte sa servera, serverless funkcije ili alata za automatizaciju.
• Koristite jedan ključ po integraciji. Ako jedan procuri, opozivate jednu integraciju, a ne sve.
• Nadzorna ploča prihvaća i vašu prijavljenu sesiju (Cognito JWT poslan kao Authorization: Bearer), ali za skripte i integracije pravi alat je API ključ.

Svi primjeri u nastavku čitaju ključ iz varijable okruženja BADGES_API_KEY.

Korak 2: Kreirajte izdavatelja

Izdavatelj je organizacija koja stoji iza značke. Pojavljuje se na svakoj stranici za provjeru i unutar podataka Open Badge v2.0, zato koristite naziv koji ljudi stvarno poznaju.

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

Obavezna polja su name (najmanje 3 znaka), url (važeća http ili https adresa) i email. Neobavezna polja su logo (slika kodirana u base64) i linkedinOrganizationId, koji uključuje gumb Add to LinkedIn Profile na vašim javnim stranicama vjerodajnica.

Odgovor sadrži identifikator izdavatelja:

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

Zadržite tu vrijednost točno onakvom kakva je vraćena. Ona je ulaz za sljedeći korak.

Provjera izdavatelja

Značke se mogu kreirati samo pod provjerenim izdavateljem. Provjera funkcionira ovako:

• Ako se e-adresa izdavatelja podudara s e-adresom vašeg računa, izdavatelj se provjerava automatski. To je najbrži put za prvi test.
• Ako je e-adresa drugačija, na nju se šalje e-poruka za provjeru s kodom. Kôd potvrđujete na nadzornoj ploči (ili putem API-ja izdavatelja) prije kreiranja znački.

Zato za ovaj vodič upotrijebite istu e-adresu kojom ste se registrirali.

Korak 3: Kreirajte značku

Značka je predložak za višekratnu upotrebu: naziv, opis, kriteriji i slika. Svako dodjeljivanje koje kasnije izdate upućuje na nju.

Zahtjev je običan JSON. Slika se šalje kao base64 niz, pa nema multipart učitavanja s kojim biste se mučili. Prefiks data URL-a poput data:image/png;base64, prihvaća se i uklanja.

JavaScript (Node 18 ili noviji):

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)

Svih pet polja (name, description, criteria, image, issuerId) obavezno je. Vrijedi znati dva neobavezna: shareText, zadani tekst koji primatelji vide pri dijeljenju na društvenim mrežama (podržava rezervirana mjesta {{badge_name}}, {{issuer_name}} i {{award_url}}), i designJson, koji pohranjuje dokument vizualnog dizajnera kako bi se značka kasnije mogla uređivati sloj po sloj.

Uspjeh vraća HTTP 200 s { "badgeId": "<id>" }. Slika se trajno pohranjuje, a značka je sada Open Badge v2.0 BadgeClass koji svatko može dohvatiti.

Treba li uopće kreirati značke kodom?

Obično ne. Dizajn značke kreativan je zadatak, a vizualni dizajner (80+ predložaka, oblika, ikona, 11 fontova i vlastita učitavanja) puno je bolje mjesto za to od skripte. Uobičajen obrazac je da svaku značku jednom dizajnirate na nadzornoj ploči, a vaša integracija samo izdaje dodjele prema njoj. Svoje značke možete popisati s GET /badges i kopirati id one koja vam treba.

Značke kreirajte putem API-ja kada ih generirate programski, primjerice jednu po tečaju u katalogu od stotina, ili kada punite testno okruženje.

Korak 4: Dodijelite značku

Ovo je poziv koji će vaša integracija izvršiti tisuće puta. Pošaljite značku, primatelja i 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 kojima ljudi griješe:

• recipient je ugniježđeni objekt s name i email. Ravna polja poput recipientEmail se odbijaju.
• recipient.name mora imati najmanje 5 znakova.
• issuedOn je obavezan. Pošaljite milisekunde epohe ili ISO datum poput 2026-09-28.
• expires je neobavezan i prima iste formate.

Uspjeh je HTTP 200 s tijelom koje sadrži awardId. E-adresa primatelja pohranjuje se kao SHA-256 hash u Open Badge podacima, pa je javni JSON nikada ne otkriva.

Korak 5: Pronađite stranicu za provjeru i Open Badge JSON

Odgovor na dodjelu daje vam identifikator, a ne gotovu poveznicu. Identifikator završava GUID-om, a javne stranice grade se od tog GUID-a:

• Stranica za provjeru čitljiva ljudima: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Ako vam awardId stigne kao puni URL, kao GUID upotrijebite zadnji segment putanje.

Obje su javne. Svatko s poveznicom može provjeriti vjerodajnicu bez otvaranja računa, a u tome je poanta: poslodavac ili referent za upise trebao bi moći provjeriti značku za deset sekundi.

Dohvatite JSON da vidite što vidi svijet:

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

Dobivate Open Badge v2.0 Assertion: značku na koju upućuje, hashirani identitet primatelja, datum izdavanja i blok za provjeru koji upućuje natrag na hostanu tvrdnju. Budući da su to standardni podaci Open Badges, može ih pročitati svaki alat koji razumije taj format. Ta prenosivost razlog je da se odabere Open Badges umjesto vlasničkog PDF-a; Open Badges vs PDF certifikati detaljnije obrađuje taj kompromis.

Kako primatelji dobivaju vjerodajnicu

Kreiranje dodjele odvojeno je od obavještavanja primatelja. Primatelji svoje vjerodajnice mogu otvoriti putem portala za primatelje na badges.ninja/me, koji koristi prijavu magičnom poveznicom bez lozinke, a mogu objaviti i javni profil na badges.ninja/u/<handle>. Sa stranice za provjeru mogu dodati značku na LinkedIn, preuzeti PDF certifikat ili podijeliti poveznicu.

Za prvih nekoliko testova pošaljite dodjelu sami sebi na vlastitu e-adresu i prođite iskustvo primatelja. To je najbrži način da primijetite stvari poput opisa značke koji zvuči nespretno.

Obrada pogrešaka koja ne boli

API koristi obične HTTP statusne kodove. Oni na koje ćete naići:

Dva praktična savjeta. Prvo, 400 tretirajte kao problem s podacima i zabilježite tijelo odgovora jer imenuje polje koje nije prošlo. Drugo, svoju integraciju učinite idempotentnom sa svoje strane: pohranite awardId uz zapis o završetku u vlastitoj bazi i provjerite ga prije ponovnog poziva API-ja. Tako ponovljeni webhook ili ponovno pokrenut posao nikada neće izdati istoj osobi dvije vjerodajnice.

Sve zajedno u pravoj integraciji

Tipična konfiguracija izgleda ovako:

1. Dizajnirajte značke na nadzornoj ploči, po jednu za tečaj ili prekretnicu, i zabilježite ID svake značke.
2. Pohranite u svoj sustav preslikavanje tečaja u ID značke.
3. Kada polaznik završi tečaj, vaš server poziva POST /awards s njegovim imenom, e-adresom i datumom završetka.
4. Spremite vraćeni awardId uz zapis o završetku.
5. Prikažite poveznicu za provjeru unutar vlastitog proizvoda kako bi je polaznik vidio bez napuštanja.

Ako radije ne pišete kod, isti poziv radi iz bilo kojeg alata za automatizaciju koji može poslati HTTP zahtjev s JSON tijelom i prilagođenim zaglavljem. Usmjerite ga na https://api.badges.ninja/awards i preslikajte polja svojeg obrasca ili tablice na badgeId, recipient.name, recipient.email i issuedOn.

Planovi i ograničenja koje vrijedi znati

API je dostupan na svakom planu; ne plaćate dodatno za njegovo otključavanje. Plan Free ($0) pokriva 2 izdavatelja, 5 znački, 2 mjesta, 1 API ključ i 1.200 vjerodajnica godišnje. Starter košta $9 mjesečno, a Pro $29 mjesečno, s višim ograničenjima. Prije planiranja uvođenja provjerite stranicu s cijenama za aktualne iznose. Ako uspoređujete što druge platforme naplaćuju za pristup API-ju, Credly alternative prikazuje troškove usporedno.

Kamo dalje

• Potpuna referenca endpointa nalazi se u dokumentaciji API-ja, koja je dostupna na 40 jezika.
• Za pojedinosti o autentifikaciji i rukovanju ključevima pogledajte vodič za autentifikaciju.
• Za detaljne kodove pogrešaka pogledajte referencu pogrešaka.
• Kada vam postane tijesno s jednim pozivom odjednom, upotrijebite skupne dodjele na nadzornoj ploči: učitajte CSV i po potrebi pauzirajte ili nastavite izvođenje.

Prva uspješna dodjela najteži je dio. Nakon toga preostaje samo ugraditi isti poziv tamo gdje se postignuća već bilježe.

Spremni izdati svoju prvu provjerljivu vjerodajnicu? Počnite besplatno na badges.ninja — vizualni dizajner, javna stranica za provjeru, PDF certifikat, izlaz Open Badge v2.0. Kreditna kartica nije potrebna.