Referenca API-ja za značke: ustvarjanje, preverjanje in pridobivanje značk

Upravljajte predloge značk — poverilnice, ki jih izdajate prejemnikom.

Če želite to značko izdati številnim prejemnikom naenkrat prek nalaganja CSV namesto prek API-ja, glejte Množične poverilnice.

Vse končne točke zahtevajo preverjanje pristnosti prek glave X-Api-Key. Glejte Preverjanje pristnosti.

Ustvarjanje značke

Ustvarite novo značko pri preverjenem izdajatelju.

POST /badges

Parametri

Parameter	Tip	Obvezno	Opis
name	string	Da	Naslov značke
description	string	Da	Kaj značka predstavlja
criteria	string	Da	Kaj je prejemnik naredil, da je prislužil to značko
image	string	Da	Slika, kodirana v Base64 (PNG ali JPG)
issuerId	string	Da	ID preverjenega izdajatelja
shareText	string	Ne	Privzeto besedilo za deljenje te značke na družbenih omrežjih. Podpira označbe mesta , in . Če je izpuščeno, se uporabi vgrajeno privzeto besedilo.
designJson	string	Ne	Serializiran dokument oblikovalnika značk, shranjen, da je mogoče značko pozneje urejati plast za plastjo.

Primer

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

Opombe

• Izdajatelj mora biti preverjen, preden lahko ustvarite značke.
• Slika je shranjena v Amazon S3 in se streže prek našega globalnega CDN pod nespremenljivim URL-jem, naslovljenim po vsebini.
• Ko razred značke obstaja, ga izdajte prejemnikom z API-jem za poverilnice.

---

Seznam značk

Pridobite vse značke, ki ste jih ustvarili.

GET /badges

Primer

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

---

Pridobitev značke

Pridobite posamezno značko, vključno z njenim besedilom za deljenje in serializiranim dokumentom oblikovalnika značk (designJson). To je končna točka, ki jo modalno okno Urejanje značke uporablja za ponovno vzpostavitev posameznih plasti; končna točka seznama izpušča designJson, da so odgovori kompaktni.

GET /badges/{badgeId}

Parametri

Parameter	Tip	Obvezno	Opis
badgeId	string	Da	ID značke (parameter poti)

Primer

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

Besedilo za deljenje je vedno vključeno. Lažja različica seznama GET /badges?badgeId={id} vrne isti dokument brez designJson, besedilo za deljenje pa vključi le, če jo pokličete z includeShareText=true.

---

Posodobitev značke

Posodobite obstoječo značko. Spremenijo se samo polja, ki jih navedete.

PUT /badges/{badgeId}

Parametri

Parameter	Tip	Obvezno	Opis
badgeId	string	Da	ID značke (parameter poti)
name	string	Ne	Nov naslov značke
description	string	Ne	Nov opis
criteria	string	Ne	Novi kriteriji
image	string	Ne	Nova slika, kodirana v Base64
designJson	string	Ne	Nov serializiran dokument oblikovalnika značk.

Primer

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
}

---

Posodobitev besedila za deljenje

Nastavite besedilo po meri, ki se prikaže, ko prejemniki to značko delijo na družbenih omrežjih.

PUT /badges/{badgeId}/share-text

Parametri

Parameter	Tip	Obvezno	Opis
badgeId	string	Da	ID značke (parameter poti)
text	string	Da	Besedilo za deljenje (HTML ni dovoljen)

Primer

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 značke

Izbrišite značko. Značka ne sme imeti nobenih poverilnic.

DELETE /badges/{badgeId}

Primer

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

Odgovor

Vrne preprost potrditveni niz:

"badge has been deleted"

Napake

• 400 — značka ima še vedno izdane poverilnice: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — značka ni bila najdena