Referenčná príručka Badges API: vytváranie, overovanie a získavanie odznakov

Spravujte šablóny odznakov — osvedčenia, ktoré vydávate príjemcom.

Ak chcete tento odznak vydať naraz mnohým príjemcom cez nahratie CSV namiesto API, pozrite si Hromadné osvedčenia.

Všetky endpointy vyžadujú autentifikáciu cez hlavičku X-Api-Key. Pozri Autentifikácia.

Vytvoriť odznak

Vytvorte nový odznak pod overeným vydavateľom.

POST /badges

Parametre

Parameter	Typ	Povinný	Popis
name	string	Áno	Názov odznaku
description	string	Áno	Čo odznak predstavuje
criteria	string	Áno	Čo príjemca urobil, aby tento odznak získal
image	string	Áno	Obrázok kódovaný v Base64 (PNG alebo JPG)
issuerId	string	Áno	ID overeného vydavateľa
shareText	string	Nie	Predvolený text na zdieľanie tohto odznaku na sociálnych sieťach. Podporuje zástupné symboly , a . Ak sa vynechá, použije sa vstavaná predvolená hodnota.
designJson	string	Nie	Serializovaný dokument návrhára odznakov, uložený, aby bolo možné odznak neskôr upravovať vrstvu po vrstve.

Príklad

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

Odpoveď

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

Poznámky

• Vydavateľ musí byť pred vytváraním odznakov overený.
• Obrázok sa ukladá v Amazon S3 a poskytuje sa cez našu globálnu CDN pod nemennou URL adresou určenou podľa obsahu.
• Keď trieda odznaku existuje, vydávajte ju príjemcom pomocou API poverení.

---

Zoznam odznakov

Získajte všetky odznaky, ktoré ste vytvorili.

GET /badges

Príklad

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

Odpoveď

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

---

Získať odznak

Získajte jeden odznak vrátane textu na zdieľanie a serializovaného dokumentu návrhára odznakov (designJson). Tento endpoint používa okno Edit Badge na obnovenie jednotlivých vrstiev; endpoint so zoznamom designJson vynecháva, aby boli odpovede štíhle.

GET /badges/{badgeId}

Parametre

Parameter	Typ	Povinný	Popis
badgeId	string	Áno	ID odznaku (parameter cesty)

Príklad

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

Odpoveď

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

Text na zdieľanie je vždy zahrnutý. Ľahší variant zoznamu GET /badges?badgeId={id} vracia rovnaký dokument bez designJson a text na zdieľanie obsahuje, iba ak sa volá s includeShareText=true.

---

Aktualizovať odznak

Aktualizujte existujúci odznak. Menia sa iba polia, ktoré zadáte.

PUT /badges/{badgeId}

Parametre

Parameter	Typ	Povinný	Popis
badgeId	string	Áno	ID odznaku (parameter cesty)
name	string	Nie	Nový názov odznaku
description	string	Nie	Nový popis
criteria	string	Nie	Nové kritériá
image	string	Nie	Nový obrázok kódovaný v Base64
designJson	string	Nie	Nový serializovaný dokument návrhára odznakov.

Príklad

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

Odpoveď

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

---

Aktualizovať text na zdieľanie

Nastavte vlastný text, ktorý sa zobrazí, keď príjemcovia zdieľajú tento odznak na sociálnych sieťach.

PUT /badges/{badgeId}/share-text

Parametre

Parameter	Typ	Povinný	Popis
badgeId	string	Áno	ID odznaku (parameter cesty)
text	string	Áno	Text na zdieľanie (HTML nie je povolené)

Príklad

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

Odpoveď

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

---

Odstrániť odznak

Odstráňte odznak. Odznak nesmie mať žiadne poverenia.

DELETE /badges/{badgeId}

Príklad

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

Odpoveď

Vráti jednoduchý potvrdzujúci reťazec:

"badge has been deleted"

Chyby

• 400 — odznak má stále vydané poverenia: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — odznak sa nenašiel