API credentialov

Vytváranie a správa credentialov (assertion) — odznakov vydaných konkrétnym príjemcom.

Všetky koncové body vyžadujú autentifikáciu cez hlavičku X-Api-Key. Pozrite si Autentifikácia.

Vytvorenie credentialu

Vydanie odznaku príjemcovi.

Potrebujete vydať odznaky stovkám či tisíckam príjemcov naraz namiesto jedného volania API na osobu? Použite funkciu rozhrania Hromadné credentialy, ktorá prijíma nahratý súbor CSV.

POST /awards

Parametre

Parameter	Typ	Povinný	Popis
badgeId	string	Áno	ID odznaku, ktorý sa má vydať
recipient	object	Áno	Údaje o príjemcovi (pozrite nižšie)
recipient.name	string	Áno	Celé meno príjemcu (minimálne 5 znakov)
recipient.email	string	Áno	E-mailová adresa príjemcu
issuedOn	string	Áno	Dátum vydania vo formáte ISO 8601 (napr. 2025-01-15)
expires	string	Nie	Dátum skončenia platnosti vo formáte ISO 8601

Príklad

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

Odpoveď

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

Poznámky

• Spotrebuje jeden credential z vášho ročného fondu credentialov (Free: 1 200/rok, Starter: 12 000/rok, Pro: 120 000/rok). Fond je flexibilný ročný limit — môžete ho čerpať kedykoľvek počas roka, aj v dávkach — a obnovuje sa v deň výročia registrácie vášho účtu. Fakturácia ostáva mesačná; ročná je len kvóta credentialov. Podrobnosti nájdete v časti Plány a fakturácia.

---

Zoznam credentialov

Načítanie credentialov s voliteľným filtrovaním a stránkovaním.

GET /awards

Parametre dotazu

Parameter	Typ	Povinný	Popis
filter	reťazec JSON	Nie	Objekt filtra (pozrite nižšie)
lastEvaluatedKey	string	Nie	Token stránkovania z predchádzajúcej odpovede

Objekt filtra

Parameter filter prijíma reťazec JSON s týmito poľami:

Pole	Typ	Popis
badgeId	string	Filtrovanie podľa ID odznaku.
search	string	Podreťazec na vyhľadanie v menách alebo e-mailoch príjemcov (pozrite searchField).
searchField	string	Buď name (predvolené), alebo email — v ktorom stĺpci sa má hľadať.

Stránkovanie cez lastEvaluatedKey funguje s filtrami aj bez nich. Veľkosť stránky je 50.

Príklad — zoznam všetkých credentialov

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

Príklad — filtrovanie podľa odznaku

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"

Odpoveď

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

Ak je v odpovedi prítomný lastEvaluatedKey, existujú ďalšie výsledky. Odovzdajte ho ako parameter dotazu v ďalšej požiadavke, aby ste získali nasledujúcu stránku.

---

Odoslanie e-mailu o credentiale

Odoslanie e-mailového oznámenia príjemcovi o jeho credentiale.

POST /awards/{awardId}/send

Parametre

Parameter	Typ	Povinný	Popis
awardId	string	Áno	ID credentialu (parameter cesty aj tela)
email	string	Áno	E-mailová adresa príjemcu

Príklad

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

Odpoveď

Vracia jednoduchý potvrdzujúci reťazec:

"email sent"

---

Zdieľanie credentialu

Zdieľanie credentialu e-mailom s viacerými príjemcami.

POST /awards/{awardId}/share

Parametre

Parameter	Typ	Povinný	Popis
awardId	string	Áno	ID credentialu (parameter cesty aj tela)
recipients	string	Áno	Zoznam e-mailových adries oddelených čiarkou
subject	string	Áno	Predmet e-mailu
message	string	Áno	Text e-mailovej správy

Príklad

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

Odpoveď

Vracia jednoduchý potvrdzujúci reťazec:

"email sent"

---

Zrušenie platnosti credentialu

Zrušenie platnosti credentialu, ktorý ste vydali. Hostovaná assertion Open Badges v2.0 sa označí ako revoked: true (s voliteľným dôvodom), takže každý overovateľ vidí, že odznak už nie je platný. Záznam o credentiale sa uchováva na účely auditu a kredit sa nevracia.

Zrušenie platnosti sa prenáša aj do Verifiable Credential Open Badges 3.0 daného credentialu: bit ocenenia sa prepne v Bitstring Status List W3C, na ktorý odkazuje credentialStatus vo VC, takže ho zistia aj VC peňaženky. Pozrite si Zrušenie platnosti (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametre

Parameter	Typ	Povinný	Popis
awardId	string	Áno	ID credentialu (parameter cesty)
reason	string	Nie	Dôvod zrušenia platnosti. Skracuje sa na 500 znakov.
notify	boolean	Nie	Ak je true, príjemcovi sa e-mailom oznámi, že jeho credential bol zrušený. Predvolene false.

Príklad

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

Odpoveď

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

Zrušenie platnosti už zrušeného credentialu je idempotentné — vráti rovnakú odpoveď bez opätovného odoslania oznámenia.

Hromadné zrušenie platnosti

Ak chcete zrušiť platnosť viacerých credentialov naraz, použite namiesto volania tohto koncového bodu pre každé ocenenie trvalý hromadný koncový bod s 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 } }'

Vracia { "jobId", "total" }; úloha zruší platnosť každého ID na strane servera (už zrušené preskočí) a dá sa obnoviť. Už zrušené a neexistujúce ID sa hlásia ako preskočené.

---

Odstránenie credentialu

Trvalé odstránenie credentialu, ktorý ste vydali. Na rozdiel od zrušenia platnosti sa záznam odstráni úplne a verejná stránka credentialu bude vracať 404. Používajte to pri skutočných chybách (napr. vydané nesprávnej osobe); pri skutočných credentialoch uprednostnite zrušenie platnosti, aby assertion zostala overiteľná ako zrušená. Kredit sa nevracia.

DELETE /awards/{awardId}

Parametre

Parameter	Typ	Povinný	Popis
awardId	string	Áno	ID credentialu (parameter cesty)

Príklad

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

Odpoveď

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

---

Stiahnutie PDF certifikátu

Vygenerovanie PDF certifikátu vo formáte A4 pripraveného na tlač pre credential.

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

Autentifikácia nie je potrebná — tento koncový bod je verejný, aby si príjemcovia mohli stiahnuť vlastný certifikát.

Príklad

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

Odpoveďou je binárne PDF s hlavičkou Content-Type: application/pdf.

---

Sledovanie udalosti credentialu

Zaznamenanie udalosti zapojenia. Používa ho verejná stránka credentialu na naplnenie štatistík zapojenia. Autentifikácia nie je potrebná.

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

Parametre

Tento koncový bod číta telo požiadavky priamo (bez obalu parameters).

Parameter	Typ	Povinný	Popis
event	string	Áno	Jedna z hodnôt view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nie	Pri event=share sociálna sieť: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potlačenie duplikátov podľa IP: tá istá udalosť z tej istej IP adresy sa počíta raz za 24 hodín.

Príklad

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

Odpoveď

{
  "ok": true
}

---

Získanie štatistík credentialu

Načítanie kumulatívnych počítadiel zapojenia pre credential.

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

Autentifikácia nie je potrebná.

Odpoveď

Počítadlá sa vracajú podľa pôvodného typu udalosti. totals obsahuje celkový počet pre každú udalosť; networks rozpisuje rozdelenie podľa sietí pre udalosti, ktoré majú network (momentálne share). Udalosti bez zaznamenanej aktivity jednoducho chýbajú.

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