Todistukset-API

Luo ja hallitse todistuksia (assertions) — tietyille vastaanottajille myönnettyjä merkkejä.

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

Luo todistus

Myönnä merkki vastaanottajalle.

Jos sinun täytyy myöntää satoja tai tuhansia todistuksia kerralla yhden API-kutsun sijaan henkilöä kohden, käytä käyttöliittymän Massatodistukset-toimintoa, joka hyväksyy CSV-latauksen.

POST /awards

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Myönnettävän merkin ID
recipient	object	Kyllä	Vastaanottajan tiedot (katso alla)
recipient.name	string	Kyllä	Vastaanottajan koko nimi (vähintään 5 merkkiä)
recipient.email	string	Kyllä	Vastaanottajan sähköpostiosoite
issuedOn	string	Kyllä	Myöntöpäivä ISO 8601 -muodossa (esim. 2025-01-15)
expires	string	Ei	Voimassaolon päättymispäivä ISO 8601 -muodossa

Esimerkki

curl -X POST https://api.badges.ninja/awards \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15"
    }
  }'

Vastaus

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Huomioita

• Vähentää yhden todistuksen vuosittaisesta todistuskiintiöstäsi (Free: 1,200/vuosi, Starter: 12,000/vuosi, Pro: 120,000/vuosi). Kiintiö on joustava vuosittainen käyttövara — käytä sitä milloin haluat vuoden aikana, myös purskeittain — ja se nollautuu tilisi rekisteröitymisen vuosipäivänä. Laskutus pysyy kuukausittaisena; vain todistuskiintiö on vuosittainen. Katso lisätiedot kohdasta Paketit ja laskutus.

---

Listaa todistukset

Hae todistukset valinnaisella suodatuksella ja sivutuksella.

GET /awards

Kyselyparametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
filter	JSON string	Ei	Suodatinobjekti (katso alla)
lastEvaluatedKey	string	Ei	Edellisen vastauksen sivutustunniste

Suodatinobjekti

filter-parametri hyväksyy JSON-merkkijonon, jossa on seuraavat kentät:

Kenttä	Tyyppi	Kuvaus
badgeId	string	Suodata merkin ID:n mukaan.
search	string	Osamerkkijono, jota haetaan vastaanottajien nimistä tai sähköpostiosoitteista (katso searchField).
searchField	string	Joko name (oletus) tai email — mistä sarakkeesta haetaan.

Sivutus lastEvaluatedKey-arvolla toimii suodattimien kanssa ja ilman. Sivukoko on 50.

Esimerkki — listaa kaikki todistukset

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

Esimerkki — suodata merkin mukaan

curl -X GET "https://api.badges.ninja/awards?filter=%7B%22badgeId%22%3A%22b1c2d3e4%22%7D" \
  -H "X-Api-Key: bws_your_api_key_here"

Vastaus

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Jos vastauksessa on lastEvaluatedKey, tuloksia on lisää. Välitä se kyselyparametrina seuraavassa pyynnössä saadaksesi seuraavan sivun.

---

Lähetä todistussähköposti

Lähetä vastaanottajalle sähköposti-ilmoitus hänen todistuksestaan.

POST /awards/{awardId}/send

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Todistuksen ID (polkuparametri ja runko)
email	string	Kyllä	Vastaanottajan sähköpostiosoite

Esimerkki

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "email": "jane@example.com"
    }
  }'

Vastaus

Palauttaa pelkän vahvistusmerkkijonon:

"email sent"

---

Jaa todistus

Jaa todistus usealle vastaanottajalle sähköpostilla.

POST /awards/{awardId}/share

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Todistuksen ID (polkuparametri ja runko)
recipients	string	Kyllä	Pilkuilla erotettu luettelo sähköpostiosoitteista
subject	string	Kyllä	Sähköpostin aihe
message	string	Kyllä	Sähköpostin viestin sisältö

Esimerkki

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/share \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "recipients": "manager@example.com,hr@example.com",
      "subject": "Check out my new badge!",
      "message": "I just earned the JavaScript Fundamentals badge."
    }
  }'

Vastaus

Palauttaa pelkän vahvistusmerkkijonon:

"email sent"

---

Peruuta todistus

Peruuta myöntämäsi todistus. Isännöity Open Badges v2.0 -assertion merkitään revoked: true (valinnaisella syyllä), jotta kaikki varmentajat näkevät, ettei merkki ole enää voimassa. Todistuksen tietue säilytetään auditointia varten, eikä krediittiä palauteta.

Peruutus välittyy myös todistuksen Open Badges 3.0 Verifiable Credentialiin: todistuksen bitti käännetään W3C Bitstring Status Listissä, johon VC:n credentialStatus viittaa, joten myös VC-lompakot havaitsevat sen. Katso Peruutus (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Todistuksen ID (polkuparametri)
reason	string	Ei	Peruutuksen syy. Katkaistaan 500 merkkiin.
notify	boolean	Ei	Kun true, vastaanottajalle lähetetään sähköposti todistuksen peruutuksesta. Oletus on false.

Esimerkki

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Vastaus

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Jo peruutetun todistuksen peruuttaminen on idempotenttia — se palauttaa saman vastauksen lähettämättä ilmoitusta uudelleen.

Peruuta massana

Jos haluat peruuttaa monta todistusta kerralla, käytä kestävää massapäätepistettä arvolla action: "revoke" sen sijaan, että kutsuisit tätä päätepistettä todistuskohtaisesti:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

Se palauttaa { "jobId", "total" }; työ peruuttaa jokaisen ID:n palvelinpuolella (ohittaen jo peruutetut) ja on jatkettavissa. Jo peruutetut ja olemattomat ID:t raportoidaan ohitettuina.

---

Poista todistus

Poista myöntämäsi todistus pysyvästi. Toisin kuin peruutus, tämä poistaa tietueen kokonaan, ja julkinen todistussivu palauttaa 404. Käytä tätä aitoihin virheisiin (esim. myönnetty väärälle henkilölle); suosi oikeissa todistuksissa peruutusta, jotta assertion pysyy varmennettavissa peruutettuna. Krediittiä ei palauteta.

DELETE /awards/{awardId}

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Todistuksen ID (polkuparametri)

Esimerkki

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Vastaus

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

Lataa PDF-todistus

Luo todistukselle tulostusvalmis A4-PDF-todistus.

GET /certify-badge/award/{awardGuid}/pdf

Todennusta ei vaadita — päätepiste on julkinen, jotta vastaanottajat voivat ladata oman todistuksensa.

Esimerkki

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

Vastaus on binäärinen PDF, jossa on otsake Content-Type: application/pdf.

---

Seuraa todistuksen tapahtumaa

Tallenna sitoutumistapahtuma. Julkinen todistussivu käyttää tätä sitoutumistilastojen täyttämiseen. Todennusta ei vaadita.

POST /certify-badge/award/{awardGuid}/event

Parametrit

Tämä päätepiste lukee runkonsa suoraan (ilman parameters-ümbrist).

Parametri	Tyyppi	Pakollinen	Kuvaus
event	string	Kyllä	Yksi arvoista view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ei	Kun event=share, sosiaalinen verkosto: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Kaksoiskirjausten esto IP-osoitteittain: sama tapahtuma samasta IP-osoitteesta lasketaan kerran 24 tunnissa.

Esimerkki

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Vastaus

{
  "ok": true
}

---

Hae todistuksen tilastot

Hae todistuksen kumulatiiviset sitoutumislaskurit.

GET /certify-badge/award/{awardGuid}/stats

Todennusta ei vaadita.

Vastaus

Laskurit palautetaan raakatapahtumatyypin mukaan. totals sisältää kunkin tapahtuman kokonaismäärän; networks erittelee verkostokohtaisen jaon tapahtumille, joilla on network (tällä hetkellä share). Tapahtumat, joista ei ole kirjattu toimintaa, puuttuvat yksinkertaisesti.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}