Awards API

Loo ja halda märgiautasusid (assertsioone) — märke, mis antakse konkreetsetele saajatele.

Kõik otspunktid nõuavad autentimist päise X-Api-Key kaudu. Vt Autentimine.

Loo autasu

Anna märk saajale.

POST /awards

Parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
badgeId	string	Jah	Antava märgi ID
recipient	object	Jah	Saaja üksikasjad (vt allpool)
recipient.name	string	Jah	Saaja täisnimi (vähemalt 5 tähemärki)
recipient.email	string	Jah	Saaja e-posti aadress
issuedOn	string	Jah	Väljastamise kuupäev ISO 8601 vormingus (nt 2025-01-15)
expires	string	Ei	Aegumiskuupäev ISO 8601 vormingus
blockchain	string	Ei	Plokiahel ahelkontrolliks. Toetatud on ainult matchain. Saadaval Pro plaanis.

Näide

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

Vastus

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

Märkused

• Loeb sinu kuukvoodi vastu ühena (Free: 100/kuus, Starter: 1 000/kuus, Pro: 10 000/kuus). Kvoot lähtestub iga arveldusperioodi alguses.
• Parameeter blockchain on saadaval ainult Pro plaanis.

---

Loenda autasud

Hangi autasud valikulise filtreerimise ja lehendamisega.

GET /awards

Päringu parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
filter	JSON string	Ei	Filtri objekt (vt allpool)
lastEvaluatedKey	string	Ei	Lehendamise token eelmisest vastusest

Filtri objekt

Parameeter filter aktsepteerib JSON-stringi nende väljadega:

Väli	Tüüp	Kirjeldus
badgeId	string	Filtreeri märgi ID järgi.
search	string	Alamstring otsimiseks saajate nimedes või e-postides (vt searchField).
searchField	string	Kas name (vaikimisi) või email — millist veergu otsida.

Lehendamine lastEvaluatedKey-ga töötab filtritega või ilma. Lehe suurus on 50.

Näide — loenda kõik autasud

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

Näide — filtreeri märgi järgi

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"

Vastus

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

Kui lastEvaluatedKey on vastuses olemas, on rohkem tulemusi. Edasta see järgmises päringus päringu parameetrina, et saada järgmine leht.

---

Saada autasu e-kiri

Saada saajale teavitus-e-kiri tema autasu kohta.

POST /awards/{awardId}/send

Parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
awardId	string	Jah	Autasu ID (tee-parameeter ja keha)
email	string	Jah	Saaja e-posti aadress

Näide

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

Vastus

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

---

Jaga autasu

Jaga autasu mitme saajaga e-posti teel.

POST /awards/{awardId}/share

Parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
awardId	string	Jah	Autasu ID (tee-parameeter ja keha)
recipients	string	Jah	Komadega eraldatud e-posti aadresside loend
subject	string	Jah	E-kirja teemarida
message	string	Jah	E-kirja sõnumi keha

Näide

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

Vastus

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

---

Lae alla PDF-tunnistus

Genereeri autasu jaoks trükivalmis A4 PDF-tunnistus.

GET /awards/{awardGuid}/pdf

Autentimist pole vaja — see otspunkt on avalik, nii et saajad saavad oma tunnistuse ise alla laadida.

Näide

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

Vastus on binaarne PDF koos päisega Content-Type: application/pdf.

---

Jälgi autasu sündmust

Salvesta kaasatuse sündmus (vaatamine, jagamine, allalaadimine, LinkedIn-i lisamine). Kasutatakse avaliku autasu lehe poolt, et täita kaasatuse statistikat. Autentimist pole vaja.

POST /awards/{awardGuid}/event

Parameetrid

Parameeter	Tüüp	Nõutav	Kirjeldus
kind	string	Jah	Üks järgnevatest: view, share, download, linkedin_add.
network	string	Ei	Kui kind=share, siis sotsiaalvõrk: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP-põhine duplikaatide summutamine: sama tüüpi sündmus samast IP-st loetakse korra iga 24 tunni jooksul.

Näide

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

---

Hangi autasu statistika

Hangi autasu kumulatiivsed kaasatuse loendurid.

GET /awards/{awardGuid}/stats

Autentimist pole vaja.

Vastus

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