API udělení

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

Všechny endpointy vyžadují autentizaci přes hlavičku X-Api-Key. Viz Autentizace.

Vytvořit udělení

Vydejte odznak příjemci.

POST /awards

Parametry

Parametr	Typ	Povinný	Popis
badgeId	string	Ano	ID odznaku k udělení
recipient	object	Ano	Detaily příjemce (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í ve formátu ISO 8601
blockchain	string	Ne	Blockchain pro on-chain ověření. Podporováno pouze matchain. Dostupné v plánu Pro.

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ěď

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

Poznámky

• Počítá se jako jedno udělení proti vašemu měsíčnímu limitu (Free: 100/měs, Starter: 1 000/měs, Pro: 10 000/měs). Limit se obnovuje každé zúčtovací období.
• Parametr blockchain je dostupný pouze v plánu Pro.

---

Seznam udělení

Načtěte udělení s volitelným filtrováním a stránkováním.

GET /awards

Query parametry

Parametr	Typ	Povinný	Popis
filter	JSON string	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á JSON string s těmito poli:

Pole	Typ	Popis
badgeId	string	Filtrovat 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 prohledat.

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

Příklad — seznam všech udělení

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ěď

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

Pokud je v odpovědi přítomen lastEvaluatedKey, jsou k dispozici další výsledky. Předejte jej jako query parametr v dalším požadavku, abyste získali další stránku.

---

Odeslat e-mail s udělením

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

POST /awards/{awardId}/send

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID udělení (parametr v cestě a v těle)
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ěď

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

---

Sdílet udělení

Sdílet udělení s více příjemci e-mailem.

POST /awards/{awardId}/share

Parametry

Parametr	Typ	Povinný	Popis
awardId	string	Ano	ID udělení (parametr v cestě a v těle)
recipients	string	Ano	Seznam e-mailových adres oddělených čárkou
subject	string	Ano	Předmět e-mailu
message	string	Ano	Tělo 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ěď

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

---

Stáhnout PDF certifikát

Vygenerujte tisknutelný certifikát PDF A4 pro udělení.

GET /awards/{awardGuid}/pdf

Autentizace se nevyžaduje — tento endpoint je veřejný, aby si příjemci mohli stáhnout svůj certifikát.

Příklad

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

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

---

Sledovat událost udělení

Zaznamenejte událost zaujetí (zobrazení, sdílení, stažení, LinkedIn add). Používá se veřejnou stránkou udělení k naplnění statistik zaujetí. Autentizace se nevyžaduje.

POST /awards/{awardGuid}/event

Parametry

Parametr	Typ	Povinný	Popis
kind	string	Ano	Jedno z view, share, download, linkedin_add.
network	string	Ne	Když kind=share, sociální síť: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potlačení duplicit per-IP: stejný kind ze stejné IP se počítá jednou za 24 hodin.

Pří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ískat statistiky udělení

Načtěte kumulativní čítače zaujetí pro udělení.

GET /awards/{awardGuid}/stats

Autentizace se nevyžaduje.

Odpověď

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