Vydávání Open Badges přes REST API badges.ninja: rychlý start

Většina programů pro vydávání osvědčení API nikdy nepotřebuje. Pokud vedete kurz s pár stovkami absolventů ročně, zvládne všechno ovládací panel: navrhnete odznak ve vizuálním návrháři, nahrajete CSV a každý příjemce dostane stránku s ověřením a certifikát v PDF. Pokud je to váš případ, začněte článkem jak vydávat Open Badges z CSV a vraťte se později.

API se vyplatí, když mají osvědčení vydávat jiné systémy: vaše vzdělávací platforma označí kurz jako dokončený, registrační nástroj uzavře událost, HR systém zaznamená dokončený compliance modul. V takových případech nikdo nechce na konci každého týdne exportovat tabulku. Jediné volání HTTP v okamžiku dokončení je jednodušší a příjemce dostane odznak, dokud je úspěch ještě čerstvý.

Tento rychlý start vás provede celou cestou ve čtyřech voláních: získejte klíč, vytvořte vydavatele, vytvořte odznak, udělte ho. Pak se podíváme, jak příjemci předat odkaz na ověření a zkontrolovat výsledek. Každý tvar požadavku níže pochází z nasazených handlerů, takže ho můžete vložit a spustit.

Co potřebujete na začátek

• Bezplatný účet na badges.ninja. Plán Free pro tento tutoriál stačí: zahrnuje 2 vydavatele, 5 odznaků, 2 místa a 1 klíč API.
• Jeden klíč API vytvořený v ovládacím panelu.
• PNG nebo JPG pro obrázek odznaku, nebo odznak navržený ve vizuálním návrháři.

Základní URL pro všechno je https://api.badges.ninja.

Krok 1: Vytvořte klíč API

Přihlaste se, otevřete API Keys v postranním panelu a klikněte na Create API Key. Dejte mu název, který říká, kde bude žít, například „LMS integration“, abyste při pozdější rotaci klíče rozlišili.

Klíč se zobrazí přesně jednou. Okamžitě ho zkopírujte do správce tajných údajů nebo do proměnné prostředí. Klíče vypadají jako bws_ následované 32 hexadecimálními znaky a posíláte je v hlavičce X-Api-Key s každým požadavkem. Zrušení klíče na stejné obrazovce má okamžitý účinek.

Pár návyků, které později ušetří potíže:

• Nikdy nevkládejte klíč do front-endového kódu ani do veřejného repozitáře. Volejte API ze serveru, serverless funkce nebo automatizačního nástroje.
• Používejte jeden klíč na jednu integraci. Když jeden unikne, zrušíte jednu integraci, ne všechny.
• Panel přijímá také vaši přihlášenou relaci (Cognito JWT posílaný jako Authorization: Bearer), ale pro skripty a integrace je správným nástrojem klíč API.

Všechny příklady níže čtou klíč z proměnné prostředí BADGES_API_KEY.

Krok 2: Vytvořte vydavatele

Vydavatel je organizace, která za odznakem stojí. Objeví se na každé stránce s ověřením i uvnitř dat Open Badge v2.0, použijte tedy název, který lidé skutečně znají.

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á pole jsou name (alespoň 3 znaky), url (platná adresa http nebo https) a email. Volitelná pole jsou logo (obrázek zakódovaný v base64) a linkedinOrganizationId, které zapne tlačítko Add to LinkedIn Profile na vašich veřejných stránkách osvědčení.

Odpověď obsahuje identifikátor vydavatele:

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

Uchovejte tuto hodnotu přesně v podobě, v jaké se vrátila. Je vstupem dalšího kroku.

Ověření vydavatele

Odznaky lze vytvářet jen pod ověřeným vydavatelem. Ověření funguje takto:

• Pokud e-mail vydavatele odpovídá e-mailu ve vašem účtu, vydavatel je ověřen automaticky. To je nejrychlejší cesta pro první test.
• Pokud je e-mail jiný, na tuto adresu přijde ověřovací e-mail s kódem. Kód potvrdíte v ovládacím panelu (nebo přes API vydavatelů) před vytvořením odznaků.

Pro tento tutoriál tedy použijte stejný e-mail, s jakým jste se registrovali.

Krok 3: Vytvořte odznak

Odznak je opakovaně použitelná šablona: název, popis, kritéria a obrázek. Každé pozdější udělení na ni odkazuje.

Požadavek je obyčejný JSON. Obrázek se posílá jako řetězec base64, takže se nemusíte potýkat s multipart nahráváním. Prefix data URL, například data:image/png;base64,, se přijme a odstraní.

JavaScript (Node 18 nebo novější):

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šech pět polí (name, description, criteria, image, issuerId) je povinných. Dvě volitelná stojí za zmínku: shareText, výchozí text, který příjemci vidí při sdílení na sociálních sítích (podporuje zástupné symboly {{badge_name}}, {{issuer_name}} a {{award_url}}), a designJson, který ukládá dokument vizuálního návrháře, aby šel odznak později upravovat vrstvu po vrstvě.

Úspěch vrací HTTP 200 s { "badgeId": "<id>" }. Obrázek je uložen trvale a odznak je nyní BadgeClass podle Open Badge v2.0, který si může stáhnout kdokoli.

Má vůbec smysl vytvářet odznaky v kódu?

Obvykle ne. Návrh odznaku je tvůrčí úkol a vizuální návrhář (přes 80 šablon, tvary, ikony, 11 písem a vlastní nahrávání) je k tomu mnohem lepší místo než skript. Běžný postup: každý odznak jednou navrhnete v ovládacím panelu a vaše integrace proti němu pouze uděluje. Své odznaky vypíšete přes GET /badges a zkopírujete id toho, který potřebujete.

Odznaky přes API vytvářejte, když je generujete programově, například jeden na kurz v katalogu o stovkách položek, nebo když plníte testovací prostředí.

Krok 4: Udělte odznak

Toto je volání, které bude vaše integrace provádět tisíckrát. Pošlete odznak, příjemce a 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"]

Pravidla, na kterých lidé klopýtají:

• recipient je vnořený objekt s name a email. Plochá pole jako recipientEmail se odmítají.
• recipient.name musí mít alespoň 5 znaků.
• issuedOn je povinné. Pošlete epochové milisekundy nebo datum ISO jako 2026-09-28.
• expires je volitelné a přijímá stejné formáty.

Úspěch je HTTP 200 s tělem obsahujícím awardId. E-mail příjemce je v datech Open Badge uložen jako hash SHA-256, takže ho veřejný JSON nikdy neodhalí.

Krok 5: Najděte stránku s ověřením a JSON Open Badge

Odpověď na udělení vám dá identifikátor, ne hotový odkaz. Identifikátor končí GUID a veřejné stránky se skládají z tohoto GUID:

• Stránka s ověřením čitelná pro člověka: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Pokud se váš awardId vrátí jako úplná URL, použijte jako GUID poslední segment cesty.

Obě stránky jsou veřejné. Kdokoli s odkazem může osvědčení ověřit bez vytvoření účtu, což je smyslem: zaměstnavatel nebo přijímací komise by měli odznak ověřit za deset sekund.

Stáhněte si JSON a uvidíte, co vidí svět:

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

Dostanete tvrzení (Assertion) Open Badge v2.0: odznak, na který odkazuje, hashovanou identitu příjemce, datum vydání a ověřovací blok ukazující zpět na hostované tvrzení. Protože jde o standardní data Open Badges, přečte je každý nástroj, který formát zná. Tato přenositelnost je důvodem, proč zvolit Open Badges místo proprietárního PDF; Open Badges vs. certifikáty PDF jde do tohoto kompromisu hlouběji.

Jak příjemci osvědčení získají

Vytvoření udělení je něco jiného než informování příjemce. Příjemci mohou své odznaky otevřít v portálu pro příjemce na badges.ninja/me, který používá přihlášení magickým odkazem bez hesla, a mohou zveřejnit veřejný profil na badges.ninja/u/<handle>. Ze stránky s ověřením mohou odznak přidat na LinkedIn, stáhnout certifikát v PDF nebo sdílet odkaz.

Při prvních testech si udělte odznak na vlastní e-mail a projděte si zážitek příjemce. Je to nejrychlejší způsob, jak si všimnout třeba nemotorně znějícího popisu odznaku.

Zpracování chyb, které nebolí

API používá běžné stavové kódy HTTP. Ty, na které narazíte:

Dvě praktické rady. Zaprvé, berte 400 jako problém s daty a logujte tělo odpovědi, protože pojmenovává chybné pole. Zadruhé, zajistěte idempotenci na své straně: uložte awardId vedle záznamu o dokončení ve vlastní databázi a před dalším voláním API ho zkontrolujte. Opakovaný webhook nebo znovu spuštěná úloha tak nikdy nevydá téže osobě dvě osvědčení.

Složení do skutečné integrace

Typické zapojení vypadá takto:

1. Navrhněte odznaky v ovládacím panelu, jeden na kurz nebo milník, a poznamenejte si ID každého odznaku.
2. Uložte ve svém systému mapování kurzu na ID odznaku.
3. Když student dokončí kurz, váš server zavolá POST /awards s jeho jménem, e-mailem a datem dokončení.
4. Vrácené awardId uložte k záznamu o dokončení.
5. Zobrazte odkaz na ověření přímo ve svém produktu, aby ho student viděl, aniž by produkt opustil.

Pokud nechcete psát kód, stejné volání funguje z jakéhokoli automatizačního nástroje, který umí odeslat požadavek HTTP s tělem JSON a vlastní hlavičkou. Nasměrujte ho na https://api.badges.ninja/awards a namapujte pole formuláře nebo tabulky na badgeId, recipient.name, recipient.email a issuedOn.

Plány a limity, které stojí za znalost

API je dostupné v každém plánu; za jeho odemčení nic navíc neplatíte. Plán Free ($0) pokrývá 2 vydavatele, 5 odznaků, 2 místa, 1 klíč API a 1,200 osvědčení ročně. Starter stojí $9 měsíčně a Pro $29 měsíčně, s vyššími limity. Než nasazení naplánujete, zkontrolujte aktuální čísla na stránce s cenami. Pokud srovnáváte, kolik si za přístup k API účtují jiné platformy, alternativa ke Credly uvádí náklady vedle sebe.

Kam dál

• Úplný přehled endpointů najdete v dokumentaci API, která je dostupná ve 40 jazycích.
• Podrobnosti o ověřování a práci s klíči najdete v průvodci ověřováním.
• Chybové kódy do hloubky popisuje přehled chyb.
• Až vyrostete z jednotlivých volání, použijte hromadné udělování v ovládacím panelu: nahrajte CSV a v případě potřeby běh pozastavte nebo obnovte.

První úspěšné udělení je nejtěžší část. Pak už jen stačí zapojit stejné volání tam, kde se úspěchy už zaznamenávají.

Připraveni vydat své první ověřitelné osvědčení? Začněte zdarma na badges.ninja — vizuální návrhář, veřejná stránka s ověřením, certifikát PDF, výstup Open Badge v2.0. Bez kreditní karty.