Awards API

Rozet ödüllerini (assertion) oluşturun ve yönetin — belirli alıcılara düzenlenen rozetler.

Tüm uç noktalar X-Api-Key başlığı aracılığıyla kimlik doğrulaması gerektirir. Kimlik Doğrulama sayfasına bakın.

Ödül Oluşturma

Bir alıcıya rozet düzenleyin.

POST /awards

Parametreler

Parametre	Tür	Gerekli	Açıklama
badgeId	string	Evet	Verilecek rozetin kimliği
recipient	object	Evet	Alıcı ayrıntıları (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 düzenleme tarihi (ör. 2025-01-15)
expires	string	Hayır	ISO 8601 biçiminde son kullanma tarihi
blockchain	string	Hayır	Zincir üstü doğrulama için blockchain. Yalnızca matchain desteklenir. Pro planında mevcuttur.

Ö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

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

Notlar

• Aylık kotaya karşı bir ödül olarak sayılır (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Kota her fatura döneminde sıfırlanır.
• blockchain parametresi yalnızca Pro planında kullanılabilir.

---

Ödülleri Listeleme

Opsiyonel filtreleme ve sayfalama ile ödülleri alın.

GET /awards

Sorgu Parametreleri

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

Filtre Nesnesi

filter parametresi şu alanlara sahip bir JSON dizesi kabul eder:

Alan	Tür	Açıklama
badgeId	string	Rozet kimliğine göre filtrele.
search	string	Alıcı adlarında ya da e-postalarında aranacak alt dize (searchField bölümüne bakın).
searchField	string	Ya name (varsayılan) ya da email — hangi sütunun arandığı.

lastEvaluatedKey ile sayfalama, filtrelerle ya da filtresiz çalışır. Sayfa boyutu 50'dir.

Örnek — Tüm Ödülleri Listele

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

Örnek — Rozete Göre Filtrele

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

{
  "statusCode": 200,
  "info": {
    "awards": [
      {
        "id": "https://api.badges.ninja/certify-badge/award/c1d2e3f4-...",
        "badge": {
          "id": "https://api.badges.ninja/certify-badge/badge/b1c2d3e4-...",
          "name": "JavaScript Fundamentals",
          "image": "https://ipfs.ninja/ipfs/Qm..."
        },
        "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 bulunuyorsa, daha fazla sonuç vardır. Sonraki sayfayı almak için bir sonraki istekte sorgu parametresi olarak gönderin.

---

Ödül E-postası Gönderme

Bir alıcıya ödülü hakkında e-posta bildirimi gönderir.

POST /awards/{awardId}/send

Parametreler

Parametre	Tür	Gerekli	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

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

---

Ödülü Paylaşma

Bir ödülü e-postayla birden çok alıcıyla paylaşır.

POST /awards/{awardId}/share

Parametreler

Parametre	Tür	Gerekli	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

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

---

PDF Sertifikasını İndirme

Bir ödül için yazdırmaya hazır A4 PDF sertifikası oluşturur.

GET /awards/{awardGuid}/pdf

Kimlik doğrulama gerektirmez — bu uç nokta kamuya açıktır, böylece alıcılar kendi sertifikalarını indirebilir.

Örnek

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

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

---

Ödül Etkinliğini İzleme

Bir etkileşim etkinliğini (view, share, download, LinkedIn add) kaydeder. Etkileşim istatistiklerini doldurmak için kamuya açık ödül sayfası tarafından kullanılır. Kimlik doğrulama gerektirmez.

POST /awards/{awardGuid}/event

Parametreler

Parametre	Tür	Gerekli	Açıklama
kind	string	Evet	Şunlardan biri: view, share, download, linkedin_add.
network	string	Hayır	kind=share olduğunda sosyal ağ: linkedin, twitter, facebook, whatsapp, telegram, email, copy.

IP başına yineleme bastırma: aynı IP'den aynı kind 24 saatte bir kez sayılır.

Örnek

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

---

Ödül İstatistiklerini Alma

Bir ödülün toplam etkileşim sayaçlarını alın.

GET /awards/{awardGuid}/stats

Kimlik doğrulama gerektirmez.

Yanıt

{
  "statusCode": 200,
  "info": {
    "stats": {
      "views": 142,
      "shares": { "linkedin": 8, "twitter": 2, "email": 1, "copy": 5 },
      "downloads": 3,
      "linkedin_adds": 4
    }
  }
}