Referenční příručka API odznaků: vytváření, ověřování a načítání odznaků

Spravujte šablony odznaků — pověření, která vydáváte příjemcům.

Pokud chcete tento odznak vydat hromadně mnoha příjemcům nahráním CSV místo přes API, viz Hromadná pověření.

Všechny endpointy vyžadují autentizaci pomocí hlavičky X-Api-Key. Viz Autentizace.

Vytvořit odznak

Vytvořte nový odznak u ověřeného vydavatele.

POST /badges

Parametry

Parametr	Typ	Povinný	Popis
name	string	Ano	Název odznaku
description	string	Ano	Co odznak představuje
criteria	string	Ano	Co příjemce udělal pro získání tohoto odznaku
image	string	Ano	Obrázek kódovaný v Base64 (PNG nebo JPG)
issuerId	string	Ano	ID ověřeného vydavatele
shareText	string	Ne	Výchozí text ke sdílení tohoto odznaku na sociálních sítích. Podporuje zástupné symboly , a . Pokud je vynechán, použije se vestavěná výchozí hodnota.
designJson	string	Ne	Serializovaný dokument návrháře odznaků, uložený, aby bylo možné odznak později upravovat po vrstvách.

Pří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"
    }
  }'

Odpověď

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

Poznámky

• Před vytvářením odznaků musí být vydavatel ověřen.
• Obrázek je uložen na Amazon S3 a poskytován přes naši globální CDN pod nezměnitelnou URL adresou odvozenou od obsahu.
• Jakmile třída odznaku existuje, vydávejte ji příjemcům pomocí API pověření.

---

Seznam odznaků

Získejte všechny odznaky, které jste vytvořili.

GET /badges

Příklad

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

Odpověď

[
  {
    "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ískat odznak

Získejte jeden odznak včetně jeho textu ke sdílení a serializovaného dokumentu návrháře odznaků (designJson). Tento endpoint používá dialog Upravit odznak k obnovení jednotlivých vrstev; endpoint se seznamem designJson vynechává, aby odpovědi zůstaly úsporné.

GET /badges/{badgeId}

Parametry

Parametr	Typ	Povinný	Popis
badgeId	string	Ano	ID odznaku (parametr cesty)

Příklad

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

Odpověď

{
  "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 ke sdílení je zahrnut vždy. Lehčí varianta se seznamem GET /badges?badgeId={id} vrací stejný dokument bez designJson a text ke sdílení zahrnuje, jen pokud je volána s includeShareText=true.

---

Aktualizovat odznak

Aktualizujte existující odznak. Změní se pouze pole, která uvedete.

PUT /badges/{badgeId}

Parametry

Parametr	Typ	Povinný	Popis
badgeId	string	Ano	ID odznaku (parametr cesty)
name	string	Ne	Nový název odznaku
description	string	Ne	Nový popis
criteria	string	Ne	Nová kritéria
image	string	Ne	Nový obrázek kódovaný v Base64
designJson	string	Ne	Nový serializovaný dokument návrháře odznaků.

Pří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"
    }
  }'

Odpověď

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

---

Aktualizovat text ke sdílení

Nastavte vlastní text zobrazený, když příjemci sdílejí tento odznak na sociálních sítích.

PUT /badges/{badgeId}/share-text

Parametry

Parametr	Typ	Povinný	Popis
badgeId	string	Ano	ID odznaku (parametr cesty)
text	string	Ano	Text ke sdílení (HTML není povoleno)

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

Odpověď

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

---

Smazat odznak

Smažte odznak. Odznak nesmí mít žádná pověření.

DELETE /badges/{badgeId}

Příklad

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

Odpověď

Vrátí prostý potvrzovací řetězec:

"badge has been deleted"

Chyby

• 400 — odznak má stále vydaná pověření: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — odznak nenalezen