Kiadások API

Hozz létre és kezelj jelvénykiadásokat (assertions) — adott címzetteknek kiadott jelvényeket.

Minden végpont az X-Api-Key fejléccel történő hitelesítést igényli. Lásd: Hitelesítés.

Kiadás létrehozása

Jelvény kiadása egy címzettnek.

POST /awards

Paraméterek

Paraméter	Típus	Kötelező	Leírás
badgeId	string	Igen	A kiadandó jelvény azonosítója
recipient	object	Igen	Címzett adatai (lásd alább)
recipient.name	string	Igen	A címzett teljes neve (legalább 5 karakter)
recipient.email	string	Igen	A címzett e-mail-címe
issuedOn	string	Igen	Kiadás dátuma ISO 8601 formátumban (pl. 2025-01-15)
expires	string	Nem	Lejárati dátum ISO 8601 formátumban
blockchain	string	Nem	Blockchain a láncon történő ellenőrzéshez. Csak a matchain támogatott. Pro csomagban elérhető.

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

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

Megjegyzések

• Egy kiadásként számít a havi keretedbe (Free: 100/hó, Starter: 1000/hó, Pro: 10 000/hó). A keret minden számlázási időszakban nullázódik.
• A blockchain paraméter csak Pro csomagban érhető el.

---

Kiadások listázása

Kiadások lekérése szűréssel és lapozással.

GET /awards

Lekérdezési paraméterek

Paraméter	Típus	Kötelező	Leírás
filter	JSON-sztring	Nem	Szűrőobjektum (lásd alább)
lastEvaluatedKey	string	Nem	Lapozási token egy korábbi válaszból

Szűrőobjektum

A filter paraméter JSON-sztringet fogad el a következő mezőkkel:

Mező	Típus	Leírás
badgeId	string	Szűrés jelvényazonosító szerint.
search	string	Részkifejezés, amelyet a címzettek nevében vagy e-mailjeiben keresünk (lásd searchField).
searchField	string	Vagy name (alapértelmezett), vagy email — melyik mezőben keressünk.

A lastEvaluatedKey alapú lapozás szűréssel és szűrés nélkül is működik. Oldalméret: 50.

Példa — összes kiadás 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ényre

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

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

Ha a válaszban szerepel a lastEvaluatedKey, akkor több eredmény van. Add át lekérdezési paraméterként a következő kérésben a további oldalhoz.

---

Kiadási e-mail küldése

E-mail-értesítést küld a címzettnek a saját kiadásáról.

POST /awards/{awardId}/send

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	A kiadás azonosítója (elérési útban és törzsben)
email	string	Igen	A címzett 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

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

---

Kiadás megosztása

Egy kiadás megosztása több címzettel e-mailben.

POST /awards/{awardId}/share

Paraméterek

Paraméter	Típus	Kötelező	Leírás
awardId	string	Igen	A kiadás azonosítója (elérési útban és törzsben)
recipients	string	Igen	Vesszővel elválasztott e-mail-címek
subject	string	Igen	Az e-mail tárgya
message	string	Igen	Az e-mail 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

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

---

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

Nyomtatásra kész A4-es PDF-tanúsítvány létrehozása egy kiadáshoz.

GET /awards/{awardGuid}/pdf

Nem igényel hitelesítést — ez a végpont nyilvános, hogy a címzettek letölthessék a saját tanúsítványukat.

Példa

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

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

---

Kiadási esemény naplózása

Elköteleződési esemény rögzítése (megtekintés, megosztás, letöltés, LinkedIn-hozzáadás). A nyilvános kiadási oldal ezt használja az elköteleződési statisztikák feltöltésére. Nem igényel hitelesítést.

POST /awards/{awardGuid}/event

Paraméterek

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

IP-enkénti duplikáció-kiszűrés: ugyanaz a kind ugyanarról az IP-ről 24 óránként egyszer számolódik.

Példa

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

---

Kiadási statisztikák lekérése

Egy kiadás halmozott elköteleződési számlálóinak lekérése.

GET /awards/{awardGuid}/stats

Nem igényel hitelesítést.

Válasz

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