Rujukan API Lencana: Cipta, Sahkan & Dapatkan Lencana

Urus templat lencana — kelayakan yang anda keluarkan kepada penerima.

Untuk mengeluarkan lencana ini kepada ramai penerima sekaligus melalui muat naik CSV dan bukannya API, lihat Kelayakan Pukal.

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

Create Badge

Cipta lencana baharu di bawah pengeluar yang telah disahkan.

POST /badges

Parameter

Parameter	Jenis	Diperlukan	Penerangan
name	string	Ya	Tajuk lencana
description	string	Ya	Perkara yang diwakili oleh lencana
criteria	string	Ya	Perkara yang dilakukan penerima untuk memperoleh lencana ini
image	string	Ya	Imej berkod Base64 (PNG atau JPG)
issuerId	string	Ya	ID pengeluar yang telah disahkan
shareText	string	Tidak	Teks perkongsian sosial lalai untuk lencana ini. Menyokong pemegang tempat , dan . Menggunakan lalai terbina dalam jika diabaikan.
designJson	string	Tidak	Dokumen pereka lencana yang diserikan, disimpan supaya lencana boleh disunting semula lapisan demi lapisan kemudian.

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

Nota

• Pengeluar mesti disahkan sebelum mencipta lencana.
• Imej disimpan pada Amazon S3 dan disampaikan melalui CDN global kami di bawah URL tidak berubah yang dialamatkan mengikut kandungan.
• Setelah kelas lencana wujud, keluarkan kepada penerima menggunakan API Kelayakan.

---

List Badges

Dapatkan semua lencana yang telah anda cipta.

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

---

Get Badge

Dapatkan satu lencana, termasuk teks perkongsiannya dan dokumen pereka lencana yang diserikan (designJson). Ini ialah titik akhir yang digunakan modal Edit Badge untuk memulihkan lapisan individu; titik akhir senarai tidak menyertakan designJson bagi memastikan respons ringkas.

GET /badges/{badgeId}

Parameter

Parameter	Jenis	Diperlukan	Penerangan
badgeId	string	Ya	ID lencana (parameter laluan)

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 perkongsian sentiasa disertakan. Varian senarai yang lebih ringan GET /badges?badgeId={id} memulangkan dokumen yang sama tanpa designJson, dan hanya menyertakan teks perkongsian apabila dipanggil dengan includeShareText=true.

---

Update Badge

Kemas kini lencana sedia ada. Hanya medan yang anda berikan akan diubah.

PUT /badges/{badgeId}

Parameter

Parameter	Jenis	Diperlukan	Penerangan
badgeId	string	Ya	ID lencana (parameter laluan)
name	string	Tidak	Tajuk lencana baharu
description	string	Tidak	Penerangan baharu
criteria	string	Tidak	Kriteria baharu
image	string	Tidak	Imej berkod base64 baharu
designJson	string	Tidak	Dokumen pereka lencana yang diserikan yang baharu.

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
}

---

Update Share Text

Tetapkan teks tersuai yang dipaparkan apabila penerima berkongsi lencana ini di media sosial.

PUT /badges/{badgeId}/share-text

Parameter

Parameter	Jenis	Diperlukan	Penerangan
badgeId	string	Ya	ID lencana (parameter laluan)
text	string	Ya	Teks perkongsian (HTML tidak dibenarkan)

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

---

Delete Badge

Padam lencana. Lencana tersebut mestilah tidak mempunyai kelayakan.

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

Memulangkan rentetan pengesahan biasa:

"badge has been deleted"

Ralat

• 400 — lencana masih mempunyai kelayakan yang telah dikeluarkan: "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 ditemui