Badges API referencia: jelvények létrehozása, ellenőrzése és lekérdezése

Kezeld a jelvénysablonokat — azokat a hitelesítő adatokat, amelyeket a címzetteknek bocsátasz ki.

Ha ezt a jelvényt az API helyett CSV-feltöltéssel szeretnéd egyszerre sok címzettnek kibocsátani, lásd a Bulk Credentials részt.

Minden végponthoz hitelesítés szükséges az X-Api-Key fejlécen keresztül. Lásd: Hitelesítés.

Jelvény létrehozása

Hozz létre új jelvényt egy ellenőrzött kibocsátó alatt.

POST /badges

Paraméterek

Paraméter	Típus	Kötelező	Leírás
name	string	Igen	A jelvény címe
description	string	Igen	Mit jelent a jelvény
criteria	string	Igen	Mit tett a címzett a jelvény megszerzéséért
image	string	Igen	Base64 kódolású kép (PNG vagy JPG)
issuerId	string	Igen	Az ellenőrzött kibocsátó azonosítója
shareText	string	Nem	A jelvény alapértelmezett közösségimédia-megosztási szövege. Támogatja a , és helyőrzőket. Ha kihagyod, egy beépített alapértelmezett szöveg lép életbe.
designJson	string	Nem	A jelvénytervező szerializált dokumentuma, eltárolva, hogy a jelvény később rétegenként újra szerkeszthető legyen.

Példa

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

Válasz

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

Megjegyzések

• A jelvények létrehozása előtt a kibocsátónak ellenőrzöttnek kell lennie.
• A képet az Amazon S3 tárolja, és globális CDN-ünkön keresztül, megváltoztathatatlan, tartalom alapján címzett URL alatt szolgáljuk ki.
• Miután a jelvényosztály létezik, bocsásd ki a címzetteknek a Credentials API segítségével.

---

Jelvények listázása

Kérd le az összes általad létrehozott jelvényt.

GET /badges

Példa

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

Válasz

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

---

Jelvény lekérése

Kérj le egyetlen jelvényt a megosztási szövegével és a jelvénytervező szerializált dokumentumával (designJson) együtt. Az Edit Badge modális ablak ezt a végpontot használja az egyes rétegek visszatöltéséhez; a lista végpont kihagyja a designJson mezőt, hogy a válaszok karcsúak maradjanak.

GET /badges/{badgeId}

Paraméterek

Paraméter	Típus	Kötelező	Leírás
badgeId	string	Igen	A jelvény azonosítója (útvonalparaméter)

Példa

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

Válasz

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

A megosztási szöveg mindig szerepel a válaszban. A könnyebb GET /badges?badgeId={id} listaváltozat ugyanezt a dokumentumot adja vissza designJson nélkül, és a megosztási szöveget csak includeShareText=true paraméterrel hívva tartalmazza.

---

Jelvény frissítése

Frissíts egy meglévő jelvényt. Csak az általad megadott mezők változnak.

PUT /badges/{badgeId}

Paraméterek

Paraméter	Típus	Kötelező	Leírás
badgeId	string	Igen	A jelvény azonosítója (útvonalparaméter)
name	string	Nem	A jelvény új címe
description	string	Nem	Új leírás
criteria	string	Nem	Új kritériumok
image	string	Nem	Új, Base64 kódolású kép
designJson	string	Nem	A jelvénytervező új szerializált dokumentuma.

Példa

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

Válasz

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

---

Megosztási szöveg frissítése

Állítsd be az egyéni szöveget, amely akkor jelenik meg, amikor a címzettek megosztják ezt a jelvényt a közösségi médiában.

PUT /badges/{badgeId}/share-text

Paraméterek

Paraméter	Típus	Kötelező	Leírás
badgeId	string	Igen	A jelvény azonosítója (útvonalparaméter)
text	string	Igen	Megosztási szöveg (HTML nem engedélyezett)

Példa

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

Válasz

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

---

Jelvény törlése

Törölj egy jelvényt. A jelvényhez nem tartozhat hitelesítő adat.

DELETE /badges/{badgeId}

Példa

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

Válasz

Egyszerű megerősítő karakterláncot ad vissza:

"badge has been deleted"

Hibák

• 400 — a jelvényhez még tartoznak kibocsátott hitelesítő adatok: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — a jelvény nem található