Awards API

Kimlik bilgilerini (assertion) oluşturun ve yönetin — belirli alıcılara verilen rozetler.

Tüm endpoint'ler X-Api-Key başlığı ile kimlik doğrulaması gerektirir. Bkz. Kimlik Doğrulama.

Kimlik Bilgisi Oluşturma

Bir alıcıya rozet verin.

Kişi başına bir API çağrısı yapmak yerine yüzlerce veya binlerce alıcıya aynı anda mı vermeniz gerekiyor? CSV yüklemeyi kabul eden Toplu Kimlik Bilgileri arayüz özelliğini kullanın.

POST /awards

Parametreler

Parametre	Tür	Zorunlu	Açıklama
badgeId	string	Evet	Verilecek rozetin kimliği
recipient	object	Evet	Alıcı bilgileri (aşağıya bakın)
recipient.name	string	Evet	Alıcının tam adı (en az 5 karakter)
recipient.email	string	Evet	Alıcının e-posta adresi
issuedOn	string	Evet	ISO 8601 biçiminde veriliş tarihi (ör. 2025-01-15)
expires	string	Hayır	ISO 8601 biçiminde son kullanma tarihi

Örnek

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

Yanıt

{
  "awardId": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Notlar

• Yıllık kimlik bilgisi havuzunuzdan bir kimlik bilgisi sayılır (Free: yılda 1.200, Starter: yılda 12.000, Pro: yılda 120.000). Havuz esnek bir yıllık haktır — yıl boyunca dilediğiniz zaman, toplu kullanımlar dahil, harcayabilirsiniz — ve hesabınızın kayıt yıl dönümünde sıfırlanır. Faturalandırma aylık kalır; yalnızca kimlik bilgisi kotası yıllıktır. Ayrıntılar için Planlar ve Faturalandırma sayfasına bakın.

---

Kimlik Bilgilerini Listeleme

Kimlik bilgilerini isteğe bağlı filtreleme ve sayfalama ile alın.

GET /awards

Sorgu Parametreleri

Parametre	Tür	Zorunlu	Açıklama
filter	JSON string	Hayır	Filtre nesnesi (aşağıya bakın)
lastEvaluatedKey	string	Hayır	Önceki yanıttan gelen sayfalama belirteci

Filtre Nesnesi

filter parametresi şu alanları içeren bir JSON dizesi kabul eder:

Alan	Tür	Açıklama
badgeId	string	Rozet kimliğine göre filtreler.
search	string	Alıcı adlarında veya e-postalarında aranacak alt dize (bkz. searchField).
searchField	string	name (varsayılan) veya email — hangi sütunda arama yapılacağı.

lastEvaluatedKey ile sayfalama filtreli veya filtresiz çalışır. Sayfa boyutu 50'dir.

Örnek — Tüm Kimlik Bilgilerini Listeleme

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

Örnek — Rozete Göre Filtreleme

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"

Yanıt

{
  "count": 1,
  "items": [
    {
      "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
      "badge": {
        "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
        "name": "JavaScript Fundamentals",
        "image": "https://badges.ninja/images/{sha256}.png"
      },
      "recipient": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "issuedOn": "2025-01-15T00:00:00.000Z",
      "timestamp": "2025-01-15T10:30:00.000Z"
    }
  ],
  "lastEvaluatedKey": "eyJ..."
}

Yanıtta lastEvaluatedKey varsa daha fazla sonuç vardır. Sonraki sayfayı almak için bunu bir sonraki istekte sorgu parametresi olarak iletin.

---

Kimlik Bilgisi E-postası Gönderme

Alıcıya kimlik bilgisiyle ilgili bir e-posta bildirimi gönderin.

POST /awards/{awardId}/send

Parametreler

Parametre	Tür	Zorunlu	Açıklama
awardId	string	Evet	Ödül kimliği (yol parametresi ve gövde)
email	string	Evet	Alıcının e-posta adresi

Örnek

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

Yanıt

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

"email sent"

---

Kimlik Bilgisini Paylaşma

Bir kimlik bilgisini e-posta yoluyla birden fazla alıcıyla paylaşın.

POST /awards/{awardId}/share

Parametreler

Parametre	Tür	Zorunlu	Açıklama
awardId	string	Evet	Ödül kimliği (yol parametresi ve gövde)
recipients	string	Evet	Virgülle ayrılmış e-posta adresleri listesi
subject	string	Evet	E-posta konu satırı
message	string	Evet	E-posta mesaj gövdesi

Örnek

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

Yanıt

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

"email sent"

---

Kimlik Bilgisini İptal Etme

Verdiğiniz bir kimlik bilgisini iptal edin. Barındırılan Open Badges v2.0 assertion'ı revoked: true olarak işaretlenir (isteğe bağlı bir gerekçeyle); böylece herhangi bir doğrulayıcı rozetin artık geçerli olmadığını görür. Kimlik bilgisi kaydı denetim amacıyla saklanır ve kredi iadesi yapılmaz.

İptal, kimlik bilgisinin Open Badges 3.0 Verifiable Credential'ına da yayılır: ödülün biti, VC'nin credentialStatus alanında başvurulan W3C Bitstring Status List içinde çevrilir; böylece VC cüzdanları da bunu algılar. Bkz. İptal (Bitstring Status List).

POST /awards/{awardId}/revoke

Parametreler

Parametre	Tür	Zorunlu	Açıklama
awardId	string	Evet	Ödül kimliği (yol parametresi)
reason	string	Hayır	İptal gerekçesi. 500 karaktere kısaltılır.
notify	boolean	Hayır	true olduğunda, alıcıya kimlik bilgisinin iptal edildiğini e-postayla bildirir. Varsayılan false'tur.

Örnek

curl -X POST https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012/revoke \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012",
      "reason": "Issued to the wrong recipient",
      "notify": true
    }
  }'

Yanıt

{
  "revoked": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

Zaten iptal edilmiş bir kimlik bilgisini yeniden iptal etmek idempotent'tir — bildirimi tekrar göndermeden aynı yanıtı döndürür.

Toplu iptal

Çok sayıda kimlik bilgisini aynı anda iptal etmek için, bu endpoint'i ödül başına çağırmak yerine action: "revoke" ile kalıcı toplu endpoint'i kullanın:

curl -X POST https://api.badges.ninja/awards/bulk-send \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "parameters": { "action": "revoke", "awardIds": ["<id1>", "<id2>"], "reason": "Program cancelled", "notify": false } }'

{ "jobId", "total" } döndürür; iş her kimliği sunucu tarafında iptal eder (zaten iptal edilmiş olanları atlar) ve devam ettirilebilir. Zaten iptal edilmiş ve var olmayan kimlikler atlanmış olarak raporlanır.

---

Kimlik Bilgisini Silme

Verdiğiniz bir kimlik bilgisini kalıcı olarak silin. İptalden farklı olarak kaydı tamamen kaldırır ve herkese açık kimlik bilgisi sayfası 404 döndürür. Bunu gerçek hatalar için kullanın (ör. yanlış kişiye verilmesi); gerçek kimlik bilgilerinde assertion'ın iptal edilmiş olarak doğrulanabilir kalması için iptal'i tercih edin. Kredi iadesi yapılmaz.

DELETE /awards/{awardId}

Parametreler

Parametre	Tür	Zorunlu	Açıklama
awardId	string	Evet	Ödül kimliği (yol parametresi)

Örnek

curl -X DELETE https://api.badges.ninja/awards/c1d2e3f4-a5b6-7890-cdef-123456789012 \
  -H "X-Api-Key: bws_your_api_key_here"

Yanıt

{
  "deleted": true,
  "awardId": "c1d2e3f4-a5b6-7890-cdef-123456789012"
}

---

PDF Sertifikası İndirme

Bir kimlik bilgisi için yazdırmaya hazır A4 PDF sertifikası oluşturun.

GET /certify-badge/award/{awardGuid}/pdf

Kimlik doğrulaması gerekmez — bu endpoint herkese açıktır, böylece alıcılar kendi sertifikalarını indirebilir.

Örnek

curl -OJ https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/pdf

Yanıt, Content-Type: application/pdf başlığıyla birlikte ikili PDF'tir.

---

Kimlik Bilgisi Olayını İzleme

Bir etkileşim olayı kaydedin. Herkese açık kimlik bilgisi sayfası tarafından etkileşim istatistiklerini doldurmak için kullanılır. Kimlik doğrulaması gerekmez.

POST /certify-badge/award/{awardGuid}/event

Parametreler

Bu endpoint gövdeyi doğrudan okur (parameters sarmalayıcısı yoktur).

Parametre	Tür	Zorunlu	Açıklama
event	string	Evet	view, share, download, click_linkedin_addtoprofile, click_pdf, click_verify değerlerinden biri.
network	string	Hayır	event=share olduğunda sosyal ağ: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP başına mükerrer olay engelleme: aynı IP'den gelen aynı olay 24 saatte bir kez sayılır.

Örnek

curl -X POST https://api.badges.ninja/certify-badge/award/c1d2e3f4-a5b6-7890-cdef-123456789012/event \
  -H "Content-Type: application/json" \
  -d '{"event": "share", "network": "linkedin"}'

Yanıt

{
  "ok": true
}

---

Kimlik Bilgisi İstatistiklerini Alma

Bir kimlik bilgisinin kümülatif etkileşim sayaçlarını alın.

GET /certify-badge/award/{awardGuid}/stats

Kimlik doğrulaması gerekmez.

Yanıt

Sayaçlar ham olay türüne göre anahtarlanarak döndürülür. totals her olay için toplam sayıyı tutar; networks ise network taşıyan olaylar için (şu anda share) ağ bazında dökümü verir. Kaydedilmiş etkinliği olmayan olaylar yanıtta yer almaz.

{
  "totals": {
    "view": 142,
    "share": 16,
    "download": 3,
    "click_linkedin_addtoprofile": 4
  },
  "networks": {
    "share": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 }
  }
}