API Penghargaan

Buat dan kelola penghargaan lencana (assertion) — lencana yang diterbitkan kepada penerima tertentu.

Semua endpoint memerlukan autentikasi via tajuk X-Api-Key. Lihat Autentikasi.

Buat Penghargaan

Terbitkan lencana ke penerima.

POST /awards

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
badgeId	string	Ya	ID lencana yang akan diberikan
recipient	object	Ya	Detail penerima (lihat di bawah)
recipient.name	string	Ya	Nama lengkap penerima (minimum 5 karakter)
recipient.email	string	Ya	Alamat surel penerima
issuedOn	string	Ya	Tanggal terbit dalam format ISO 8601 (mis. 2025-01-15)
expires	string	Tidak	Tanggal kedaluwarsa dalam format ISO 8601
blockchain	string	Tidak	Blockchain untuk verifikasi on-chain. Hanya matchain yang didukung. Tersedia pada paket 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"
    }
  }'

Respons

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

Catatan

• Dihitung sebagai satu penghargaan terhadap kuota bulanan Anda (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Kuota diatur ulang setiap periode penagihan.
• Parameter blockchain hanya tersedia pada paket Pro.

---

Daftar Penghargaan

Ambil penghargaan dengan penyaringan dan paginasi opsional.

GET /awards

Parameter Kueri

Parameter	Tipe	Diperlukan	Deskripsi
filter	string JSON	Tidak	Objek filter (lihat di bawah)
lastEvaluatedKey	string	Tidak	Token paginasi dari respons sebelumnya

Objek Filter

Parameter filter menerima string JSON dengan bidang ini:

Bidang	Tipe	Deskripsi
badgeId	string	Filter berdasarkan ID lencana.
search	string	Substring untuk dicari di nama atau surel penerima (lihat searchField).
searchField	string	Salah satu name (default) atau email — kolom mana yang dicari.

Paginasi via lastEvaluatedKey bekerja dengan atau tanpa filter. Ukuran halaman adalah 50.

Contoh — Daftar Semua Penghargaan

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

Contoh — Filter berdasarkan 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"

Respons

{
  "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 ada dalam respons, ada hasil lebih banyak. Lewatkan sebagai parameter kueri di permintaan berikutnya untuk mendapatkan halaman berikutnya.

---

Kirim Surel Penghargaan

Kirim surel notifikasi ke penerima tentang penghargaan mereka.

POST /awards/{awardId}/send

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
awardId	string	Ya	ID penghargaan (parameter jalur dan badan)
email	string	Ya	Alamat surel 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"
    }
  }'

Respons

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

---

Bagikan Penghargaan

Bagikan penghargaan dengan beberapa penerima via surel.

POST /awards/{awardId}/share

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
awardId	string	Ya	ID penghargaan (parameter jalur dan badan)
recipients	string	Ya	Daftar alamat surel dipisahkan koma
subject	string	Ya	Baris subjek surel
message	string	Ya	Badan pesan surel

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

Respons

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

---

Unduh Sertifikat PDF

Hasilkan sertifikat PDF A4 siap cetak untuk penghargaan.

GET /awards/{awardGuid}/pdf

Tidak diperlukan autentikasi — endpoint ini publik sehingga penerima dapat mengunduh sertifikat mereka sendiri.

Contoh

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

Respons adalah PDF biner dengan tajuk Content-Type: application/pdf.

---

Lacak Peristiwa Penghargaan

Catat peristiwa keterlibatan (tampilan, berbagi, unduh, tambah LinkedIn). Digunakan oleh halaman penghargaan publik untuk mengisi statistik keterlibatan. Tidak diperlukan autentikasi.

POST /awards/{awardGuid}/event

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
kind	string	Ya	Salah satu dari view, share, download, linkedin_add.
network	string	Tidak	Saat kind=share, jaringan sosial: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

Penekanan duplikat per IP: jenis sama dari IP sama dihitung sekali per 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 Penghargaan

Ambil penghitung keterlibatan kumulatif untuk penghargaan.

GET /awards/{awardGuid}/stats

Tidak diperlukan autentikasi.

Respons

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