Hitelesítő adatok API

Hitelesítő adatok (assertionök) létrehozása és kezelése — meghatározott kedvezményezetteknek kibocsátott jelvények.

Minden végponthoz hitelesítés szükséges az X-Api-Key fejlécen keresztül. Lásd: Hitelesítés.

Hitelesítő adat létrehozása

Jelvény kibocsátása egy kedvezményezettnek.

Százakat vagy ezreket kell egyszerre kibocsátanod, személyenkénti egy API-hívás helyett? Használd a Tömeges hitelesítő adatok felületi funkciót, amely CSV-feltöltést fogad el.

POST /awards

Paraméterek

Paraméter	Típus	Kötelező	Leírás
badgeId	string	Igen	A kibocsátandó jelvény azonosítója
recipient	object	Igen	A kedvezményezett adatai (lásd lent)
recipient.name	string	Igen	A kedvezményezett teljes neve (legalább 5 karakter)
recipient.email	string	Igen	A kedvezményezett e-mail-címe
issuedOn	string	Igen	Kibocsátás dátuma ISO 8601 formátumban (pl. 2025-01-15)
expires	string	Nem	Lejárati dátum ISO 8601 formátumban

Példa

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

Válasz

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

Megjegyzések

• Egy hitelesítő adatnak számít az éves hitelesítőadat-keretedből (Free: 1,200/év, Starter: 12,000/év, Pro: 120,000/év). A keret rugalmas éves juttatás — az év során bármikor felhasználhatod, akár egy lendülettel is — és a fiókod regisztrációs évfordulóján nullázódik. A számlázás havi marad; csak a hitelesítőadat-kvóta éves. A részletekért lásd: Csomagok és számlázás.

---

Hitelesítő adatok listázása

Hitelesítő adatok lekérése opcionális szűréssel és lapozással.

GET /awards

Lekérdezési paraméterek

Paraméter	Típus	Kötelező	Leírás
filter	JSON string	Nem	Szűrőobjektum (lásd lent)
lastEvaluatedKey	string	Nem	Egy korábbi válaszból kapott lapozási token

Szűrőobjektum

A filter paraméter egy JSON stringet fogad el ezekkel a mezőkkel:

Mező	Típus	Leírás
badgeId	string	Szűrés jelvényazonosító szerint.
search	string	A kedvezményezettek nevében vagy e-mail-címében keresett részlet (lásd searchField).
searchField	string	name (alapértelmezett) vagy email — melyik oszlopban keressen.

A lastEvaluatedKey szerinti lapozás szűrőkkel és anélkül is működik. Az oldalméret 50.

Példa — az összes hitelesítő adat listázása

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

Példa — szűrés jelvény szerint

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"

Válasz

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

Ha a válaszban szerepel a lastEvaluatedKey, további találatok vannak. Add át lekérdezési paraméterként a következő kérésben, hogy megkapd a következő oldalt.

---

Hitelesítő adat e-mail küldése

E-mailes értesítés küldése egy kedvezményezettnek a hitelesítő adatáról.

POST /awards/{awardId}/send

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	Az award azonosítója (útvonalparaméter és törzs)
email	string	Igen	A kedvezményezett e-mail-címe

Példa

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

Válasz

Egyszerű visszaigazoló stringet ad vissza:

"email sent"

---

Hitelesítő adat megosztása

Hitelesítő adat megosztása több kedvezményezettel e-mailben.

POST /awards/{awardId}/share

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	Az award azonosítója (útvonalparaméter és törzs)
recipients	string	Igen	E-mail-címek vesszővel elválasztott listája
subject	string	Igen	Az e-mail tárgya
message	string	Igen	Az e-mail üzenetének törzse

Példa

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

Válasz

Egyszerű visszaigazoló stringet ad vissza:

"email sent"

---

Hitelesítő adat visszavonása

Az általad kibocsátott hitelesítő adat visszavonása. A tárolt Open Badges v2.0 assertion revoked: true jelölést kap (opcionális indoklással), így minden ellenőrző látja, hogy a jelvény már nem érvényes. A hitelesítőadat-rekord auditálási célból megmarad, és kredit nem kerül visszatérítésre.

A visszavonás kiterjed a hitelesítő adat Open Badges 3.0 Verifiable Credential-jére is: az award bitje átbillen a VC credentialStatus mezője által hivatkozott W3C Bitstring Status Listben, így a VC-tárcák is észlelik. Lásd: Visszavonás (Bitstring Status List).

POST /awards/{awardId}/revoke

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	Az award azonosítója (útvonalparaméter)
reason	string	Nem	A visszavonás oka. 500 karakterre csonkolódik.
notify	boolean	Nem	true esetén e-mailben értesíti a kedvezményezettet a hitelesítő adat visszavonásáról. Alapértelmezés: false.

Példa

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

Válasz

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

Egy már visszavont hitelesítő adat újbóli visszavonása idempotens — ugyanazt a választ adja vissza, az értesítés újraküldése nélkül.

Tömeges visszavonás

Sok hitelesítő adat egyszerre történő visszavonásához award-onkénti hívás helyett használd a tartós tömeges végpontot action: "revoke" értékkel:

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

{ "jobId", "total" } értéket ad vissza; a feladat szerveroldalon minden azonosítót visszavon (a már visszavontakat kihagyva), és folytatható. A már visszavont és a nem létező azonosítókat kihagyottként jelenti.

---

Hitelesítő adat törlése

Az általad kibocsátott hitelesítő adat végleges törlése. A visszavonással ellentétben ez teljesen eltávolítja a rekordot, és a nyilvános hitelesítőadat-oldal 404-et ad vissza. Valódi hibákra használd (pl. rossz személynek bocsátottad ki); valódi hitelesítő adatoknál inkább a visszavonást válaszd, hogy az assertion visszavontként ellenőrizhető maradjon. Kredit nem kerül visszatérítésre.

DELETE /awards/{awardId}

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	Az award azonosítója (útvonalparaméter)

Példa

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

Válasz

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

---

PDF-tanúsítvány letöltése

Nyomtatásra kész A4 PDF-tanúsítvány előállítása egy hitelesítő adathoz.

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

Hitelesítés nem szükséges — ez a végpont nyilvános, hogy a kedvezményezettek letölthessék saját tanúsítványukat.

Példa

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

A válasz a bináris PDF Content-Type: application/pdf fejléccel.

---

Hitelesítőadat-esemény követése

Elköteleződési esemény rögzítése. A nyilvános hitelesítőadat-oldal használja az elköteleződési statisztikák feltöltéséhez. Hitelesítés nem szükséges.

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

Paraméterek

Ez a végpont közvetlenül a törzsét olvassa (nincs parameters burkoló).

Paraméter	Típus	Kötelező	Leírás
event	string	Igen	A következők egyike: view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify.
network	string	Nem	event=share esetén a közösségi hálózat: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP-nkénti duplikációszűrés: ugyanaz az esemény ugyanarról az IP-címről 24 óránként egyszer számít.

Példa

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

Válasz

{
  "ok": true
}

---

Hitelesítőadat-statisztikák lekérése

Egy hitelesítő adat kumulatív elköteleződési számlálóinak lekérése.

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

Hitelesítés nem szükséges.

Válasz

A számlálók a nyers eseménytípus szerint kulcsolva érkeznek. A totals az eseményenkénti összesített számot tartalmazza; a networks a hálózatonkénti bontást adja azoknál az eseményeknél, amelyek network értéket hordoznak (jelenleg share). A rögzített tevékenység nélküli események egyszerűen hiányoznak.

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