Awards API

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

Všetky endpointy vyžadujú autentifikáciu cez hlavičku X-Api-Key. Pozri Autentifikácia.

Vytvoriť udelenie

Vydajte odznak príjemcovi.

POST /awards

Parametre

Parameter	Typ	Povinné	Popis
badgeId	string	Áno	ID odznaku na udelenie
recipient	object	Áno	Detaily príjemcu (pozri 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 exspirácie vo formáte ISO 8601
blockchain	string	Nie	Blockchain pre on-chain overenie. Podporovaný je iba matchain. Dostupné v pláne Pro.

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ď

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

Poznámky

• Počíta sa ako jedno udelenie proti vašej mesačnej kvóte (Free: 100/mes, Starter: 1 000/mes, Pro: 10 000/mes). Kvóta sa obnoví každé fakturačné obdobie.
• Parameter blockchain je dostupný iba v pláne Pro.

---

Zobraziť udelenia

Získajte udelenia s voliteľným filtrovaním a stránkovaním.

GET /awards

Parametre dotazu

Parameter	Typ	Povinné	Popis
filter	JSON string	Nie	Filtrovací objekt (pozri nižšie)
lastEvaluatedKey	string	Nie	Token stránkovania z predchádzajúcej odpovede

Filtrovací objekt

Parameter filter prijíma JSON string s týmito poliami:

Pole	Typ	Popis
badgeId	string	Filter podľa ID odznaku.
search	string	Podreťazec na vyhľadanie v menách alebo e-mailoch príjemcov (pozri searchField).
searchField	string	Buď name (predvolené) alebo email — ktorý stĺpec hľadať.

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

Príklad — Zobraziť všetky udelenia

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

Príklad — Filtrovať 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ď

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "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 lastEvaluatedKey v odpovedi prítomný, existuje viac výsledkov. Odovzdajte ho ako parameter dotazu v ďalšej požiadavke na získanie ďalšej stránky.

---

Odoslať e-mail udelenia

Pošlite e-mailové upozornenie príjemcovi o jeho udelení.

POST /awards/{awardId}/send

Parametre

Parameter	Typ	Povinné	Popis
awardId	string	Áno	ID udelenia (parameter cesty a 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ď

{
  "statusCode": 200,
  "info": {
    "sent": true
  }
}

---

Zdieľať udelenie

Zdieľajte udelenie s viacerými príjemcami cez e-mail.

POST /awards/{awardId}/share

Parametre

Parameter	Typ	Povinné	Popis
awardId	string	Áno	ID udelenia (parameter cesty a tela)
recipients	string	Áno	Zoznam e-mailových adries oddelených čiarkami
subject	string	Áno	Predmet e-mailu
message	string	Áno	Telo správy e-mailu

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ď

{
  "statusCode": 200,
  "info": {
    "shared": true
  }
}

---

Stiahnuť PDF certifikát

Vygenerujte A4 PDF certifikát pripravený na tlač pre udelenie.

GET /awards/{awardGuid}/pdf

Bez autentifikácie — tento endpoint je verejný, aby si príjemcovia mohli stiahnuť svoj vlastný certifikát.

Príklad

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

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

---

Sledovať udalosť udelenia

Zaznamenajte udalosť zapojenia (zobrazenie, zdieľanie, sťahovanie, LinkedIn add). Používa to verejná stránka udelenia na vyplnenie štatistík zapojenia. Bez autentifikácie.

POST /awards/{awardGuid}/event

Parametre

Parameter	Typ	Povinné	Popis
kind	string	Áno	Jeden z view, share, download, linkedin_add.
network	string	Nie	Keď kind=share, sociálna sieť: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potlačenie duplicít na IP: ten istý kind z tej istej IP sa počíta raz za 24 hodín.

Príklad

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

---

Získať štatistiky udelenia

Získajte kumulatívne počítadlá zapojenia pre udelenie.

GET /awards/{awardGuid}/stats

Bez autentifikácie.

Odpoveď

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}