API Kredensial

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

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

Buat Kredensial

Terbitkan lencana ke penerima.

POST /awards

Parameter

Parameter	Tipe	Diperlukan	Deskripsi
badgeId	string	Ya	ID lencana yang akan diterbitkan
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

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 kredensial terhadap kuota bulanan Anda (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Kuota diatur ulang setiap periode penagihan.

---

Daftar Kredensial

Ambil kredensial 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 Kredensial

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 Kredensial

Kirim surel notifikasi ke penerima tentang kredensial 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 Kredensial

Bagikan kredensial 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 kredensial.

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 Kredensial

Catat peristiwa keterlibatan (tampilan, berbagi, unduh, tambah LinkedIn). Digunakan oleh halaman kredensial 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 Kredensial

Ambil penghitung keterlibatan kumulatif untuk kredensial.

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