Awards API

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

Vsi endpointi zahtevajo avtentikacijo prek glave X-Api-Key. Glej Avtentikacija.

Ustvari podelitev

Izdajte značko prejemniku.

POST /awards

Parametri

Parameter	Tip	Obvezno	Opis
badgeId	string	Da	ID značke za podelitev
recipient	object	Da	Podrobnosti prejemnika (glej 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 obliki ISO 8601 (npr. 2025-01-15)
expires	string	Ne	Datum poteka v obliki ISO 8601
blockchain	string	Ne	Veriga blokov za on-chain preverjanje. Podprta je le matchain. Na voljo v paketu Pro.

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

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

Opombe

• Šteje se kot ena podelitev proti vaši mesečni kvoti (Free: 100/mes, Starter: 1.000/mes, Pro: 10.000/mes). Kvota se ponastavi vsako obračunsko obdobje.
• Parameter blockchain je na voljo le v paketu Pro.

---

Naštej podelitve

Pridobite podelitve z izbirnim filtriranjem in razdelitvijo na strani.

GET /awards

Parametri poizvedbe

Parameter	Tip	Obvezno	Opis
filter	JSON string	Ne	Objekt filtra (glej spodaj)
lastEvaluatedKey	string	Ne	Žeton razdelitve na strani iz prejšnjega odgovora

Objekt filtra

Parameter filter sprejema niz JSON s temi polji:

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

Razdelitev na strani prek lastEvaluatedKey deluje s filtri ali brez. Velikost strani je 50.

Primer — Naštej vse podelitve

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

Primer — Filtriraj 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

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

Če je lastEvaluatedKey prisoten v odgovoru, obstaja več rezultatov. Posredujte ga kot parameter poizvedbe v naslednji zahtevi za pridobitev naslednje strani.

---

Pošlji e-pošto podelitve

Pošljite e-poštno obvestilo prejemniku o njegovi podelitvi.

POST /awards/{awardId}/send

Parametri

Parameter	Tip	Obvezno	Opis
awardId	string	Da	ID podelitve (parameter poti in telesa)
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

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

---

Deli podelitev

Delite podelitev z več prejemniki prek e-pošte.

POST /awards/{awardId}/share

Parametri

Parameter	Tip	Obvezno	Opis
awardId	string	Da	ID podelitve (parameter poti in telesa)
recipients	string	Da	Seznam e-poštnih naslovov, ločenih z vejicami
subject	string	Da	Vrstica zadeve e-pošte
message	string	Da	Telo sporočila e-pošte

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

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

---

Prenesi PDF spričevalo

Ustvarite spričevalo A4 PDF, pripravljeno za tisk, za podelitev.

GET /awards/{awardGuid}/pdf

Brez avtentikacije — ta endpoint je javen, da lahko prejemniki prenesejo svoje lastno spričevalo.

Primer

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

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

---

Sledi dogodek podelitve

Zabeleži dogodek angažiranosti (ogled, deljenje, prenos, LinkedIn add). Uporablja ga javna stran podelitve za polnjenje statistike angažiranosti. Brez avtentikacije.

POST /awards/{awardGuid}/event

Parametri

Parameter	Tip	Obvezno	Opis
kind	string	Da	Eden izmed view, share, download, linkedin_add.
network	string	Ne	Ko je kind=share, družbeno omrežje: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potlačitev podvojenosti glede na IP: enak kind iz istega IP se šteje enkrat na 24 ur.

Primer

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

---

Pridobi statistiko podelitve

Pridobite kumulativne števce angažiranosti za podelitev.

GET /awards/{awardGuid}/stats

Brez avtentikacije.

Odgovor

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