Awards API

Izveidojiet un pārvaldiet nozīmju apbalvojumus (assertions) — nozīmes, kas izsniegtas konkrētiem saņēmējiem.

Visi galapunkti prasa autentifikāciju caur galveni X-Api-Key. Skatiet Autentifikācija.

Izveidot apbalvojumu

Pasniegt nozīmi saņēmējam.

POST /awards

Parametri

Parametrs	Tips	Obligāts	Apraksts
badgeId	string	Jā	Pasniedzamās nozīmes ID
recipient	object	Jā	Saņēmēja detaļas (skatīt zemāk)
recipient.name	string	Jā	Saņēmēja pilns vārds (vismaz 5 rakstzīmes)
recipient.email	string	Jā	Saņēmēja e-pasta adrese
issuedOn	string	Jā	Izsniegšanas datums ISO 8601 formātā (piemēram, 2025-01-15)
expires	string	Nē	Derīguma beigu datums ISO 8601 formātā
blockchain	string	Nē	Blokķēde ķēdes pārbaudei. Atbalstīts tikai matchain. Pieejams Pro plānā.

Piemērs

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

Atbilde

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

Piezīmes

• Skaitās kā viens apbalvojums pret jūsu ikmēneša kvotu (Free: 100/mēn, Starter: 1 000/mēn, Pro: 10 000/mēn). Kvota tiek atiestatīta katra norēķinu perioda sākumā.
• Parametrs blockchain ir pieejams tikai Pro plānā.

---

Uzskaitīt apbalvojumus

Iegūt apbalvojumus ar izvēles filtrēšanu un lapošanu.

GET /awards

Vaicājuma parametri

Parametrs	Tips	Obligāts	Apraksts
filter	JSON virkne	Nē	Filtra objekts (skatīt zemāk)
lastEvaluatedKey	string	Nē	Lapošanas tokens no iepriekšējās atbildes

Filtra objekts

Parametrs filter pieņem JSON virkni ar šiem laukiem:

Lauks	Tips	Apraksts
badgeId	string	Filtrēt pēc nozīmes ID.
search	string	Apakšvirkne meklēšanai saņēmēju vārdos vai e-pastos (skatīt searchField).
searchField	string	Vai nu name (noklusējums), vai email — kuru kolonnu meklēt.

Lapošana, izmantojot lastEvaluatedKey, darbojas ar filtriem vai bez tiem. Lapas izmērs ir 50.

Piemērs — uzskaitīt visus apbalvojumus

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

Piemērs — filtrēt pēc nozīmes

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"

Atbilde

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

Ja lastEvaluatedKey atrodas atbildē, ir vairāk rezultātu. Nodot to kā vaicājuma parametru nākamajā pieprasījumā, lai iegūtu nākamo lapu.

---

Sūtīt apbalvojuma e-pastu

Sūtīt saņēmējam paziņojuma e-pastu par viņa apbalvojumu.

POST /awards/{awardId}/send

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs un pamatteksts)
email	string	Jā	Saņēmēja e-pasta adrese

Piemērs

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

Atbilde

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

---

Dalīties ar apbalvojumu

Dalīties ar apbalvojumu ar vairākiem saņēmējiem pa e-pastu.

POST /awards/{awardId}/share

Parametri

Parametrs	Tips	Obligāts	Apraksts
awardId	string	Jā	Apbalvojuma ID (ceļa parametrs un pamatteksts)
recipients	string	Jā	Ar komatiem atdalītu e-pasta adrešu saraksts
subject	string	Jā	E-pasta tēmas rinda
message	string	Jā	E-pasta ziņojuma pamatteksts

Piemērs

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

Atbilde

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

---

Lejupielādēt PDF sertifikātu

Ģenerēt drukai gatavu A4 PDF sertifikātu apbalvojumam.

GET /awards/{awardGuid}/pdf

Autentifikācija nav nepieciešama — šis galapunkts ir publisks, lai saņēmēji varētu lejupielādēt savu sertifikātu.

Piemērs

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

Atbilde ir binārais PDF ar galveni Content-Type: application/pdf.

---

Izsekot apbalvojuma notikumu

Reģistrēt iesaistes notikumu (skats, dalīšanās, lejupielāde, LinkedIn pievienošana). Izmanto publiskā apbalvojuma lapa, lai aizpildītu iesaistes statistiku. Autentifikācija nav nepieciešama.

POST /awards/{awardGuid}/event

Parametri

Parametrs	Tips	Obligāts	Apraksts
kind	string	Jā	Viens no: view, share, download, linkedin_add.
network	string	Nē	Kad kind=share, sociālais tīkls: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP dublikātu nomākšana: tas pats veids no tā paša IP tiek skaitīts vienreiz 24 stundās.

Piemērs

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

---

Iegūt apbalvojuma statistiku

Iegūt apbalvojuma kumulatīvos iesaistes skaitītājus.

GET /awards/{awardGuid}/stats

Autentifikācija nav nepieciešama.

Atbilde

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