API Lencana

Urus templat lencana — kelayakan yang anda anugerahkan kepada penerima.

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

Cipta Lencana

Cipta lencana baharu di bawah pengeluar yang disahkan.

POST /badges

Parameter

Parameter	Jenis	Diperlukan	Penerangan
name	string	Ya	Tajuk lencana
description	string	Ya	Apa yang diwakili oleh lencana
criteria	string	Ya	Apa yang penerima lakukan untuk mendapatkan lencana ini
image	string	Ya	Imej berkod Base64 (PNG atau JPG)
issuerId	string	Ya	ID pengeluar yang disahkan

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

Tindak Balas

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

Nota

• Pengeluar mestilah disahkan sebelum mencipta lencana.
• Imej dimuat naik ke IPFS untuk storan kekal.

---

Senaraikan Lencana

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"

Tindak Balas

{
  "statusCode": 200,
  "info": {
    "badges": [
      {
        "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://ipfs.ninja/ipfs/Qm...",
        "issuer": "https://api.badges.ninja/certify-badge/issuer/a1b2c3d4-...",
        "timestamp": "2025-01-15T10:30:00.000Z"
      }
    ]
  }
}

---

Kemas Kini Lencana

Kemas kini lencana sedia ada. Hanya medan yang anda berikan 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

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

Tindak Balas

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

---

Kemas Kini Teks Perkongsian

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

Tindak Balas

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

---

Padam Lencana

Padam lencana. Lencana mestilah tidak mempunyai anugerah.

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"

Tindak Balas

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

Ralat

• 400 — lencana mempunyai anugerah dan tidak boleh dipadam
• 404 — lencana tidak ditemui