Awards API

Stvaranje i upravljanje dodjelama bedževa (assertions) — bedževima izdanim određenim primateljima.

Svi endpointi zahtijevaju autentifikaciju preko zaglavlja X-Api-Key. Pogledajte Autentifikacija.

Stvori dodjelu

Izdajte bedž primatelju.

POST /awards

Parametri

Parametar	Tip	Obvezno	Opis
badgeId	string	Da	ID bedža za dodjelu
recipient	object	Da	Pojedinosti primatelja (vidi dolje)
recipient.name	string	Da	Puno ime primatelja (najmanje 5 znakova)
recipient.email	string	Da	Adresa e-pošte primatelja
issuedOn	string	Da	Datum izdavanja u formatu ISO 8601 (npr. 2025-01-15)
expires	string	Ne	Datum isteka u formatu ISO 8601
blockchain	string	Ne	Blockchain za on-chain provjeru. Podržan je samo matchain. Dostupno u planu Pro.

Primjer

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

Napomene

• Broji se kao jedna dodjela prema vašoj mjesečnoj kvoti (Free: 100/mj, Starter: 1.000/mj, Pro: 10.000/mj). Kvota se ponavlja svako obračunsko razdoblje.
• Parametar blockchain dostupan je samo u planu Pro.

---

Popiši dodjele

Dohvatite dodjele s opcionalnim filtriranjem i straničenjem.

GET /awards

Upitni parametri

Parametar	Tip	Obvezno	Opis
filter	JSON string	Ne	Objekt filtra (vidi dolje)
lastEvaluatedKey	string	Ne	Token straničenja iz prethodnog odgovora

Objekt filtra

Parametar filter prihvaća JSON niz s ovim poljima:

Polje	Tip	Opis
badgeId	string	Filter po ID bedža.
search	string	Podniz za potragu u imenima ili e-poštama primatelja (vidi searchField).
searchField	string	Bilo name (zadano) bilo email — koji stupac pretraživati.

Straničenje preko lastEvaluatedKey radi s filtrima i bez njih. Veličina stranice je 50.

Primjer — Popiši sve dodjele

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

Primjer — Filtriraj po bedžu

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

Ako je lastEvaluatedKey prisutan u odgovoru, postoji više rezultata. Proslijedite ga kao upitni parametar u sljedećem zahtjevu za dohvat sljedeće stranice.

---

Pošalji e-poštu dodjele

Pošaljite e-poštnu obavijest primatelju o njegovoj dodjeli.

POST /awards/{awardId}/send

Parametri

Parametar	Tip	Obvezno	Opis
awardId	string	Da	ID dodjele (parametar putanje i tijela)
email	string	Da	Adresa e-pošte primatelja

Primjer

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

---

Podijeli dodjelu

Podijelite dodjelu s više primatelja preko e-pošte.

POST /awards/{awardId}/share

Parametri

Parametar	Tip	Obvezno	Opis
awardId	string	Da	ID dodjele (parametar putanje i tijela)
recipients	string	Da	Popis adresa e-pošte odvojenih zarezima
subject	string	Da	Redak predmeta e-pošte
message	string	Da	Tijelo poruke e-pošte

Primjer

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

---

Preuzmi PDF certifikat

Generirajte A4 PDF certifikat spreman za tisak za dodjelu.

GET /awards/{awardGuid}/pdf

Bez autentifikacije — ovaj endpoint je javan tako da primatelji mogu preuzeti svoj vlastiti certifikat.

Primjer

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

Odgovor je binarni PDF sa zaglavljem Content-Type: application/pdf.

---

Prati događaj dodjele

Zabilježite događaj angažmana (pregled, dijeljenje, preuzimanje, LinkedIn add). Koristi ga javna stranica dodjele za popunjavanje statistike angažmana. Bez autentifikacije.

POST /awards/{awardGuid}/event

Parametri

Parametar	Tip	Obvezno	Opis
kind	string	Da	Jedan od view, share, download, linkedin_add.
network	string	Ne	Kad je kind=share, društvena mreža: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Potiskivanje duplikata po IP-u: isti kind iz iste IP-a broji se jednom u 24 sata.

Primjer

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

---

Dohvati statistiku dodjele

Dohvatite kumulativne brojače angažmana za dodjelu.

GET /awards/{awardGuid}/stats

Bez autentifikacije.

Odgovor

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