Awards API

Kurkite ir valdykite ženklelių apdovanojimus (assertions) — ženklelius, išduotus konkretiems gavėjams.

Visi galutiniai taškai reikalauja autentikavimo per antraštę X-Api-Key. Žr. Autentikavimas.

Sukurti apdovanojimą

Apdovanoti gavėją ženkleliu.

POST /awards

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Apdovanojamo ženklelio ID
recipient	object	Taip	Gavėjo detalės (žr. toliau)
recipient.name	string	Taip	Gavėjo pilnas vardas (mažiausiai 5 simboliai)
recipient.email	string	Taip	Gavėjo el. pašto adresas
issuedOn	string	Taip	Išdavimo data ISO 8601 formatu (pvz., 2025-01-15)
expires	string	Ne	Galiojimo pabaigos data ISO 8601 formatu
blockchain	string	Ne	Blokų grandinė grandinės patikrai. Palaikomas tik matchain. Prieinama Pro plane.

Pavyzdys

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

Atsakymas

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

Pastabos

• Skaičiuojama kaip vienas apdovanojimas prieš jūsų mėnesio kvotą (Free: 100/mėn, Starter: 1 000/mėn, Pro: 10 000/mėn). Kvota atstatoma kiekvieną atsiskaitymo laikotarpį.
• Parametras blockchain prieinamas tik Pro plane.

---

Išvardyti apdovanojimus

Gauti apdovanojimus su pasirinktiniu filtravimu ir puslapiavimu.

GET /awards

Užklausos parametrai

Parametras	Tipas	Privalomas	Aprašymas
filter	JSON eilutė	Ne	Filtro objektas (žr. toliau)
lastEvaluatedKey	string	Ne	Puslapiavimo žetonas iš ankstesnio atsakymo

Filtro objektas

Parametras filter priima JSON eilutę su šiais laukais:

Laukas	Tipas	Aprašymas
badgeId	string	Filtruoti pagal ženklelio ID.
search	string	Potekstė, kurią ieškoti gavėjų varduose arba el. paštuose (žr. searchField).
searchField	string	Arba name (numatyta), arba email — kurį stulpelį ieškoti.

Puslapiavimas per lastEvaluatedKey veikia su filtrais ar be jų. Puslapio dydis yra 50.

Pavyzdys — išvardyti visus apdovanojimus

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

Pavyzdys — filtruoti pagal ženklelį

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"

Atsakymas

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

Jei lastEvaluatedKey yra atsakyme, yra daugiau rezultatų. Perduokite jį kaip užklausos parametrą kitoje užklausoje, kad gautumėte kitą puslapį.

---

Siųsti apdovanojimo el. laišką

Siųsti gavėjui pranešimo el. laišką apie jo apdovanojimą.

POST /awards/{awardId}/send

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras ir kūnas)
email	string	Taip	Gavėjo el. pašto adresas

Pavyzdys

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

Atsakymas

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

---

Dalytis apdovanojimu

Dalytis apdovanojimu su keliais gavėjais el. paštu.

POST /awards/{awardId}/share

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Apdovanojimo ID (kelio parametras ir kūnas)
recipients	string	Taip	Kableliais atskirtas el. paštų sąrašas
subject	string	Taip	El. laiško tema
message	string	Taip	El. laiško žinutės turinys

Pavyzdys

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

Atsakymas

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

---

Atsisiųsti PDF pažymėjimą

Sugeneruoti spausdinti paruoštą A4 PDF pažymėjimą apdovanojimui.

GET /awards/{awardGuid}/pdf

Autentikavimo nereikia — šis galutinis taškas yra viešas, kad gavėjai galėtų atsisiųsti savo pažymėjimą.

Pavyzdys

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

Atsakymas yra dvejetainis PDF su antrašte Content-Type: application/pdf.

---

Sekti apdovanojimo įvykį

Įrašyti įsitraukimo įvykį (peržiūra, dalijimasis, atsisiuntimas, LinkedIn pridėjimas). Naudoja viešas apdovanojimo puslapis, kad užpildytų įsitraukimo statistiką. Autentikavimo nereikia.

POST /awards/{awardGuid}/event

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
kind	string	Taip	Vienas iš: view, share, download, linkedin_add.
network	string	Ne	Kai kind=share, socialinis tinklas: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP dublikatų slopinimas: tas pats tipas iš to paties IP skaičiuojamas vieną kartą per 24 valandas.

Pavyzdys

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

---

Gauti apdovanojimo statistiką

Gauti apdovanojimo kumuliacinius įsitraukimo skaitiklius.

GET /awards/{awardGuid}/stats

Autentikavimo nereikia.

Atsakymas

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