API za poverilnice

Ustvarjanje in upravljanje poverilnic (assertions) — značk, izdanih določenim prejemnikom.

Vse končne točke zahtevajo preverjanje pristnosti prek glave X-Api-Key. Glejte Preverjanje pristnosti.

Ustvarjanje poverilnice

Izdajte značko prejemniku.

Želite izdati na stotine ali tisoče prejemnikov naenkrat, namesto enega klica API-ja na osebo? Uporabite funkcijo uporabniškega vmesnika Množične poverilnice, ki sprejme nalaganje CSV.

POST /awards

Parametri

Parameter	Tip	Obvezen	Opis
badgeId	string	Da	ID značke, ki jo izdajate
recipient	object	Da	Podatki o prejemniku (glejte spodaj)
recipient.name	string	Da	Polno ime prejemnika (najmanj 5 znakov)
recipient.email	string	Da	E-poštni naslov prejemnika
issuedOn	string	Da	Datum izdaje v formatu ISO 8601 (npr. 2025-01-15)
expires	string	Ne	Datum poteka v formatu ISO 8601

Primer

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

Odgovor

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

Opombe

• Šteje kot ena poverilnica v vašem letnem skladu poverilnic (Free: 1.200/leto, Starter: 12.000/leto, Pro: 120.000/leto). Sklad je prožna letna kvota — porabite jo, kadar želite, tudi v sunkih — in se ponastavi na obletnico registracije vašega računa. Obračunavanje ostaja mesečno; letna je le kvota poverilnic. Podrobnosti so v Načrti in obračunavanje.

---

Seznam poverilnic

Pridobite poverilnice z neobveznim filtriranjem in paginacijo.

GET /awards

Parametri poizvedbe

Parameter	Tip	Obvezen	Opis
filter	JSON string	Ne	Objekt filtra (glejte spodaj)
lastEvaluatedKey	string	Ne	Žeton paginacije iz prejšnjega odgovora

Objekt filtra

Parameter filter sprejme niz JSON s temi polji:

Polje	Tip	Opis
badgeId	string	Filtriranje po ID-ju značke.
search	string	Podniz za iskanje v imenih ali e-poštnih naslovih prejemnikov (glejte searchField).
searchField	string	Bodisi name (privzeto) bodisi email — kateri stolpec iskati.

Paginacija prek lastEvaluatedKey deluje s filtri ali brez njih. Velikost strani je 50.

Primer — seznam vseh poverilnic

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

Primer — filtriranje po znački

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"

Odgovor

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

Če je lastEvaluatedKey prisoten v odgovoru, obstaja še več rezultatov. Posredujte ga kot parameter poizvedbe v naslednji zahtevi, da dobite naslednjo stran.

---

Pošiljanje e-pošte o poverilnici

Prejemniku pošljite e-poštno obvestilo o njegovi poverilnici.

POST /awards/{awardId}/send

Parametri

Parameter	Tip	Obvezen	Opis
awardId	string	Da	ID podelitve (parameter poti in telo)
email	string	Da	E-poštni naslov prejemnika

Primer

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

Odgovor

Vrne preprost potrditveni niz:

"email sent"

---

Deljenje poverilnice

Poverilnico delite z več prejemniki po e-pošti.

POST /awards/{awardId}/share

Parametri

Parameter	Tip	Obvezen	Opis
awardId	string	Da	ID podelitve (parameter poti in telo)
recipients	string	Da	Z vejicami ločen seznam e-poštnih naslovov
subject	string	Da	Zadeva e-pošte
message	string	Da	Telo e-poštnega sporočila

Primer

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

Odgovor

Vrne preprost potrditveni niz:

"email sent"

---

Preklic poverilnice

Prekličite poverilnico, ki ste jo izdali. Gostovana trditev Open Badges v2.0 je označena z revoked: true (z neobveznim razlogom), tako da vsak preverjevalnik vidi, da značka ni več veljavna. Zapis poverilnice se hrani za revizijske namene, kredit pa se ne povrne.

Preklic se razširi tudi na Open Badges 3.0 Verifiable Credential poverilnice: bit podelitve se v W3C Bitstring Status List, na katero kaže credentialStatus VC-ja, preklopi, tako da preklic zaznajo tudi denarnice VC. Glejte Preklic (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametri

Parameter	Tip	Obvezen	Opis
awardId	string	Da	ID podelitve (parameter poti)
reason	string	Ne	Razlog preklica. Skrajšan na 500 znakov.
notify	boolean	Ne	Če je true, prejemniku po e-pošti sporoči, da je bila njegova poverilnica preklicana. Privzeto false.

Primer

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

Odgovor

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

Preklic že preklicane poverilnice je idempotenten — vrne enak odgovor, ne da bi znova poslal obvestilo.

Množični preklic

Za preklic več poverilnic naenkrat namesto klicanja te končne točke za vsako podelitev uporabite trajno množično končno točko z action: "revoke":

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

Vrne { "jobId", "total" }; opravilo na strežniku prekliče vsak ID (že preklicane preskoči) in ga je mogoče nadaljevati. Že preklicani in neobstoječi ID-ji so sporočeni kot preskočeni.

---

Brisanje poverilnice

Trajno izbrišite poverilnico, ki ste jo izdali. Za razliko od preklica to v celoti odstrani zapis, javna stran poverilnice pa vrne 404. Uporabite za resnične napake (npr. izdano napačni osebi); za prave poverilnice raje uporabite preklic, da trditev ostane preverljiva kot preklicana. Kredit se ne povrne.

DELETE /awards/{awardId}

Parametri

Parameter	Tip	Obvezen	Opis
awardId	string	Da	ID podelitve (parameter poti)

Primer

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

Odgovor

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

---

Prenos PDF potrdila

Ustvarite A4 PDF potrdilo za poverilnico, pripravljeno za tisk.

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

Preverjanje pristnosti ni potrebno — ta končna točka je javna, da lahko prejemniki prenesejo lastno potrdilo.

Primer

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

Odgovor je binarni PDF z glavo Content-Type: application/pdf.

---

Beleženje dogodka poverilnice

Zabeležite dogodek angažiranosti. Uporablja ga javna stran poverilnice za polnjenje statistike angažiranosti. Preverjanje pristnosti ni potrebno.

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

Parametri

Ta končna točka bere telo neposredno (brez ovoja parameters).

Parameter	Tip	Obvezen	Opis
event	string	Da	Eno od view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ne	Ko je event=share, družbeno omrežje: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Zatiranje dvojnikov po IP-ju: isti dogodek z istega IP-ja se šteje enkrat na 24 ur.

Primer

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

Odgovor

{
  "ok": true
}

---

Pridobitev statistike poverilnice

Pridobite kumulativne števce angažiranosti za poverilnico.

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

Preverjanje pristnosti ni potrebno.

Odgovor

Števci so vrnjeni po surovem tipu dogodka. totals vsebuje skupno število za vsak dogodek; networks razčleni razdelitev po omrežjih za dogodke, ki nosijo network (trenutno share). Dogodki brez zabeležene dejavnosti preprosto manjkajo.

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