Myöntäjien API

Hallitse merkkien myöntäjiä — organisaatioita tai yksityishenkilöitä, jotka myöntävät merkkejä.

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

Luo myöntäjä

Luo uusi merkkien myöntäjä.

POST /issuers

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
name	string	Kyllä	Organisaation nimi (vähintään 3 merkkiä)
url	string	Kyllä	Organisaation verkkosivusto (oltava kelvollinen HTTP/HTTPS-URL)
email	string	Kyllä	Myöntäjän yhteyssähköposti
logo	string	Ei	Base64-koodattu kuva (PNG tai JPG)
linkedinOrganizationId	string	Ei	LinkedInin yrityssivun numeerinen tunnus. Kun tämä on asetettu, jokaisella tämän myöntäjän julkisella todistussivulla näkyy Add to LinkedIn Profile -painike.

Esimerkki

curl -X POST https://api.badges.ninja/issuers \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com"
    }
  }'

Vastaus

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Huomautukset

• Lasketaan mukaan tilauksesi myöntäjärajaan (Free: 2, Starter: 5, Pro: 10). Kiintiötä ei vähennetä.
• Jos myöntäjän sähköposti vastaa tilisi sähköpostia, myöntäjä varmennetaan automaattisesti.
• Jos sähköposti on eri, myöntäjän sähköpostiin lähetetään varmennusviesti.
• Kun myöntäjä on määritetty, aloita todistusten myöntäminen kyseiselle myöntäjälle Todistus-API:lla.

---

Luettele myöntäjät

Hae kaikki luomasi myöntäjät.

GET /issuers

Esimerkki

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

Vastaus

{
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
      "name": "Acme Academy",
      "url": "https://acme.example.com",
      "email": "badges@acme.example.com",
      "verified": true,
      "timestamp": 1736937000000
    }
  ]
}

timestamp on Unix-epoch millisekunteina. Kun myöntäjiä on enemmän kuin yhdelle sivulle mahtuu, palautetaan sivutusta varten myös lastEvaluatedKey.

---

Varmenna myöntäjä

Varmenna myöntäjä sen sähköpostiin lähetetyllä varmennuskoodilla.

POST /issuers/{issuerId}/verify

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
issuerId	string	Kyllä	Myöntäjän tunnus (polkuparametri)
code	string	Kyllä	Sähköpostin varmennuskoodi

Esimerkki

curl -X POST https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "ABC123"
    }
  }'

Vastaus

Pelkkä merkkijono:

"issuer has been verified"

---

Poista myöntäjä

Poista myöntäjä. Myöntäjään ei saa olla liitettynä merkkejä.

DELETE /issuers/{issuerId}

Esimerkki

curl -X DELETE https://api.badges.ninja/issuers/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: bws_your_api_key_here"

Vastaus

Pelkkä merkkijono:

"issuer has been deleted"

Virheet

• 400 — myöntäjään on yhä liitetty merkkejä: issuer has {n} badge(s) linked — delete the badges first. Poisto estyy vain liitettyjen merkkien vuoksi — todistukset eivät estä sitä.
• 404 — myöntäjää ei löytynyt

---

Päivitä myöntäjä

Päivitä myöntäjän kenttiä. Vain varmentamattomia myöntäjiä voi muokata — kun myöntäjä on varmennettu, tämä päätepiste palauttaa 400 verified issuers cannot be edited todistusten vakauden säilyttämiseksi. Myöntäjän muokkaus luo uuden varmennuskoodin: jos email vastaa tilisi sähköpostia, myöntäjä varmennetaan automaattisesti uudelleen, muuten kyseiseen osoitteeseen lähetetään uusi varmennusviesti.

PUT /issuers/{issuerId}

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
issuerId	string	Kyllä	Myöntäjän tunnus (polkuparametri)
name	string	Ei	Uusi nimi
url	string	Ei	Uusi URL
email	string	Ei	Uusi sähköposti (lähettää uuden varmennusviestin, ellei se vastaa tilisi sähköpostia)
logo	string	Ei	Uusi base64-koodattu logo
linkedinOrganizationId	string	Ei	Uusi LinkedIn-organisaation tunnus (tai tyhjä merkkijono tyhjentämiseen)

Vastaus

{
  "issuerId": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "updated": true
}

Virheet

• 400 — verified issuers cannot be edited (myöntäjä on jo varmennettu)
• 400 — not authorized (myöntäjä kuuluu toiselle tilille)
• 404 — myöntäjää ei löytynyt