Badges API nuoroda: ženklelių kūrimas, patikrinimas ir gavimas

Valdykite ženklelių šablonus – pažymėjimus, kuriuos išduodate gavėjams.

Jei šį ženklelį norite išduoti daugeliui gavėjų iš karto įkeldami CSV, o ne per API, žr. Masiniai pažymėjimai.

Visi galutiniai taškai reikalauja autentikavimo per antraštę X-Api-Key. Žr. Autentikavimas.

Sukurti ženklelį

Sukurkite naują ženklelį pagal patvirtintą išdavėją.

POST /badges

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
name	string	Taip	Ženklelio pavadinimas
description	string	Taip	Ką ženklelis reiškia
criteria	string	Taip	Ką gavėjas padarė, kad gautų šį ženklelį
image	string	Taip	Base64 užkoduotas paveikslėlis (PNG arba JPG)
issuerId	string	Taip	Patvirtinto išdavėjo ID
shareText	string	Ne	Numatytasis šio ženklelio dalijimosi socialiniuose tinkluose tekstas. Palaiko vietos žymes , ir . Jei nenurodyta, naudojama integruota numatytoji reikšmė.
designJson	string	Ne	Serializuotas ženklelių dizainerio dokumentas, išsaugomas, kad ženklelį vėliau būtų galima redaguoti sluoksnis po sluoksnio.

Pavyzdys

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

Atsakymas

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

Pastabos

• Prieš kuriant ženklelius išdavėjas turi būti patvirtintas.
• Paveikslėlis saugomas Amazon S3 ir pateikiamas per mūsų pasaulinį CDN nekeičiamu, pagal turinį adresuojamu URL.
• Kai ženklelio klasė sukurta, išduokite ją gavėjams naudodami Pažymėjimų API.

---

Išvardyti ženklelius

Gaukite visus jūsų sukurtus ženklelius.

GET /badges

Pavyzdys

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

Atsakymas

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

---

Gauti ženklelį

Gaukite vieną ženklelį kartu su jo dalijimosi tekstu ir serializuotu ženklelių dizainerio dokumentu (designJson). Šį galutinį tašką naudoja ženklelio redagavimo langas, kad atkurtų atskirus sluoksnius; sąrašo galutinis taškas designJson praleidžia, kad atsakymai būtų lengvi.

GET /badges/{badgeId}

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Ženklelio ID (kelio parametras)

Pavyzdys

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

Atsakymas

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

Dalijimosi tekstas įtraukiamas visada. Lengvesnis sąrašo variantas GET /badges?badgeId={id} grąžina tą patį dokumentą be designJson ir dalijimosi tekstą įtraukia tik kviečiant su includeShareText=true.

---

Atnaujinti ženklelį

Atnaujinkite esamą ženklelį. Pakeičiami tik jūsų pateikti laukai.

PUT /badges/{badgeId}

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Ženklelio ID (kelio parametras)
name	string	Ne	Naujas ženklelio pavadinimas
description	string	Ne	Naujas aprašymas
criteria	string	Ne	Nauji kriterijai
image	string	Ne	Naujas Base64 užkoduotas paveikslėlis
designJson	string	Ne	Naujas serializuotas ženklelių dizainerio dokumentas.

Pavyzdys

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

Atsakymas

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

---

Atnaujinti dalijimosi tekstą

Nustatykite pasirinktinį tekstą, rodomą gavėjams dalijantis šiuo ženklelio socialinėje žiniasklaidoje.

PUT /badges/{badgeId}/share-text

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Ženklelio ID (kelio parametras)
text	string	Taip	Dalijimosi tekstas (HTML neleidžiamas)

Pavyzdys

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

Atsakymas

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

---

Ištrinti ženklelį

Ištrinkite ženklelį. Ženklelis neturi turėti pažymėjimų.

DELETE /badges/{badgeId}

Pavyzdys

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

Atsakymas

Grąžinama paprasta patvirtinimo eilutė:

"badge has been deleted"

Klaidos

• 400 — ženklelis vis dar turi išduotų pažymėjimų: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — ženklelis nerastas