Badges API Referansı: Rozet Oluşturma, Doğrulama ve Getirme

Rozet şablonlarını yönetin — alıcılara verdiğiniz kimlik bilgileri.

Bu rozeti API yerine CSV yükleyerek aynı anda birçok alıcıya vermek için bkz. Toplu Kimlik Bilgileri.

Tüm uç noktalar X-Api-Key başlığı ile kimlik doğrulaması gerektirir. Bkz. Kimlik Doğrulama.

Rozet Oluştur

Doğrulanmış bir düzenleyici altında yeni bir rozet oluşturun.

POST /badges

Parametreler

Parametre	Tür	Zorunlu	Açıklama
name	string	Evet	Rozet başlığı
description	string	Evet	Rozetin neyi temsil ettiği
criteria	string	Evet	Alıcının bu rozeti kazanmak için yaptığı şey
image	string	Evet	Base64 kodlu görsel (PNG veya JPG)
issuerId	string	Evet	Doğrulanmış düzenleyicinin ID'si
shareText	string	Hayır	Bu rozet için varsayılan sosyal paylaşım metni. , ve yer tutucularını destekler. Belirtilmezse yerleşik bir varsayılan kullanılır.
designJson	string	Hayır	Rozetin daha sonra katman katman yeniden düzenlenebilmesi için saklanan, serileştirilmiş rozet tasarımcısı belgesi.

Örnek

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

Yanıt

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

Notlar

• Rozet oluşturmadan önce düzenleyicinin doğrulanmış olması gerekir.
• Görsel Amazon S3'te saklanır ve değiştirilemez, içeriğe göre adreslenen bir URL altında küresel CDN'imiz üzerinden sunulur.
• Bir badge class oluşturulduktan sonra, Credentials API ile alıcılara verin.

---

Rozetleri Listele

Oluşturduğunuz tüm rozetleri alın.

GET /badges

Örnek

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

Yanıt

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

---

Rozeti Getir

Tek bir rozeti, paylaşım metni ve serileştirilmiş rozet tasarımcısı belgesi (designJson) dahil olarak alın. Rozet Düzenle penceresi, tek tek katmanları yeniden yüklemek için bu uç noktayı kullanır; yanıtları hafif tutmak için liste uç noktası designJson alanını içermez.

GET /badges/{badgeId}

Parametreler

Parametre	Tür	Zorunlu	Açıklama
badgeId	string	Evet	Rozet ID'si (yol parametresi)

Örnek

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

Yanıt

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

Paylaşım metni her zaman dahil edilir. Daha hafif GET /badges?badgeId={id} liste varyantı aynı belgeyi designJson olmadan döndürür ve paylaşım metnini yalnızca includeShareText=true ile çağrıldığında içerir.

---

Rozeti Güncelle

Mevcut bir rozeti güncelleyin. Yalnızca sağladığınız alanlar değişir.

PUT /badges/{badgeId}

Parametreler

Parametre	Tür	Zorunlu	Açıklama
badgeId	string	Evet	Rozet ID'si (yol parametresi)
name	string	Hayır	Yeni rozet başlığı
description	string	Hayır	Yeni açıklama
criteria	string	Hayır	Yeni kriterler
image	string	Hayır	Yeni base64 kodlu görsel
designJson	string	Hayır	Yeni serileştirilmiş rozet tasarımcısı belgesi.

Örnek

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

Yanıt

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

---

Paylaşım Metnini Güncelle

Alıcılar bu rozeti sosyal medyada paylaştığında gösterilen özel metni ayarlayın.

PUT /badges/{badgeId}/share-text

Parametreler

Parametre	Tür	Zorunlu	Açıklama
badgeId	string	Evet	Rozet ID'si (yol parametresi)
text	string	Evet	Paylaşım metni (HTML kullanılamaz)

Örnek

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

Yanıt

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

---

Rozeti Sil

Bir rozeti silin. Rozetin hiç kimlik bilgisi olmamalıdır.

DELETE /badges/{badgeId}

Örnek

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

Yanıt

Düz bir onay dizesi döndürür:

"badge has been deleted"

Hatalar

• 400 — rozetin hâlâ verilmiş kimlik bilgileri var: "This badge still has issued awards. Remove them first from the Awards page (revoke or delete each award), then delete the badge."
• 404 — rozet bulunamadı