Merkki-API:n viite: luo, varmenna ja hae merkkejä

Hallitse merkkipohjia — todistuksia, joita myönnät vastaanottajille.

Jos haluat myöntää tämän merkin kerralla usealle vastaanottajalle CSV-tiedoston latauksella API:n sijaan, katso Massatodistukset.

Kaikki päätepisteet vaativat todennuksen X-Api-Key-otsikon kautta. Katso Todennus.

Luo merkki

Luo uusi merkki varmennetun myöntäjän alle.

POST /badges

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
name	string	Kyllä	Merkin otsikko
description	string	Kyllä	Mitä merkki edustaa
criteria	string	Kyllä	Mitä vastaanottaja teki ansaitakseen tämän merkin
image	string	Kyllä	Base64-koodattu kuva (PNG tai JPG)
issuerId	string	Kyllä	Varmennetun myöntäjän tunniste
shareText	string	Ei	Tämän merkin oletusarvoinen sosiaalisen jaon teksti. Tukee paikkamerkkejä , ja . Jos tekstiä ei anneta, käytetään sisäänrakennettua oletusta.
designJson	string	Ei	Sarjallistettu merkkisuunnittelijan dokumentti, joka tallennetaan, jotta merkkiä voi myöhemmin muokata kerros kerrallaan.

Esimerkki

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

Vastaus

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

Huomautuksia

• Myöntäjän on oltava varmennettu, ennen kuin merkkejä voi luoda.
• Kuva tallennetaan Amazon S3:een ja jaellaan maailmanlaajuisen CDN-verkkomme kautta muuttumattomasta, sisältöpohjaisesta URL-osoitteesta.
• Kun merkkiluokka on olemassa, myönnä se vastaanottajille Todistukset-API:n avulla.

---

Listaa merkit

Hae kaikki luomasi merkit.

GET /badges

Esimerkki

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

Vastaus

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

---

Hae merkki

Hae yksittäinen merkki sekä sen jakoteksti ja sarjallistettu merkkisuunnittelijan dokumentti (designJson). Tätä päätepistettä Muokkaa merkkiä -ikkuna käyttää yksittäisten kerrosten palauttamiseen; luettelopäätepiste jättää designJson-kentän pois, jotta vastaukset pysyvät kevyinä.

GET /badges/{badgeId}

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Merkin tunniste (polkuparametri)

Esimerkki

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

Vastaus

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

Jakoteksti sisältyy aina. Kevyempi luettelovariantti GET /badges?badgeId={id} palauttaa saman dokumentin ilman designJson-kenttää ja sisällyttää jakotekstin vain, kun sitä kutsutaan parametrilla includeShareText=true.

---

Päivitä merkki

Päivitä olemassa oleva merkki. Vain antamasi kentät muuttuvat.

PUT /badges/{badgeId}

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Merkin tunniste (polkuparametri)
name	string	Ei	Merkin uusi otsikko
description	string	Ei	Uusi kuvaus
criteria	string	Ei	Uudet kriteerit
image	string	Ei	Uusi Base64-koodattu kuva
designJson	string	Ei	Uusi sarjallistettu merkkisuunnittelijan dokumentti.

Esimerkki

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

Vastaus

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

---

Päivitä jakoteksti

Aseta mukautettu teksti, joka näytetään, kun vastaanottajat jakavat tämän merkin sosiaalisessa mediassa.

PUT /badges/{badgeId}/share-text

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Merkin tunniste (polkuparametri)
text	string	Kyllä	Jakoteksti (HTML ei sallittu)

Esimerkki

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

Vastaus

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

---

Poista merkki

Poista merkki. Merkillä ei saa olla todistuksia.

DELETE /badges/{badgeId}

Esimerkki

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

Vastaus

Palauttaa pelkän vahvistusmerkkijonon:

"badge has been deleted"

Virheet

• 400 — merkillä on edelleen myönnettyjä todistuksia: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — merkkiä ei löytynyt