API pověření

Vytvářejte a spravujte pověření (assertions) — odznaky vydané konkrétním příjemcům.

Všechny endpointy vyžadují ověření prostřednictvím hlavičky X-Api-Key. Viz Ověřování.

Vytvoření pověření

Vydejte odznak příjemci.

Potřebujete vydávat stovkám nebo tisícům příjemců najednou, místo jednoho volání API na osobu? Použijte funkci uživatelského rozhraní Hromadná pověření, která přijímá nahrání souboru CSV.

POST /awards

Parametry

Parametr	Typ	Povinný	Popis
badgeId	string	Ano	ID odznaku, který se má vydat
recipient	object	Ano	Údaje o příjemci (viz níže)
recipient.name	string	Ano	Celé jméno příjemce (minimálně 5 znaků)
recipient.email	string	Ano	E-mailová adresa příjemce
issuedOn	string	Ano	Datum vydání ve formátu ISO 8601 (např. 2025-01-15)
expires	string	Ne	Datum vypršení platnosti ve formátu ISO 8601

Pří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"
    }
  }'

Odpověď

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

Poznámky

• Počítá se jako jedno pověření z vašeho ročního poolu pověření (Free: 1 200/rok, Starter: 12 000/rok, Pro: 120 000/rok). Pool je flexibilní roční příděl — čerpejte z něj, kdy chcete, i v dávkách — a obnovuje se v den výročí registrace vašeho účtu. Fakturace zůstává měsíční; roční je pouze kvóta pověření. Podrobnosti viz Tarify a fakturace.

---

Výpis pověření

Načtěte pověření s volitelným filtrováním a stránkováním.

GET /awards

Parametry dotazu

Parametr	Typ	Povinný	Popis
filter	řetězec JSON	Ne	Objekt filtru (viz níže)
lastEvaluatedKey	string	Ne	Token stránkování z předchozí odpovědi

Objekt filtru

Parametr filter přijímá řetězec JSON s těmito poli:

Pole	Typ	Popis
badgeId	string	Filtrování podle ID odznaku.
search	string	Podřetězec k vyhledání ve jménech nebo e-mailech příjemců (viz searchField).
searchField	string	Buď name (výchozí), nebo email — který sloupec se prohledává.

Stránkování pomocí lastEvaluatedKey funguje s filtry i bez nich. Velikost stránky je 50.

Příklad — výpis všech pověření

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

Příklad — filtrování podle 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"

Odpověď

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

Pokud je v odpovědi přítomno lastEvaluatedKey, existují další výsledky. Předejte ho jako parametr dotazu v dalším požadavku, abyste získali další stránku.

---

Odeslání e-mailu s pověřením

Odešlete příjemci e-mailové oznámení o jeho pověření.

POST /awards/{awardId}/send

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID pověření (parametr cesty i těla)
email	string	Ano	E-mailová adresa příjemce

Pří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"
    }
  }'

Odpověď

Vrací prostý potvrzovací řetězec:

"email sent"

---

Sdílení pověření

Sdílejte pověření e-mailem s více příjemci.

POST /awards/{awardId}/share

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID pověření (parametr cesty i těla)
recipients	string	Ano	Seznam e-mailových adres oddělených čárkou
subject	string	Ano	Předmět e-mailu
message	string	Ano	Text e-mailové zprávy

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

Odpověď

Vrací prostý potvrzovací řetězec:

"email sent"

---

Odvolání pověření

Odvolejte pověření, které jste vydali. Hostovaná assertion Open Badges v2.0 se označí revoked: true (s volitelným důvodem), takže každý ověřovatel uvidí, že odznak již neplatí. Záznam o pověření se uchovává pro účely auditu a žádný kredit se nevrací.

Odvolání se šíří také do Verifiable Credential Open Badges 3.0 daného pověření: bit pověření se přepne ve W3C Bitstring Status List, na kterou odkazuje credentialStatus v rámci VC, takže odvolání zjistí i peněženky VC. Viz Odvolání (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID pověření (parametr cesty)
reason	string	Ne	Důvod odvolání. Zkracuje se na 500 znaků.
notify	boolean	Ne	Při hodnotě true pošle příjemci e-mail o tom, že jeho pověření bylo odvoláno. Výchozí hodnota je false.

Pří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
    }
  }'

Odpověď

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

Odvolání již odvolaného pověření je idempotentní — vrátí stejnou odpověď bez opětovného odeslání oznámení.

Hromadné odvolání

Chcete-li odvolat mnoho pověření najednou, použijte místo volání tohoto endpointu pro každé pověření zvlášť odolný hromadný endpoint 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 } }'

Vrací { "jobId", "total" }; úloha odvolá každé ID na straně serveru (již odvolaná přeskočí) a lze ji obnovit. Již odvolaná a neexistující ID se hlásí jako přeskočená.

---

Smazání pověření

Trvale smažte pověření, které jste vydali. Na rozdíl od odvolání tím záznam zcela zmizí a veřejná stránka pověření bude vracet 404. Využijte to pro skutečné chyby (např. vydání nesprávné osobě); u skutečných pověření dávejte přednost odvolání, aby assertion zůstala ověřitelná jako odvolaná. Žádný kredit se nevrací.

DELETE /awards/{awardId}

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID pověření (parametr cesty)

Příklad

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

Odpověď

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

---

Stažení PDF certifikátu

Vygenerujte PDF certifikát ve formátu A4 připravený k tisku pro dané pověření.

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

Ověření není vyžadováno — tento endpoint je veřejný, aby si příjemci mohli stáhnout vlastní certifikát.

Příklad

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

Odpovědí je binární PDF s hlavičkou Content-Type: application/pdf.

---

Sledování události pověření

Zaznamenejte událost zapojení. Používá ji veřejná stránka pověření k naplnění statistik zapojení. Ověření není vyžadováno.

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

Parametry

Tento endpoint čte své tělo přímo (bez obalu parameters).

Parametr	Typ	Povinný	Popis
event	string	Ano	Jedna z hodnot view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ne	Při event=share sociální síť: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potlačení duplicit podle IP: stejná událost ze stejné IP adresy se započítá jednou za 24 hodin.

Pří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"}'

Odpověď

{
  "ok": true
}

---

Získání statistik pověření

Načtěte kumulativní čítače zapojení pro dané pověření.

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

Ověření není vyžadováno.

Odpověď

Čítače se vracejí podle surového typu události. totals obsahuje celkový počet pro každou událost; networks rozepisuje rozdělení podle sítí u událostí, které nesou network (aktuálně share). Události bez zaznamenané aktivity v odpovědi jednoduše chybějí.

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