Vydávanie Open Badges cez REST API Badges Ninja: rýchly štart

Väčšina programov digitálnych osvedčení API nikdy nepotrebuje. Ak vediete kurz s pár stovkami absolventov ročne, nástenka zvládne všetko: navrhnete digitálny odznak vo vizuálnom dizajnéri, nahráte CSV a každý príjemca dostane stránku na overenie a PDF certifikát. Ak je to váš prípad, začnite článkom ako vydávať Open Badges z CSV a vráťte sa neskôr.

API sa oplatí, keď majú osvedčenia vydávať iné systémy: vaša vzdelávacia platforma označí kurz ako dokončený, váš registračný nástroj uzavrie podujatie, váš HR systém zaeviduje dokončený modul o súlade s predpismi. V takých prípadoch nikto nechce na konci každého týždňa exportovať tabuľku. Jedno HTTP volanie v okamihu dokončenia je jednoduchšie a príjemca dostane odznak, kým je úspech ešte čerstvý.

Tento rýchly štart prejde celou cestou v štyroch volaniach: získate kľúč, vytvoríte vydavateľa, vytvoríte odznak a udelíte ho. Potom sa pozrieme, ako odovzdať príjemcovi odkaz na overenie a ako skontrolovať výsledok. Každý tvar požiadavky nižšie pochádza z nasadených obslužných funkcií, takže ho môžete skopírovať a spustiť.

Čo potrebujete na začiatok

• Bezplatný účet na badges.ninja. Plán Free pre tento návod stačí: zahŕňa 2 vydavateľov, 5 odznakov, 2 miesta a 1 API kľúč.
• Jeden API kľúč vytvorený z nástenky.
• PNG alebo JPG pre obrázok odznaku, prípadne odznak, ktorý ste navrhli vo vizuálnom dizajnéri.

Základná URL pre všetko je https://api.badges.ninja.

Krok 1: Vytvorte API kľúč

Prihláste sa, otvorte API Keys v bočnom paneli a kliknite na Create API Key. Dajte mu názov, ktorý hovorí, kde bude žiť, napríklad „LMS integration“, aby ste kľúče pri neskoršej rotácii vedeli rozlíšiť.

Kľúč sa zobrazí presne raz. Okamžite ho skopírujte do správcu tajomstiev alebo do premennej prostredia. Kľúče vyzerajú ako bws_ nasledované 32 hexadecimálnymi znakmi a posielajú sa v hlavičke X-Api-Key pri každej požiadavke. Zrušenie kľúča z tej istej obrazovky nadobudne účinnosť okamžite.

Pár návykov, ktoré neskôr ušetria starosti:

• Nikdy nevkladajte kľúč do front-end kódu ani do verejného repozitára. API volajte zo servera, serverless funkcie alebo automatizačného nástroja.
• Používajte jeden kľúč na jednu integráciu. Ak jeden unikne, zrušíte jednu integráciu, nie všetky.
• Nástenka akceptuje aj vašu prihlásenú reláciu (Cognito JWT poslaný ako Authorization: Bearer), no pre skripty a integrácie je správnym nástrojom API kľúč.

Všetky príklady nižšie čítajú kľúč z premennej prostredia s názvom BADGES_API_KEY.

Krok 2: Vytvorte vydavateľa

Vydavateľ je organizácia, ktorá za odznakom stojí. Zobrazuje sa na každej stránke na overenie aj v dátach Open Badge v2.0, preto použite názov, ktorý ľudia skutočne poznajú.

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

Povinné polia sú name (aspoň 3 znaky), url (platná adresa http alebo https) a email. Voliteľné polia sú logo (obrázok zakódovaný v base64) a linkedinOrganizationId, ktoré zapne tlačidlo Pridať do profilu LinkedIn na vašich verejných stránkach osvedčení.

Odpoveď obsahuje identifikátor vydavateľa:

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

Ponechajte túto hodnotu presne tak, ako bola vrátená. Je vstupom do ďalšieho kroku.

Overenie vydavateľa

Odznaky sa dajú vytvárať len pod overeným vydavateľom. Overenie funguje takto:

• Ak sa e-mail vydavateľa zhoduje s e-mailom vášho účtu, vydavateľ sa overí automaticky. Je to najrýchlejšia cesta pre prvý test.
• Ak je e-mail iný, na túto adresu príde overovací e-mail s kódom. Kód potvrdíte na nástenke (alebo cez API vydavateľov) pred vytváraním odznakov.

Preto pre tento návod použite ten istý e-mail, s ktorým ste sa registrovali.

Krok 3: Vytvorte odznak

Odznak je opakovane použiteľná šablóna: názov, popis, kritériá a obrázok. Každé udelenie, ktoré neskôr vydáte, sa naň odkazuje.

Požiadavka je obyčajný JSON. Obrázok sa posiela ako reťazec base64, takže nemusíte bojovať s multipart nahrávaním. Predpona ako data:image/png;base64, sa akceptuje a odstráni.

JavaScript (Node 18 alebo novší):

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)

Všetkých päť polí (name, description, criteria, image, issuerId) je povinných. Za zmienku stoja dve voliteľné: shareText, predvolený text, ktorý príjemcovia vidia pri zdieľaní na sociálnych sieťach (podporuje zástupné znaky {{badge_name}}, {{issuer_name}} a {{award_url}}), a designJson, ktoré ukladá dokument vizuálneho dizajnéra, aby sa odznak dal neskôr upravovať vrstvu po vrstve.

Úspech vráti HTTP 200 s { "badgeId": "<id>" }. Obrázok sa uloží natrvalo a odznak je odteraz Open Badge v2.0 BadgeClass, ktorý si môže načítať ktokoľvek.

Treba odznaky vôbec vytvárať v kóde?

Zvyčajne nie. Návrh odznakov je kreatívna úloha a vizuálny dizajnér (80+ šablón, tvary, ikony, 11 písiem a vlastné nahrávania) je na ňu oveľa lepším miestom ako skript. Bežný vzor je navrhnúť každý odznak raz na nástenke a nechať integráciu len vydávať udelenia voči nemu. Svoje odznaky si môžete vypísať cez GET /badges a skopírovať id toho, ktorý potrebujete.

Odznaky vytvárajte cez API, keď ich generujete programovo, napríklad po jednom pre každý kurz v katalógu so stovkami kurzov, alebo keď napĺňate testovacie prostredie.

Krok 4: Udeľte odznak

Toto je volanie, ktoré vaša integrácia vykoná tisíckrát. Pošlite odznak, príjemcu a dátum.

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

Pravidlá, na ktorých ľudia zakopnú:

• recipient je vnorený objekt s name a email. Ploché polia ako recipientEmail sa odmietnu.
• recipient.name musí mať aspoň 5 znakov.
• issuedOn je povinné. Pošlite epochové milisekundy alebo ISO dátum ako 2026-09-28.
• expires je voliteľné a prijíma rovnaké formáty.

Úspech je HTTP 200 s telom obsahujúcim awardId. E-mail príjemcu sa v dátach Open Badge ukladá ako hash SHA-256, takže ho verejný JSON nikdy neprezradí.

Krok 5: Nájdite stránku na overenie a Open Badge JSON

Odpoveď na udelenie vám dáva identifikátor, nie hotový odkaz. Identifikátor sa končí GUID-om a verejné stránky sa budujú z tohto GUID-u:

• Stránka na overenie čitateľná pre ľudí: https://badges.ninja/awards/<awardId>
• Open Badge v2.0 JSON-LD: https://api.badges.ninja/certify-badge/award/<awardId>

Ak vám awardId príde ako celá URL, ako GUID použite posledný segment cesty.

Obe sú verejné. Ktokoľvek s odkazom môže osvedčenie overiť bez vytvorenia účtu, a o to ide: zamestnávateľ alebo prijímacia komisia by mali vedieť odznak skontrolovať za desať sekúnd.

Načítajte JSON a uvidíte, čo vidí svet:

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

Dostanete Open Badge v2.0 Assertion: odznak, na ktorý sa odkazuje, hashovanú identitu príjemcu, dátum vydania a overovací blok smerujúci späť na hostované potvrdenie. Keďže ide o štandardné dáta Open Badges, prečíta ich každý nástroj, ktorý formát pozná. Táto prenosnosť je dôvod, prečo zvoliť Open Badges namiesto proprietárneho PDF; Open Badges vs PDF certifikáty rozoberá tento kompromis podrobnejšie.

Ako príjemcovia osvedčenie dostanú

Vytvorenie udelenia je oddelené od informovania príjemcu. Príjemcovia môžu otvoriť svoje osvedčenia cez portál pre príjemcov na badges.ninja/me, ktorý používa prihlásenie cez magic link bez hesla, a môžu zverejniť verejný profil na badges.ninja/u/<handle>. Zo stránky na overenie môžu odznak pridať na LinkedIn, stiahnuť PDF certifikát alebo zdieľať odkaz.

Pri prvých pár testoch pošlite udelenie na vlastnú e-mailovú adresu a prejdite si zážitok príjemcu. Je to najrýchlejší spôsob, ako si všimnúť veci, napríklad popis odznaku, ktorý znie nemotorne.

Spracovanie chýb, ktoré nebolí

API používa bežné stavové kódy HTTP. Tie, s ktorými sa stretnete:

Dva praktické tipy. Po prvé, 400 berte ako problém s dátami a logujte telo odpovede, keďže pomenúva chybné pole. Po druhé, urobte svoju integráciu idempotentnou na vašej strane: uložte awardId k záznamu o dokončení vo vlastnej databáze a skontrolujte ho pred ďalším volaním API. Opakovaný webhook alebo znovu spustená úloha tak nikdy nevydá tomu istému človeku dve osvedčenia.

Poskladanie do skutočnej integrácie

Typické zapojenie vyzerá takto:

1. Navrhnite odznaky na nástenke, po jednom na kurz alebo míľnik, a poznačte si ID každého odznaku.
2. Uložte vo svojom systéme mapovanie z kurzu na ID odznaku.
3. Keď študent dokončí kurz, váš server zavolá POST /awards s jeho menom, e-mailom a dátumom dokončenia.
4. Vrátené awardId uložte k záznamu o dokončení.
5. Zobrazte odkaz na overenie priamo vo vlastnom produkte, aby ho študent videl bez opustenia aplikácie.

Ak radšej nechcete písať kód, to isté volanie funguje z ľubovoľného automatizačného nástroja, ktorý vie poslať HTTP požiadavku s telom JSON a vlastnou hlavičkou. Nasmerujte ho na https://api.badges.ninja/awards a namapujte polia formulára alebo tabuľky na badgeId, recipient.name, recipient.email a issuedOn.

Plány a limity, ktoré stoja za povšimnutie

API je dostupné v každom pláne; za jeho odomknutie nič nedoplácate. Plán Free ($0) pokrýva 2 vydavateľov, 5 odznakov, 2 miesta, 1 API kľúč a 1,200 osvedčení ročne. Starter stojí $9 mesačne a Pro $29 mesačne, s vyššími limitmi. Aktuálne čísla si pozrite na stránke s cenami skôr, než dimenzujete nasadenie. Ak porovnávate, koľko si za prístup k API účtujú iné platformy, alternatíva ku Credly uvádza náklady vedľa seba.

Kam ďalej

• Úplný referenčný popis koncových bodov nájdete v dokumentácii API, ktorá je dostupná v 40 jazykoch.
• Podrobnosti o autentifikácii a práci s kľúčmi nájdete v príručke autentifikácie.
• Chybové kódy do hĺbky nájdete v referencii chýb.
• Keď vyrastiete z jedného volania naraz, použite hromadné udeľovanie na nástenke: nahrajte CSV a v prípade potreby beh pozastavte alebo obnovte.

Prvé úspešné udelenie je to najťažšie. Potom už len zapojíte to isté volanie tam, kde sa úspechy už zaznamenávajú.

Ste pripravení vydať svoje prvé overiteľné osvedčenie? Začnite zadarmo na badges.ninja — vizuálny dizajnér, verejná stránka na overenie, PDF certifikát, výstup Open Badge v2.0. Bez kreditnej karty.