Awards API

Kimlik bilgilerini (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.

Kimlik Bilgisi 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

Ö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 kimlik bilgisi olarak sayılır (Free: 100/mo, Starter: 1,000/mo, Pro: 10,000/mo). Kota her fatura döneminde sıfırlanır.

---

Kimlik Bilgilerini Listeleme

Opsiyonel filtreleme ve sayfalama ile kimlik bilgilerini 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 Kimlik Bilgilerini 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.

---

Kimlik Bilgisi E-postası Gönderme

Bir alıcıya kimlik bilgisi 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
  }
}

---

Kimlik Bilgisini Paylaşma

Bir kimlik bilgisini 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 kimlik bilgisi 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.

---

Kimlik Bilgisi Etkinliğini İzleme

Bir etkileşim etkinliğini (view, share, download, LinkedIn add) kaydeder. Etkileşim istatistiklerini doldurmak için kamuya açık kimlik bilgisi 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"}}'

---

Kimlik Bilgisi İstatistiklerini Alma

Bir kimlik bilgisinin 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
    }
  }
}