Dokumentacja API odznak: tworzenie, weryfikacja i pobieranie odznak

Zarządzaj szablonami odznak — poświadczeniami, które wystawiasz odbiorcom.

Aby wystawić tę odznakę wielu odbiorcom naraz za pomocą pliku CSV zamiast API, zobacz Poświadczenia zbiorcze.

Wszystkie endpointy wymagają uwierzytelnienia za pomocą nagłówka X-Api-Key. Zobacz Uwierzytelnianie.

Utwórz odznakę

Utwórz nową odznakę w ramach zweryfikowanego wystawcy.

POST /badges

Parametry

Parametr	Typ	Wymagany	Opis
name	string	Tak	Tytuł odznaki
description	string	Tak	Co reprezentuje odznaka
criteria	string	Tak	Co odbiorca zrobił, aby zdobyć tę odznakę
image	string	Tak	Obraz zakodowany w Base64 (PNG lub JPG)
issuerId	string	Tak	Identyfikator zweryfikowanego wystawcy
shareText	string	Nie	Domyślny tekst udostępniania w mediach społecznościowych dla tej odznaki. Obsługuje symbole zastępcze , i . Jeśli go pominiesz, zostanie użyty wbudowany tekst domyślny.
designJson	string	Nie	Zserializowany dokument projektanta odznak, zapisywany, aby można było później edytować odznakę warstwa po warstwie.

Przykład

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Odpowiedź

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Uwagi

• Wystawca musi zostać zweryfikowany, zanim utworzysz odznaki.
• Obraz jest przechowywany w Amazon S3 i udostępniany przez nasz globalny CDN pod niezmiennym adresem URL opartym na zawartości.
• Gdy klasa odznaki już istnieje, wystawiaj ją odbiorcom za pomocą API poświadczeń.

---

Lista odznak

Pobierz wszystkie utworzone przez siebie odznaki.

GET /badges

Przykład

curl -X GET https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here"

Odpowiedź

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Pobierz odznakę

Pobierz pojedynczą odznakę wraz z tekstem udostępniania i zserializowanym dokumentem projektanta odznak (designJson). Z tego endpointu korzysta okno Edytuj odznakę, aby odtworzyć poszczególne warstwy; endpoint listy pomija designJson, aby odpowiedzi były lekkie.

GET /badges/{badgeId}

Parametry

Parametr	Typ	Wymagany	Opis
badgeId	string	Tak	Identyfikator odznaki (parametr ścieżki)

Przykład

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Odpowiedź

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Tekst udostępniania jest zawsze dołączany. Lżejszy wariant listy GET /badges?badgeId={id} zwraca ten sam dokument bez designJson i dołącza tekst udostępniania tylko wtedy, gdy zostanie wywołany z parametrem includeShareText=true.

---

Aktualizuj odznakę

Zaktualizuj istniejącą odznakę. Zmieniane są tylko podane pola.

PUT /badges/{badgeId}

Parametry

Parametr	Typ	Wymagany	Opis
badgeId	string	Tak	Identyfikator odznaki (parametr ścieżki)
name	string	Nie	Nowy tytuł odznaki
description	string	Nie	Nowy opis
criteria	string	Nie	Nowe kryteria
image	string	Nie	Nowy obraz zakodowany w Base64
designJson	string	Nie	Nowy zserializowany dokument projektanta odznak.

Przykład

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Odpowiedź

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Aktualizuj tekst udostępniania

Ustaw własny tekst wyświetlany, gdy odbiorcy udostępniają tę odznakę w mediach społecznościowych.

PUT /badges/{badgeId}/share-text

Parametry

Parametr	Typ	Wymagany	Opis
badgeId	string	Tak	Identyfikator odznaki (parametr ścieżki)
text	string	Tak	Tekst udostępniania (HTML jest niedozwolony)

Przykład

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Odpowiedź

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Usuń odznakę

Usuń odznakę. Odznaka nie może mieć żadnych poświadczeń.

DELETE /badges/{badgeId}

Przykład

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Odpowiedź

Zwraca zwykły ciąg potwierdzenia:

"badge has been deleted"

Błędy

• 400 — odznaka nadal ma wystawione poświadczenia: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — nie znaleziono odznaki