API Anugerah

Cipta dan urus anugerah lencana (assertion) — lencana yang dikeluarkan kepada penerima tertentu.

Semua endpoint memerlukan pengesahan melalui pengepala X-Api-Key. Lihat Pengesahan.

Cipta Anugerah

Keluarkan lencana kepada penerima.

POST /awards

Parameter

Parameter	Jenis	Diperlukan	Penerangan
badgeId	string	Ya	ID lencana untuk dianugerahkan
recipient	object	Ya	Butiran penerima (lihat di bawah)
recipient.name	string	Ya	Nama penuh penerima (minimum 5 aksara)
recipient.email	string	Ya	Alamat e-mel penerima
issuedOn	string	Ya	Tarikh keluaran dalam format ISO 8601 (cth. 2025-01-15)
expires	string	Tidak	Tarikh tamat tempoh dalam format ISO 8601
blockchain	string	Tidak	Blockchain untuk pengesahan on-chain. Hanya matchain disokong. Tersedia pada pelan Pro.

Contoh

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

Tindak Balas

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

Nota

• Dikira sebagai satu anugerah daripada kuota bulanan anda (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Kuota ditetapkan semula setiap tempoh pengebilan.
• Parameter blockchain hanya tersedia pada pelan Pro.

---

Senaraikan Anugerah

Dapatkan anugerah dengan penapisan dan halaman pilihan.

GET /awards

Parameter Pertanyaan

Parameter	Jenis	Diperlukan	Penerangan
filter	rentetan JSON	Tidak	Objek penapis (lihat di bawah)
lastEvaluatedKey	string	Tidak	Token halaman daripada tindak balas sebelumnya

Objek Penapis

Parameter filter menerima rentetan JSON dengan medan ini:

Medan	Jenis	Penerangan
badgeId	string	Tapis mengikut ID lencana.
search	string	Substring untuk dicari sama ada dalam nama atau e-mel penerima (lihat searchField).
searchField	string	Sama ada name (lalai) atau email — lajur mana untuk dicari.

Halaman melalui lastEvaluatedKey berfungsi dengan atau tanpa penapis. Saiz halaman ialah 50.

Contoh — Senaraikan Semua Anugerah

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

Contoh — Tapis mengikut Lencana

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"

Tindak Balas

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

Jika lastEvaluatedKey hadir dalam tindak balas, terdapat lebih banyak hasil. Hantarnya sebagai parameter pertanyaan dalam permintaan seterusnya untuk mendapatkan halaman seterusnya.

---

Hantar E-mel Anugerah

Hantar e-mel pemberitahuan kepada penerima mengenai anugerah mereka.

POST /awards/{awardId}/send

Parameter

Parameter	Jenis	Diperlukan	Penerangan
awardId	string	Ya	ID anugerah (parameter laluan dan badan)
email	string	Ya	Alamat e-mel penerima

Contoh

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

Tindak Balas

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

---

Kongsi Anugerah

Kongsi anugerah dengan berbilang penerima melalui e-mel.

POST /awards/{awardId}/share

Parameter

Parameter	Jenis	Diperlukan	Penerangan
awardId	string	Ya	ID anugerah (parameter laluan dan badan)
recipients	string	Ya	Senarai alamat e-mel dipisahkan koma
subject	string	Ya	Baris subjek e-mel
message	string	Ya	Badan mesej e-mel

Contoh

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

Tindak Balas

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

---

Muat Turun Sijil PDF

Jana sijil PDF A4 sedia cetak untuk anugerah.

GET /awards/{awardGuid}/pdf

Tiada pengesahan diperlukan — endpoint ini awam supaya penerima boleh memuat turun sijil mereka sendiri.

Contoh

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

Tindak balas ialah PDF binari dengan pengepala Content-Type: application/pdf.

---

Jejak Peristiwa Anugerah

Rekodkan peristiwa penglibatan (paparan, perkongsian, muat turun, tambah LinkedIn). Digunakan oleh halaman anugerah awam untuk mengisi statistik penglibatan. Tiada pengesahan diperlukan.

POST /awards/{awardGuid}/event

Parameter

Parameter	Jenis	Diperlukan	Penerangan
kind	string	Ya	Salah satu daripada view, share, download, linkedin_add.
network	string	Tidak	Apabila kind=share, rangkaian sosial: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Penindasan pendua setiap IP: jenis sama daripada IP sama dikira sekali setiap 24 jam.

Contoh

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

---

Dapatkan Statistik Anugerah

Dapatkan pembilang penglibatan kumulatif untuk anugerah.

GET /awards/{awardGuid}/stats

Tiada pengesahan diperlukan.

Tindak Balas

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