Credentials API

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

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

Sukurti pažymėjimą

Išduoti ženklelį gavėjui.

POST /awards

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
badgeId	string	Taip	Išduodamo ž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

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 pažymėjimas 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į.

---

Išvardyti pažymėjimus

Gauti pažymėjimus 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 pažymėjimus

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 pažymėjimo el. laišką

Siųsti gavėjui pranešimo el. laišką apie jo pažymėjimą.

POST /awards/{awardId}/send

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Pažymėjimo 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 pažymėjimu

Dalytis pažymėjimu su keliais gavėjais el. paštu.

POST /awards/{awardId}/share

Parametrai

Parametras	Tipas	Privalomas	Aprašymas
awardId	string	Taip	Pažymėjimo 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ą pažymėjimui.

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 pažymėjimo įvykį

Įrašyti įsitraukimo įvykį (peržiūra, dalijimasis, atsisiuntimas, LinkedIn pridėjimas). Naudoja viešas pažymėjimo 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 pažymėjimo statistiką

Gauti pažymėjimo 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
    }
  }
}