Wystawianie Open Badges przez REST API badges.ninja: szybki start

Większość programów certyfikacji nigdy nie potrzebuje API. Jeśli prowadzisz kurs z kilkuset absolwentami rocznie, panel robi wszystko: projektujesz odznakę w wizualnym projektancie, wgrywasz plik CSV, a każdy odbiorca dostaje stronę weryfikacji i certyfikat w PDF. Jeśli to Twoja sytuacja, zacznij od jak wystawiać Open Badges z pliku CSV i wróć tu później.

API zaczyna się opłacać, gdy poświadczenia ma wystawiać inny system: Twoja platforma e-learningowa oznacza kurs jako ukończony, narzędzie do rejestracji zamyka wydarzenie, system HR zapisuje ukończony moduł zgodności. W takich przypadkach nikt nie chce co tydzień eksportować arkusza. Jedno wywołanie HTTP w chwili ukończenia jest prostsze, a odbiorca dostaje swoją odznakę, gdy osiągnięcie jest jeszcze świeże.

Ten przewodnik prowadzi przez całą ścieżkę w czterech wywołaniach: zdobądź klucz, utwórz wystawcę, utwórz odznakę, przyznaj ją. Potem zobaczymy, jak przekazać odbiorcy link weryfikacyjny i sprawdzić wynik. Każdy kształt żądania poniżej pochodzi z wdrożonych handlerów, więc możesz go wkleić i uruchomić.

Co jest potrzebne na start

• Darmowe konto na badges.ninja. Plan Free wystarczy do tego samouczka: obejmuje 2 wystawców, 5 odznak, 2 miejsca i 1 klucz API.
• Jeden klucz API, utworzony w panelu.
• Plik PNG lub JPG z grafiką odznaki albo odznaka zaprojektowana w wizualnym projektancie.

Bazowy adres URL dla wszystkiego to https://api.badges.ninja.

Krok 1: Utwórz klucz API

Zaloguj się, otwórz API Keys na pasku bocznym i kliknij Create API Key. Nadaj mu nazwę mówiącą, gdzie będzie używany, np. „LMS integration”, żebyś później mógł odróżnić klucze przy rotacji.

Klucz jest pokazywany dokładnie raz. Od razu skopiuj go do menedżera sekretów lub zmiennej środowiskowej. Klucze mają postać bws_ i 32 znaków szesnastkowych, a przesyłasz je w nagłówku X-Api-Key przy każdym żądaniu. Unieważnienie klucza na tym samym ekranie działa natychmiast.

Kilka nawyków, które oszczędzą kłopotów:

• Nigdy nie umieszczaj klucza w kodzie front-endu ani w publicznym repozytorium. Wywołuj API z serwera, funkcji serverless lub narzędzia do automatyzacji.
• Używaj jednego klucza na integrację. Jeśli jeden wycieknie, unieważniasz jedną integrację, a nie wszystkie.
• Panel akceptuje też Twoją zalogowaną sesję (token Cognito JWT wysyłany jako Authorization: Bearer), ale w skryptach i integracjach właściwym narzędziem jest klucz API.

Wszystkie poniższe przykłady odczytują klucz ze zmiennej środowiskowej o nazwie BADGES_API_KEY.

Krok 2: Utwórz wystawcę

Wystawca to organizacja, która stoi za odznaką. Pojawia się na każdej stronie weryfikacji i w danych Open Badge v2.0, więc użyj nazwy, którą ludzie naprawdę 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"}'

Wymagane pola to name (co najmniej 3 znaki), url (poprawny adres http lub https) i email. Pola opcjonalne to logo (obraz zakodowany w base64) oraz linkedinOrganizationId, który włącza przycisk Add to LinkedIn Profile na Twoich publicznych stronach poświadczeń.

Odpowiedź zawiera identyfikator wystawcy:

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

Zachowaj tę wartość dokładnie w takiej postaci, w jakiej wróciła. To dane wejściowe następnego kroku.

Weryfikacja wystawcy

Odznaki można tworzyć tylko pod zweryfikowanym wystawcą. Weryfikacja działa tak:

• Jeśli e-mail wystawcy zgadza się z e-mailem na Twoim koncie, wystawca jest weryfikowany automatycznie. To najszybsza droga do pierwszego testu.
• Jeśli e-mail jest inny, na ten adres trafia wiadomość weryfikacyjna z kodem. Kod potwierdzasz w panelu (lub przez API wystawców) przed utworzeniem odznak.

W tym samouczku użyj więc tego samego e-maila, którym się zarejestrowałeś.

Krok 3: Utwórz odznakę

Odznaka to wielokrotnego użytku szablon: nazwa, opis, kryteria i obraz. Każde późniejsze przyznanie odwołuje się do niego.

Żądanie to zwykły JSON. Obraz przesyłasz jako ciąg base64, więc nie ma żadnego wysyłania multipart, z którym trzeba by się mocować. Prefiks data URL, taki jak data:image/png;base64,, jest akceptowany i usuwany.

JavaScript (Node 18 lub nowszy):

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)

Wszystkie pięć pól (name, description, criteria, image, issuerId) jest wymaganych. Warto znać dwa opcjonalne: shareText, czyli domyślny tekst, który odbiorcy widzą przy udostępnianiu w sieciach społecznościowych (obsługuje symbole zastępcze {{badge_name}}, {{issuer_name}} i {{award_url}}), oraz designJson, który przechowuje dokument wizualnego projektanta, by odznakę można było później edytować warstwa po warstwie.

Sukces zwraca HTTP 200 z { "badgeId": "<id>" }. Obraz jest przechowywany na stałe, a odznaka jest teraz BadgeClass w Open Badge v2.0, który może pobrać każdy.

Czy w ogóle tworzyć odznaki w kodzie?

Zwykle nie. Projekt odznaki to zadanie twórcze, a wizualny projektant (ponad 80 szablonów, kształty, ikony, 11 czcionek i własne wgrania) jest do tego znacznie lepszym miejscem niż skrypt. Częsty wzorzec: każdą odznakę projektujesz raz w panelu, a Twoja integracja tylko wystawia przyznania. Odznaki wylistujesz przez GET /badges i skopiujesz id tej, której potrzebujesz.

Twórz odznaki przez API, gdy generujesz je programowo, np. po jednej na kurs w katalogu liczącym setki pozycji, albo gdy zasilasz środowisko testowe.

Krok 4: Przyznaj odznakę

To wywołanie, które Twoja integracja wykona tysiące razy. Wyślij odznakę, odbiorcę i datę.

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

Zasady, na których ludzie się potykają:

• recipient to zagnieżdżony obiekt z name i email. Płaskie pola, takie jak recipientEmail, są odrzucane.
• recipient.name musi mieć co najmniej 5 znaków.
• issuedOn jest wymagane. Wyślij milisekundy epoki lub datę ISO, np. 2026-09-28.
• expires jest opcjonalne i przyjmuje te same formaty.

Sukces to HTTP 200 z treścią zawierającą awardId. E-mail odbiorcy jest przechowywany w danych Open Badge jako skrót SHA-256, więc publiczny JSON nigdy go nie ujawnia.

Krok 5: Znajdź stronę weryfikacji i JSON Open Badge

Odpowiedź na przyznanie daje identyfikator, a nie gotowy link. Identyfikator kończy się GUID-em, a publiczne strony budowane są z tego GUID-a:

• Czytelna dla człowieka strona weryfikacji: https://badges.ninja/awards/<awardId>
• JSON-LD Open Badge v2.0: https://api.badges.ninja/certify-badge/award/<awardId>

Jeśli Twój awardId wraca jako pełny adres URL, użyj ostatniego segmentu ścieżki jako GUID-a.

Obie strony są publiczne. Każdy, kto ma link, może zweryfikować poświadczenie bez zakładania konta — o to właśnie chodzi: pracodawca lub osoba rekrutująca na studia powinna móc sprawdzić odznakę w dziesięć sekund.

Pobierz JSON, aby zobaczyć to, co widzi świat:

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

Dostajesz asercję Open Badge v2.0: odznakę, do której się odwołuje, zahaszowaną tożsamość odbiorcy, datę wystawienia i blok weryfikacji wskazujący na hostowaną asercję. Ponieważ to standardowe dane Open Badges, odczyta je każde narzędzie rozumiejące ten format. Ta przenośność to powód, dla którego warto wybrać Open Badges zamiast własnościowego PDF-a; Open Badges kontra certyfikaty PDF omawia ten kompromis głębiej.

Jak odbiorcy otrzymują poświadczenie

Utworzenie przyznania to osobna sprawa niż poinformowanie o nim odbiorcy. Odbiorcy mogą otworzyć swoje poświadczenia w portalu odbiorcy pod adresem badges.ninja/me, który używa logowania magicznym linkiem bez hasła, i mogą opublikować publiczny profil pod badges.ninja/u/<handle>. Ze strony weryfikacji mogą dodać odznakę do LinkedIn, pobrać certyfikat w PDF lub udostępnić link.

Przy pierwszych testach wyślij przyznanie na własny adres e-mail i przejdź całą ścieżkę odbiorcy. To najszybszy sposób, by zauważyć np. niezręcznie brzmiący opis odznaki.

Obsługa błędów, która nie boli

API używa zwykłych kodów statusu HTTP. Te, które spotkasz:

Dwie praktyczne wskazówki. Po pierwsze, traktuj 400 jako problem z danymi i loguj treść odpowiedzi, bo wskazuje ona błędne pole. Po drugie, zadbaj o idempotentność po swojej stronie: zapisz awardId obok rekordu ukończenia we własnej bazie i sprawdź go przed ponownym wywołaniem API. Dzięki temu ponowiony webhook lub ponownie uruchomione zadanie nigdy nie wystawi tej samej osobie dwóch poświadczeń.

Składamy to w prawdziwą integrację

Typowe połączenie wygląda tak:

1. Zaprojektuj odznaki w panelu, po jednej na kurs lub kamień milowy, i zanotuj identyfikator każdej z nich.
2. Zapisz w swoim systemie mapowanie kursu na identyfikator odznaki.
3. Gdy uczestnik ukończy kurs, Twój serwer wywołuje POST /awards z jego imieniem, e-mailem i datą ukończenia.
4. Zapisz zwrócony awardId przy rekordzie ukończenia.
5. Pokaż link weryfikacyjny wewnątrz własnego produktu, żeby uczestnik zobaczył go bez opuszczania go.

Jeśli wolisz nie pisać kodu, to samo wywołanie działa z każdego narzędzia do automatyzacji, które potrafi wysłać żądanie HTTP z treścią JSON i własnym nagłówkiem. Wskaż mu https://api.badges.ninja/awards i zmapuj pola formularza lub arkusza na badgeId, recipient.name, recipient.email i issuedOn.

Plany i limity, które warto znać

API jest dostępne w każdym planie; nie płacisz dodatkowo za jego odblokowanie. Plan Free ($0) obejmuje 2 wystawców, 5 odznak, 2 miejsca, 1 klucz API i 1,200 poświadczeń rocznie. Starter kosztuje $9 miesięcznie, a Pro $29 miesięcznie, z wyższymi limitami. Zanim zaplanujesz wdrożenie, sprawdź aktualne liczby na stronie cennika. Jeśli porównujesz, ile inne platformy liczą za dostęp do API, alternatywa dla Credly zestawia koszty obok siebie.

Co dalej

• Pełna dokumentacja endpointów znajduje się w dokumentacji API, dostępnej w 40 językach.
• Szczegóły uwierzytelniania i obsługi kluczy znajdziesz w przewodniku po uwierzytelnianiu.
• Kody błędów w szczegółach opisuje dokumentacja błędów.
• Gdy wyrośniesz z pojedynczych wywołań, użyj masowych przyznań w panelu: wgraj CSV i w razie potrzeby wstrzymaj lub wznów przebieg.

Pierwsze udane przyznanie to najtrudniejsza część. Potem wystarczy wpiąć to samo wywołanie tam, gdzie osiągnięcia i tak są już zapisywane.

Gotowy, by wystawić pierwsze weryfikowalne poświadczenie? Zacznij za darmo na badges.ninja — wizualny projektant, publiczna strona weryfikacji, certyfikat PDF, wyjście Open Badge v2.0. Karta kredytowa niepotrzebna.