API vjerodajnica

Izrada i upravljanje vjerodajnicama (assertionima) — značkama izdanima određenim primateljima.

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

Izrada vjerodajnice

Izdajte značku primatelju.

Trebate izdati stotinama ili tisućama primatelja odjednom umjesto jednog API poziva po osobi? Upotrijebite UI značajku Skupne vjerodajnice, koja prihvaća prijenos CSV datoteke.

POST /awards

Parametri

Parametar	Tip	Obavezno	Opis
badgeId	string	Da	ID značke koju treba izdati
recipient	object	Da	Podaci o primatelju (pogledajte dolje)
recipient.name	string	Da	Puno ime primatelja (najmanje 5 znakova)
recipient.email	string	Da	E-adresa primatelja
issuedOn	string	Da	Datum izdavanja u formatu ISO 8601 (npr. 2025-01-15)
expires	string	Ne	Datum isteka u formatu ISO 8601

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

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

Napomene

• Računa se kao jedna vjerodajnica iz vašeg godišnjeg fonda vjerodajnica (Free: 1,200/godišnje, Starter: 12,000/godišnje, Pro: 120,000/godišnje). Fond je fleksibilna godišnja kvota — potrošite je kad god želite tijekom godine, uključujući u naletima — a resetira se na obljetnicu registracije vašeg računa. Naplata ostaje mjesečna; samo je kvota vjerodajnica godišnja. Pojedinosti pogledajte u Planovi i naplata.

---

Popis vjerodajnica

Dohvatite vjerodajnice uz neobvezno filtriranje i straničenje.

GET /awards

Parametri upita

Parametar	Tip	Obavezno	Opis
filter	JSON string	Ne	Objekt filtra (pogledajte dolje)
lastEvaluatedKey	string	Ne	Token za straničenje iz prethodnog odgovora

Objekt filtra

Parametar filter prihvaća JSON string s ovim poljima:

Polje	Tip	Opis
badgeId	string	Filtriranje prema ID-u značke.
search	string	Podniz za traženje u imenima ili e-adresama primatelja (pogledajte searchField).
searchField	string	Ili name (zadano) ili email — koji se stupac pretražuje.

Straničenje putem lastEvaluatedKey radi sa filtrima i bez njih. Veličina stranice je 50.

Primjer — popis svih vjerodajnica

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

Primjer — filtriranje prema 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

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

Ako je lastEvaluatedKey prisutan u odgovoru, postoji još rezultata. Proslijedite ga kao parametar upita u sljedećem zahtjevu da biste dobili sljedeću stranicu.

---

Slanje e-pošte o vjerodajnici

Pošaljite primatelju e-obavijest o njegovoj vjerodajnici.

POST /awards/{awardId}/send

Parametri

Parametar	Tip	Obavezno	Opis
awardId	string	Da	ID nagrade (parametar putanje i tijelo)
email	string	Da	E-adresa 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

Vraća običan string potvrde:

"email sent"

---

Dijeljenje vjerodajnice

Podijelite vjerodajnicu s više primatelja putem e-pošte.

POST /awards/{awardId}/share

Parametri

Parametar	Tip	Obavezno	Opis
awardId	string	Da	ID nagrade (parametar putanje i tijelo)
recipients	string	Da	Popis e-adresa odvojenih zarezom
subject	string	Da	Predmet 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

Vraća običan string potvrde:

"email sent"

---

Opoziv vjerodajnice

Opozovite vjerodajnicu koju ste izdali. Hostirani Open Badges v2.0 assertion označava se s revoked: true (uz neobvezan razlog) kako bi svaki alat za provjeru vidio da značka više nije valjana. Zapis vjerodajnice zadržava se radi revizije, a kredit se ne vraća.

Opoziv se prenosi i na Open Badges 3.0 Verifiable Credential vjerodajnice: bit nagrade preokreće se u W3C Bitstring Status List na koji upućuje credentialStatus iz VC-a, pa opoziv otkrivaju i VC novčanici. Pogledajte Opoziv (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametri

Parametar	Tip	Obavezno	Opis
awardId	string	Da	ID nagrade (parametar putanje)
reason	string	Ne	Razlog opoziva. Skraćuje se na 500 znakova.
notify	boolean	Ne	Kada je true, e-poštom obavještava primatelja da je njegova vjerodajnica opozvana. Zadano je false.

Primjer

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

Odgovor

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

Opoziv već opozvane vjerodajnice idempotentan je — vraća isti odgovor bez ponovnog slanja obavijesti.

Skupni opoziv

Za opoziv mnogo vjerodajnica odjednom upotrijebite trajni skupni endpoint s action: "revoke" umjesto pozivanja ovog endpointa za svaku nagradu:

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

Vraća { "jobId", "total" }; zadatak na poslužitelju opoziva svaki id (preskačući već opozvane) i može se nastaviti. Već opozvani i nepostojeći id-ovi prijavljuju se kao preskočeni.

---

Brisanje vjerodajnice

Trajno izbrišite vjerodajnicu koju ste izdali. Za razliku od opoziva, ovo potpuno uklanja zapis, a javna stranica vjerodajnice vraćat će 404. Koristite to za stvarne pogreške (npr. izdano pogrešnoj osobi); za prave vjerodajnice radije odaberite opoziv kako bi assertion ostao provjerljiv kao opozvan. Kredit se ne vraća.

DELETE /awards/{awardId}

Parametri

Parametar	Tip	Obavezno	Opis
awardId	string	Da	ID nagrade (parametar putanje)

Primjer

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

Odgovor

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

---

Preuzimanje PDF certifikata

Generirajte A4 PDF certifikat spreman za ispis za vjerodajnicu.

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

Autentifikacija nije potrebna — ovaj je endpoint javan kako bi primatelji mogli preuzeti vlastiti certifikat.

Primjer

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

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

---

Praćenje događaja vjerodajnice

Zabilježite događaj angažmana. Koristi ga javna stranica vjerodajnice za popunjavanje statistike angažmana. Autentifikacija nije potrebna.

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

Parametri

Ovaj endpoint čita svoje tijelo izravno (bez omotača parameters).

Parametar	Tip	Obavezno	Opis
event	string	Da	Jedno od: view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Ne	Kada je event=share, društvena mreža: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Suzbijanje duplikata po IP-u: isti događaj s iste IP adrese broji se jednom u 24 sata.

Primjer

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

Odgovor

{
  "ok": true
}

---

Dohvaćanje statistike vjerodajnice

Dohvatite kumulativne brojače angažmana za vjerodajnicu.

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

Autentifikacija nije potrebna.

Odgovor

Brojači se vraćaju po izvornom tipu događaja. totals sadrži ukupni broj po događaju; networks prikazuje raspodjelu po mrežama za događaje koji nose network (trenutačno share). Događaji bez zabilježene aktivnosti jednostavno nedostaju.

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