Myönnöt-API

Luo ja hallitse merkkimyöntöjä (assertions) — tietyille vastaanottajille myönnettyjä merkkejä.

Kaikki päätepisteet vaativat todennuksen X-Api-Key-otsikon kautta. Katso Todennus.

Luo myöntö

Myönnä merkki vastaanottajalle.

POST /awards

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
badgeId	string	Kyllä	Myönnettävän merkin ID
recipient	object	Kyllä	Vastaanottajan tiedot (katso alla)
recipient.name	string	Kyllä	Vastaanottajan täysi nimi (vähintään 5 merkkiä)
recipient.email	string	Kyllä	Vastaanottajan sähköpostiosoite
issuedOn	string	Kyllä	Myöntöpäivä ISO 8601 -muodossa (esim. 2025-01-15)
expires	string	Ei	Vanhenemispäivä ISO 8601 -muodossa
blockchain	string	Ei	Blockchain on-chain-varmistukseen. Vain matchain on tuettu. Saatavilla Pro-tilauksessa.

Esimerkki

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

Vastaus

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

Huomautuksia

• Lasketaan yhdeksi myönnöksi kuukausikiintiöstäsi (Free: 100/kk, Starter: 1 000/kk, Pro: 10 000/kk). Kiintiö nollautuu jokaisella laskutuskaudella.
• Parametri blockchain on saatavilla vain Pro-tilauksessa.

---

Listaa myönnöt

Hae myöntöjä valinnaisella suodatuksella ja sivutuksella.

GET /awards

Kyselyparametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
filter	JSON-merkkijono	Ei	Suodatusobjekti (katso alla)
lastEvaluatedKey	string	Ei	Sivutustoken edellisestä vastauksesta

Suodatusobjekti

Parametri filter hyväksyy JSON-merkkijonon näillä kentillä:

Kenttä	Tyyppi	Kuvaus
badgeId	string	Suodata merkin IDllä.
search	string	Osamerkkijono, jota etsitään vastaanottajien nimistä tai sähköposteista (katso searchField).
searchField	string	Joko name (oletus) tai email — mitä saraketta etsitään.

Sivutus lastEvaluatedKey-tokenilla toimii suodattimien kanssa tai ilman. Sivukoko on 50.

Esimerkki — Listaa kaikki myönnöt

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

Esimerkki — Suodata merkin mukaan

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"

Vastaus

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

Jos lastEvaluatedKey on läsnä vastauksessa, on lisää tuloksia. Välitä se kyselyparametrina seuraavassa pyynnössä saadaksesi seuraavan sivun.

---

Lähetä myöntösähköposti

Lähetä sähköposti-ilmoitus vastaanottajalle hänen myönnöstään.

POST /awards/{awardId}/send

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Myönnön ID (polun parametri ja runko)
email	string	Kyllä	Vastaanottajan sähköpostiosoite

Esimerkki

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

Vastaus

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

---

Jaa myöntö

Jaa myöntö useiden vastaanottajien kanssa sähköpostitse.

POST /awards/{awardId}/share

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
awardId	string	Kyllä	Myönnön ID (polun parametri ja runko)
recipients	string	Kyllä	Pilkuilla erotettu luettelo sähköpostiosoitteista
subject	string	Kyllä	Sähköpostin aihe
message	string	Kyllä	Sähköpostin viestiteksti

Esimerkki

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

Vastaus

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

---

Lataa PDF-todistus

Luo tulostusvalmis A4-PDF-todistus myönnölle.

GET /awards/{awardGuid}/pdf

Todennusta ei vaadita — tämä päätepiste on julkinen, jotta vastaanottajat voivat ladata oman todistuksensa.

Esimerkki

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

Vastaus on binäärinen PDF otsikolla Content-Type: application/pdf.

---

Seuraa myöntötapahtumaa

Rekisteröi sitoutumistapahtuma (katselu, jakaminen, lataus, LinkedIn-lisäys). Käytetään julkisella myöntösivulla sitoutumistilastojen täyttämiseen. Todennusta ei vaadita.

POST /awards/{awardGuid}/event

Parametrit

Parametri	Tyyppi	Pakollinen	Kuvaus
kind	string	Kyllä	Yksi seuraavista: view, share, download, linkedin_add.
network	string	Ei	Kun kind=share, sosiaalinen verkosto: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Kaksoiskappaleiden estäminen per IP: sama kind samasta IP:stä lasketaan kerran per 24 tuntia.

Esimerkki

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

---

Hae myöntötilastot

Hae myönnön kumulatiiviset sitoutumislaskurit.

GET /awards/{awardGuid}/stats

Todennusta ei vaadita.

Vastaus

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