Badges API referenca: stvaranje, provjera i dohvat bedževa

Upravljajte predlošcima bedževa — vjerodajnicama koje izdajete primateljima.

Za izdavanje ovog bedža većem broju primatelja odjednom putem CSV uploada umjesto putem API-ja pogledajte Bulk Credentials.

Svi endpointi zahtijevaju autentifikaciju preko zaglavlja X-Api-Key. Pogledajte Autentifikacija.

Stvori bedž

Stvorite novi bedž pod provjerenim izdavateljem.

POST /badges

Parametri

Parametar	Tip	Obavezno	Opis
name	string	Da	Naslov bedža
description	string	Da	Što bedž predstavlja
criteria	string	Da	Što je primatelj učinio da zasluži ovaj bedž
image	string	Da	Slika kodirana u Base64 (PNG ili JPG)
issuerId	string	Da	ID provjerenog izdavatelja
shareText	string	Ne	Zadani tekst za dijeljenje na društvenim mrežama za ovaj bedž. Podržava rezervirana mjesta , i . Ako se izostavi, koristi se ugrađena zadana vrijednost.
designJson	string	Ne	Serijalizirani dokument dizajnera bedževa, pohranjen kako bi se bedž kasnije mogao ponovno uređivati sloj po sloj.

Primjer

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

Odgovor

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

Napomene

• Izdavatelj mora biti provjeren prije stvaranja bedževa.
• Slika se pohranjuje na Amazon S3 i poslužuje preko našeg globalnog CDN-a pod nepromjenjivim URL-om adresiranim prema sadržaju.
• Kad klasa bedža postoji, izdajte je primateljima pomoću Credentials API-ja.

---

Popis bedževa

Dohvatite sve bedževe koje ste stvorili.

GET /badges

Primjer

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

Odgovor

[
  {
    "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"
  }
]

---

Dohvat bedža

Dohvatite pojedinačni bedž, uključujući njegov tekst za dijeljenje i serijalizirani dokument dizajnera bedževa (designJson). Ovo je endpoint koji modalni prozor Edit Badge koristi za ponovno učitavanje pojedinih slojeva; endpoint za popis izostavlja designJson kako bi odgovori ostali laki.

GET /badges/{badgeId}

Parametri

Parametar	Tip	Obavezno	Opis
badgeId	string	Da	ID bedža (parametar putanje)

Primjer

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

Odgovor

{
  "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 za dijeljenje uvijek je uključen. Lakša varijanta popisa GET /badges?badgeId={id} vraća isti dokument bez designJson, a tekst za dijeljenje uključuje samo kad se pozove s includeShareText=true.

---

Ažuriranje bedža

Ažurirajte postojeći bedž. Mijenjaju se samo polja koja navedete.

PUT /badges/{badgeId}

Parametri

Parametar	Tip	Obavezno	Opis
badgeId	string	Da	ID bedža (parametar putanje)
name	string	Ne	Novi naslov bedža
description	string	Ne	Novi opis
criteria	string	Ne	Novi kriteriji
image	string	Ne	Nova slika kodirana u Base64
designJson	string	Ne	Novi serijalizirani dokument dizajnera bedževa.

Primjer

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

Odgovor

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

---

Ažuriranje teksta za dijeljenje

Postavite prilagođeni tekst koji se prikazuje kada primatelji dijele ovaj bedž na društvenim mrežama.

PUT /badges/{badgeId}/share-text

Parametri

Parametar	Tip	Obavezno	Opis
badgeId	string	Da	ID bedža (parametar putanje)
text	string	Da	Tekst za dijeljenje (HTML nije dopušten)

Primjer

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

Odgovor

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

---

Brisanje bedža

Obrišite bedž. Bedž ne smije imati nijednu vjerodajnicu.

DELETE /badges/{badgeId}

Primjer

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

Odgovor

Vraća običan string potvrde:

"badge has been deleted"

Pogreške

• 400 — bedž još ima izdane vjerodajnice: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — bedž nije pronađen