Referensi API Lencana: Buat, Verifikasi & Ambil Lencana

Kelola templat lencana — kredensial yang Anda terbitkan kepada penerima.

Untuk menerbitkan lencana ini kepada banyak penerima sekaligus melalui unggahan CSV, bukan melalui API, lihat Kredensial Massal.

Semua endpoint memerlukan autentikasi melalui header X-Api-Key. Lihat Autentikasi.

Buat Lencana

Buat lencana baru di bawah penerbit yang telah diverifikasi.

POST /badges

Parameter

Parameter	Tipe	Wajib	Deskripsi
name	string	Ya	Judul lencana
description	string	Ya	Apa yang diwakili oleh lencana
criteria	string	Ya	Apa yang dilakukan penerima untuk mendapatkan lencana ini
image	string	Ya	Gambar berenkode Base64 (PNG atau JPG)
issuerId	string	Ya	ID penerbit yang telah diverifikasi
shareText	string	Tidak	Teks berbagi sosial default untuk lencana ini. Mendukung placeholder , , dan . Menggunakan default bawaan jika dihilangkan.
designJson	string	Tidak	Dokumen perancang lencana yang diserialisasi, disimpan agar lencana dapat diedit ulang lapisan demi lapisan di kemudian hari.

Contoh

curl -X POST https://api.badges.ninja/badges \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "name": "JavaScript Fundamentals",
      "description": "Demonstrates proficiency in core JavaScript concepts",
      "criteria": "Completed the JavaScript Fundamentals course with a score of 80% or higher",
      "image": "data:image/png;base64,iVBORw0KGgo...",
      "issuerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }'

Respons

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-f5a6-7890-bcde-f12345678901"
}

Catatan

• Penerbit harus diverifikasi sebelum membuat lencana.
• Gambar disimpan di Amazon S3 dan disajikan melalui CDN global kami di bawah URL yang tidak dapat diubah dan beralamat konten (content-addressed).
• Setelah kelas lencana dibuat, terbitkan kepada penerima menggunakan API Kredensial.

---

Daftar Lencana

Ambil semua lencana yang telah Anda buat.

GET /badges

Contoh

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

Respons

[
  {
    "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
    "name": "JavaScript Fundamentals",
    "description": "Demonstrates proficiency in core JavaScript concepts",
    "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
    "image": "https://badges.ninja/images/{sha256}.png",
    "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
]

---

Ambil Lencana

Ambil satu lencana, termasuk teks berbagi dan dokumen perancang lencana yang diserialisasi (designJson). Ini adalah endpoint yang digunakan modal Edit Lencana untuk memuat ulang setiap lapisan; endpoint daftar tidak menyertakan designJson agar respons tetap ringan.

GET /badges/{badgeId}

Parameter

Parameter	Tipe	Wajib	Deskripsi
badgeId	string	Ya	ID lencana (parameter path)

Contoh

curl -X GET https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Respons

{
  "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "name": "JavaScript Fundamentals",
  "description": "Demonstrates proficiency in core JavaScript concepts",
  "criteria": { "narrative": "Completed the JavaScript Fundamentals course..." },
  "image": "https://badges.ninja/images/{sha256}.png",
  "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
  "shareText": "Excited to share that I just received the \"{{badge_name}}\" certification!",
  "designJson": "{ ...serialized designer document... }",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Teks berbagi selalu disertakan. Varian daftar yang lebih ringan, GET /badges?badgeId={id}, mengembalikan dokumen yang sama tanpa designJson, dan hanya menyertakan teks berbagi bila dipanggil dengan includeShareText=true.

---

Perbarui Lencana

Perbarui lencana yang sudah ada. Hanya kolom yang Anda berikan yang diubah.

PUT /badges/{badgeId}

Parameter

Parameter	Tipe	Wajib	Deskripsi
badgeId	string	Ya	ID lencana (parameter path)
name	string	Tidak	Judul lencana baru
description	string	Tidak	Deskripsi baru
criteria	string	Tidak	Kriteria baru
image	string	Tidak	Gambar berenkode Base64 yang baru
designJson	string	Tidak	Dokumen perancang lencana terserialisasi yang baru.

Contoh

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "name": "JavaScript Fundamentals v2",
      "description": "Updated description for the JS badge"
    }
  }'

Respons

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
  "updated": true
}

---

Perbarui Teks Berbagi

Tetapkan teks kustom yang ditampilkan saat penerima membagikan lencana ini di media sosial.

PUT /badges/{badgeId}/share-text

Parameter

Parameter	Tipe	Wajib	Deskripsi
badgeId	string	Ya	ID lencana (parameter path)
text	string	Ya	Teks berbagi (HTML tidak diizinkan)

Contoh

curl -X PUT https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901/share-text \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "badgeId": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
      "text": "I just earned the JavaScript Fundamentals badge! Check it out:"
    }
  }'

Respons

{
  "badgeId": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-..."
}

---

Hapus Lencana

Hapus lencana. Lencana tidak boleh memiliki kredensial.

DELETE /badges/{badgeId}

Contoh

curl -X DELETE https://api.badges.ninja/badges/b1c2d3e4-f5a6-7890-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

Respons

Mengembalikan string konfirmasi biasa:

"badge has been deleted"

Kesalahan

• 400 — lencana masih memiliki kredensial yang diterbitkan: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — lencana tidak ditemukan