Tunnistuste API

Loo ja halda tunnistusi (assertions) — konkreetsetele saajatele välja antud märke.

Kõik lõpp-punktid nõuavad autentimist päisega X-Api-Key. Vaata Autentimine.

Loo tunnistus

Anna märk saajale välja.

Kui pead korraga välja andma sadadele või tuhandetele saajatele, mitte ühe API-päringuga inimese kohta, kasuta kasutajaliidese funktsiooni Hulgitunnistused, mis aktsepteerib CSV-faili üleslaadimist.

POST /awards

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
badgeId	string	Jah	Väljaantava märgi ID
recipient	object	Jah	Saaja andmed (vaata allpool)
recipient.name	string	Jah	Saaja täisnimi (vähemalt 5 tähemärki)
recipient.email	string	Jah	Saaja e-posti aadress
issuedOn	string	Jah	Väljaandmise kuupäev ISO 8601 formaadis (nt 2025-01-15)
expires	string	Ei	Aegumiskuupäev ISO 8601 formaadis

Näide

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

Vastus

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

Märkused

• Arvestatakse ühe tunnistusena sinu aastasest tunnistuste mahust (Free: 1,200/aastas, Starter: 12,000/aastas, Pro: 120,000/aastas). Maht on paindlik aastane limiit — kasuta seda millal tahes aasta jooksul, ka hoogudena — ning see lähtestub sinu konto registreerimise aastapäeval. Arveldus jääb kuupõhiseks; ainult tunnistuste kvoot on aastane. Üksikasjad vaata Paketid ja arveldus.

---

Loetle tunnistused

Too tunnistused valikulise filtreerimise ja lehitsemisega.

GET /awards

Päringuparameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
filter	JSON string	Ei	Filtriobjekt (vaata allpool)
lastEvaluatedKey	string	Ei	Eelmise vastuse lehitsemismärk

Filtriobjekt

Parameeter filter aktsepteerib JSON-stringi järgmiste väljadega:

Väli	Tüüp	Kirjeldus
badgeId	string	Filtreeri märgi ID järgi.
search	string	Alamsõne, mida otsida saajate nimedest või e-posti aadressidest (vaata searchField).
searchField	string	Kas name (vaikimisi) või email — millisest veerust otsida.

Lehitsemine märgiga lastEvaluatedKey töötab nii filtritega kui ilma. Lehe suurus on 50.

Näide — loetle kõik tunnistused

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

Näide — filtreeri märgi järgi

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"

Vastus

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

Kui vastuses on lastEvaluatedKey, on veel tulemusi. Järgmise lehe saamiseks edasta see järgmises päringus päringuparameetrina.

---

Saada tunnistuse e-kiri

Saada saajale tema tunnistuse kohta e-posti teavitus.

POST /awards/{awardId}/send

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
awardId	string	Jah	Tunnistuse ID (teeparameeter ja keha)
email	string	Jah	Saaja e-posti aadress

Näide

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

Vastus

Tagastab lihtsa kinnitusstringi:

"email sent"

---

Jaga tunnistust

Jaga tunnistust e-posti teel mitme saajaga.

POST /awards/{awardId}/share

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
awardId	string	Jah	Tunnistuse ID (teeparameeter ja keha)
recipients	string	Jah	Komaga eraldatud e-posti aadresside loend
subject	string	Jah	E-kirja teemarida
message	string	Jah	E-kirja sõnumi sisu

Näide

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

Vastus

Tagastab lihtsa kinnitusstringi:

"email sent"

---

Tühista tunnistus

Tühista sinu välja antud tunnistus. Majutatud Open Badges v2.0 assertion märgitakse revoked: true (valikulise põhjusega), nii et iga kinnitaja näeb, et märk ei kehti enam. Tunnistuse kirje säilitatakse auditeerimiseks ja krediiti ei tagastata.

Tühistamine kandub edasi ka tunnistuse Open Badges 3.0 Verifiable Credentialile: tunnistuse bitt pööratakse ümber W3C Bitstring Status Listis, millele viitab VC väli credentialStatus, nii et ka VC-rahakotid märkavad seda. Vaata Tühistamine (Bitstring Status List).

POST /awards/{awardId}/revoke

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
awardId	string	Jah	Tunnistuse ID (teeparameeter)
reason	string	Ei	Tühistamise põhjus. Lühendatakse 500 tähemärgini.
notify	boolean	Ei	Kui true, saadetakse saajale e-kiri tema tunnistuse tühistamise kohta. Vaikimisi false.

Näide

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

Vastus

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

Juba tühistatud tunnistuse tühistamine on idempotentne — see tagastab sama vastuse ilma teavitust uuesti saatmata.

Tühista hulgi

Paljude tunnistuste korraga tühistamiseks kasuta vastupidavat hulgilõpp-punkti koos action: "revoke", selle asemel et kutsuda seda lõpp-punkti iga tunnistuse kohta eraldi:

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

See tagastab { "jobId", "total" }; töö tühistab iga ID serveripoolselt (jättes juba tühistatud vahele) ja on jätkatav. Juba tühistatud ja olematud ID-d raporteeritakse vahelejäetutena.

---

Kustuta tunnistus

Kustuta sinu välja antud tunnistus jäädavalt. Erinevalt tühistamisest eemaldab see kirje täielikult ja avalik tunnistuse leht tagastab 404. Kasuta seda päris vigade korral (nt vale inimesele välja antud); päris tunnistuste puhul eelista tühistamist, et assertion jääks tühistatuna kinnitatavaks. Krediiti ei tagastata.

DELETE /awards/{awardId}

Parameetrid

Parameeter	Tüüp	Kohustuslik	Kirjeldus
awardId	string	Jah	Tunnistuse ID (teeparameeter)

Näide

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

Vastus

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

---

Laadi alla PDF-sertifikaat

Genereeri tunnistuse jaoks prindivalmis A4 PDF-sertifikaat.

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

Autentimist ei nõuta — see lõpp-punkt on avalik, et saajad saaksid oma sertifikaadi ise alla laadida.

Näide

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

Vastus on binaarne PDF päisega Content-Type: application/pdf.

---

Jälgi tunnistuse sündmust

Salvesta kaasamissündmus. Kasutab avalik tunnistuse leht kaasamisstatistika täitmiseks. Autentimist ei nõuta.

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

Parameetrid

See lõpp-punkt loeb oma keha otse (ilma parameters ümbriseta).

Parameeter	Tüüp	Kohustuslik	Kirjeldus
event	string	Jah	Üks väärtustest view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ei	Kui event=share, sotsiaalvõrgustik: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Dubleerimise summutamine IP kohta: sama IP-lt pärinev sama sündmus loetakse 24 tunni jooksul ühe korra.

Näide

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

Vastus

{
  "ok": true
}

---

Hangi tunnistuse statistika

Too tunnistuse kumulatiivsed kaasamisloendurid.

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

Autentimist ei nõuta.

Vastus

Loendurid tagastatakse sündmuse algtüübi järgi. totals sisaldab iga sündmuse koguarvu; networks näitab sündmuste puhul, millel on network (praegu share), jaotust võrgustike kaupa. Sündmused, mille kohta tegevust pole, puuduvad lihtsalt.

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